From dbf6905aac5db0ff9ba20a0a6099d55f659886a7 Mon Sep 17 00:00:00 2001 From: qicosmos Date: Mon, 21 Aug 2023 16:40:09 +0800 Subject: [PATCH] [easylog][doc]add doc for easylog (#419) --- README.md | 12 +- website/docs/en/index.md | 8 +- .../docs/zh/easylog/easylog introduction.md | 108 ++++++++++++++++++ website/docs/zh/index.md | 8 +- 4 files changed, 122 insertions(+), 14 deletions(-) create mode 100644 website/docs/zh/easylog/easylog introduction.md diff --git a/README.md b/README.md index 828391e64..60f4c353d 100644 --- a/README.md +++ b/README.md @@ -25,7 +25,7 @@ The target of yaLanTingLibs: provide very easy and high performance modern C++ l # Quick Start ## compiler requirements -If your compiler don't support C++20, yalantinglibs will only compile the serialization libraries (struct_pack, struct_json, struct_xml, struct_yaml). +If your compiler don't support C++20, yalantinglibs will only compile the serialization libraries (struct_pack, struct_json, struct_xml, struct_yaml, easylog support C++17). Make sure you have such compilers: - g++9 above; @@ -445,19 +445,11 @@ No dependency. No dependency. -### struct_json - -- [iguana](https://github.com/qicosmos/iguana) - ### struct_pb (optional) - [protobuf](https://protobuf.dev/) -### struct_xml - -- [iguana](https://github.com/qicosmos/iguana) - -### struct_yaml +### struct_json、struct_xml、struct_yaml - [iguana](https://github.com/qicosmos/iguana) diff --git a/website/docs/en/index.md b/website/docs/en/index.md index b64dd5577..d8bc15b25 100644 --- a/website/docs/en/index.md +++ b/website/docs/en/index.md @@ -20,6 +20,10 @@ features: details: Only one line code to finish serialization and deserialization, 2-50x faster than protobuf. - title: coro_rpc details: Very easy-to-use, coroutine-based, high performance rpc framework with C++20, more than 2000w qps in echo scene. - - title: struct_json - details: Reflection-based json lib, very easy to do struct to json and json to struct. + - title: struct_json\struct_xml\struct_yaml + details: C++17 reflection-based json lib, very easy to do struct to json\xml\yaml and json\xml\yaml to struct. + - title: coro_http_client + details: C++20 coroutine http(https) client, include: get/post, websocket, multipart file upload, chunked and ranges download etc. + - title: easylog + details: C++17 high performance and easy to use logging lib, support cout、sprintf and fmt::format/std::format stream. --- diff --git a/website/docs/zh/easylog/easylog introduction.md b/website/docs/zh/easylog/easylog introduction.md new file mode 100644 index 000000000..47f29b293 --- /dev/null +++ b/website/docs/zh/easylog/easylog introduction.md @@ -0,0 +1,108 @@ +# easylog 简介 + +easylog 是C++17 实现的高性能易用的 header only 日志库，它支持主流的3 中流输出模式：std::cout模式、sprintf模式和fmt::format/std::format 模式。主要特点: + +- 支持3 种输出流 +- 同步写日志 +- 异步写日志 +- 日志输出到控制台 +- 日志输出到文件 +- waring 以上级别的日志通过颜色区分 +- 设置文件大小 +- 设置文件数 +- 手动flush +- 创建多个日志实例 + +# 基本用法 + +```c++ +// 流式输出 +ELOG_INFO << "easylog " << 42; +ELOG(INFO) << "easylog " << 42; + +// printf输出 +ELOGV(INFO, "easylog %d", 42); + +// fmt::format 输出 +#if defined(HAS_FMT_LIB) + ELOGFMT(INFO, "easylog {}", 42); +#endif + +// std::format 输出 +#if defined(HAS_STD_FORMAT) + ELOGFMT(INFO, "easylog {}", 42); +#endif +``` + +流式输出的ELOG_INFO 等价于ELOG(INFO)。 + +easylog 定义了如下日志级别： +```c++ +enum class Severity { + NONE = 0, + TRACE = 1, + DEBUG = 2, + INFO = 3, + WARN = 4, + WARNING = 5, + ERROR = 6, + CRITICAL = 7, + FATAL = 8, +}; +``` +用户可以根据需要输出这几种级别的日志，默认的日志级别是DEBUG，其中WARN 和 WARNING 是等价的，CRITICAL 和FATAL 是等价的，主要是为了适配其它日志库。 + +可以通过API ```easylog::set_min_severity(Severity severity)``` 来设置最小的日志级别，如把日志级别设置为WARN 之后，将会只输出WARNING 及以上级别的日志。 + +easylog 默认会将日志输出到控制台，如果不希望输出到控制台则通过API ```void set_console(bool enable)``` 将它禁用即可。 + +easylog 默认是同步输出日志，同步输出日志的性能没有异步日志的性能好，可以通过API ```easylog::void set_async(bool enable)```启用异步模式来输出日志以获得最好的性能。 + +easylog 默认不会每次flush 日志，可以通过调用API ```easylog::flush()```手动将日志内容flush 到日志文件。 + +# 输出到文件 +easylog 默认会将日志输出到控制台，如果希望easylog 将日志输出到文件则需要调用easylog::init 接口做初始化。 + +```c++ +/// \param Id 日志实例的唯一id，默认为0 +/// \param min_severity 最低的日志级别 +/// \param filename 日志文件名称 +/// \param async 是否为异步模式 +/// \param enable_console 是否输出到控制台 +/// \param max_file_size 日志文件最大size +/// \param max_files 最大日志文件数 +/// \param flush_every_time 是否每次flush 日志 +template +void init_log(Severity min_severity, const std::string &filename = "", + bool async = true, bool enable_console = true, + size_t max_file_size = 0, size_t max_files = 0, + bool flush_every_time = false); +``` + +如果日志文件大小达到了max_file_size 旧的日志文件将会被覆盖，如果max_files 设置为1，当大小达到了max_file_size 时，日志文件会被覆盖。 + +```c++ +easylog::init_log(Severity::DEBUG, filename, false, true, 5, 3); +ELOG_INFO << "long string test, long string test"; +ELOG_INFO << "long string test, long string test"; +ELOG_INFO << "long string test, long string test"; +``` +这个代码将产生3 个日志文件(easylog.txt, easylog.1.txt, easylog.2.txt)，当日志size达到设定的最大size 时，将会把easylog.txt 重命名为easylog.1.txt，接着创建新文件easylog.txt，日志内容会写到最新的easylog.txt 文件里。如果日志文件数达到了最大的max_files 3 时，最老的日志文件easylog.3.txt 会被删除，之前的easylog.txt 和 easylog.1.txt 会被重命名为easylog.1.txt 和 easylog.2.txt，然后创建最新的日志文件easylog.txt 用于写日志。 + +日志文件覆盖的原则是，当达到最大file size 时就要创建新的日志文件写日志，如果文件数量达到了最大size，则删掉最旧的日志文件，把之前的日志文件重命名重命名之后再创建最新的日志文件写日志，保持始终最多只有max_files 个日志文件。 + +# 创建多个日志实例 + +默认的日志实例只有一个，如果希望创建更多日志实例，则通过唯一的日志ID 来创建新的日志实例。 + +```c++ +constexpr size_t Id = 2; +easylog::init_log(Severity::DEBUG, "testlog.txt"); +MELOG_INFO(Id) << "test"; +MELOGV(INFO, Id, "it is a test %d", 42); + +constexpr size_t Id3 = 3; +easylog::init_log(Severity::DEBUG, "testlog3.txt"); +MELOG_INFO(Id3) << "test"; +MELOGV(INFO, Id3, "it is a test %d", 42); +``` diff --git a/website/docs/zh/index.md b/website/docs/zh/index.md index e81eb114f..86b196797 100644 --- a/website/docs/zh/index.md +++ b/website/docs/zh/index.md @@ -20,6 +20,10 @@ features: details: 只需要一行代码完成序列化和反序列化, 比 protobuf 快 2-50 倍. - title: coro_rpc details: Very easy-to-use, coroutine-based, high performance rpc framework with C++20, more than 2000w qps in echo scene. - - title: struct_json - details: 基于反射的 json 库, 结构体和 json 的相互转换. + - title: struct_json\struct_xml\struct_yaml + details: C++17 实现的基于反射的 json\xml\yaml 库, 结构体和 json\xml\yaml 的相互转换. + - title: coro_http_client + details: 基于C++20 协程的 http(https) client, 包括: get/post, websocket, multipart file upload, chunked and ranges download etc. + - title: easylog + details: C++17 实现的高性能易用的日志库, 支持cout 流式、sprintf 和 fmt::format/std::format 输出. ---