Skip to content

Commit

Permalink
[easylog][doc]add doc for easylog (#419)
Browse files Browse the repository at this point in the history
  • Loading branch information
qicosmos authored Aug 21, 2023
1 parent 5ca0127 commit dbf6905
Show file tree
Hide file tree
Showing 4 changed files with 122 additions and 14 deletions.
12 changes: 2 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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)
Expand Down
8 changes: 6 additions & 2 deletions website/docs/en/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
---
108 changes: 108 additions & 0 deletions website/docs/zh/easylog/easylog introduction.md
Original file line number Diff line number Diff line change
@@ -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 <size_t Id = 0>
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<Id>(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<Id3>(Severity::DEBUG, "testlog3.txt");
MELOG_INFO(Id3) << "test";
MELOGV(INFO, Id3, "it is a test %d", 42);
```
8 changes: 6 additions & 2 deletions website/docs/zh/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 输出.
---

0 comments on commit dbf6905

Please sign in to comment.