# AxonLogger **Repository Path**: diabio/axon_logger ## Basic Information - **Project Name**: AxonLogger - **Description**: 这是一个功能丰富且高性能的C++日志库 - **Primary Language**: C++ - **License**: MulanPSL-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-06-11 - **Last Updated**: 2025-08-31 ## Categories & Tags **Categories**: Uncategorized **Tags**: Cpp, cmake ## README # AxonLogger v1.1.0: C++ 高性能异步日志库 ## 简介 `AxonLogger` 是一个从零开始精心打造的、现代、功能丰富且高性能的C++日志库。其设计灵感源于业界顶尖的日志项目，但核心功能，包括异步调度、文件I/O、滚动策略和控制台颜色输出，均为完全独立实现。 它旨在为C++应用提供一个可靠、易用、高度可配置且完全自主可控的日志解决方案。 ## 核心特性 - **高性能异步写入：** 基于生产者-消费者模型和无锁队列 `moodycamel::ConcurrentQueue` 实现，日志写入操作不会阻塞主应用程序线程，有效提升应用程序吞吐量。 - **灵活的实例化：** 采用工厂模式和建造者模式，支持创建和管理多个、完全隔离的日志记录器实例，告别了传统单例模式的局限性。 - **现代化的格式化API：** 全面集成`{fmt}`库，提供类型安全的、Python f-string风格的格式化宏（例如 `LOG_INFO(logger, "User {} logged in", id)`)，兼具高性能与易用性。 - **多输出目标：** 通过适配器模式，支持将日志同时输出到控制台、滚动文件和远程HTTP服务。 - **结构化日志 (JSON)：** 支持将日志输出为机器可读的JSON格式，便于日志分析工具进行处理和查询。 - **动态日志级别调整：** 支持运行时动态修改日志级别（TRACE, DEBUG, INFO, WARN, ERROR, CRITICAL, OFF），无需重启应用程序。 - **分布式追踪支持：** 自动在每条日志中注入 `Trace ID` 和 `Span ID`，方便进行请求链路追踪。 - **健壮性设计：** - **敏感信息过滤：** 利用装饰器模式实现日志内容过滤，可使用正则表达式对密码、Token等敏感信息进行自动脱敏处理。 - **日志回溯 (Backtrace)：** 可选功能，在程序异常退出时，能够打印最近N条历史日志，辅助故障排查。 - **优雅退出：** 程序结束时，会自动等待并刷写队列中所有剩余的日志，确保数据不丢失。 - **内存管理：** 经Valgrind验证，项目目前无已知内存泄漏。 - **模块化与可扩展：** 基于清晰的接口设计（`ISink`, `IFormatter`），易于添加新的日志输出目标和格式化方式。 ## 项目结构 ```bash AxonLogger/ # 项目根目录 ├── external/ # 外部第三方库 (Git 子模块管理) │ ├── fmt/ │ ├── moodycamel_queue/ │ └── nlohmann_json/ ├── include/ # 公共头文件，定义接口和类结构 │ ├── logger_api.hpp # 核心接口类 (Logger接口、日志级别枚举) │ ├── core/ # 核心模块头文件 (异步工作、日志上下文、日志条目) │ ├── io/ # 核心底层I/O模块 │ ├── utils/ # 辅助工具 │ ├── metrics/ # 内部性能检测类 │ ├── sinks/ # 输出器接口头文件 (控制台、文件、过滤、网络) │ └── formatters/ # 格式化器接口头文件 (基础文本、JSON) ├── src/ # 实现代码 │ ├── core/ # 核心逻辑实现 │ ├── io/ # 核心底层I/O模块 │ ├── utils/ # 辅助工具实现 │ ├── metrics/ # 内部性能检测类实现 │ ├── sinks/ # 输出器实现 │ └── formatters/ # 格式化器实现 ├── tests/ # 单元测试与性能测试 │ └── test_perf.cpp # 性能测试 ├── examples/ # 使用示例 │ ├── basic_usage.cpp # 综合功能演示 │ └── test_network.py # 网络日志接收端 (Python Flask 示例) └── CMakeLists.txt # 项目构建配置 ``` ## 构建项目 本项目使用CMake构建，并依赖Git子模块来管理第三方库。 1. **克隆仓库并初始化子模块：** ```bash git clone https://gitee.com/diabio/AxonLogger.git cd AxonLogger git submodule update --init --recursive ``` * **注意：** 如果你是在`Debian/Ubuntu`等系统下运行，可能需要安装`libcurl4-openssl-dev`和`python3-full`（用于测试网络日志接收端）： ```bash sudo apt update sudo apt install libcurl4-openssl-dev python3-full pipx pipx ensurepath # 确保 pipx 的bin目录在PATH中 ``` 2. **构建项目：** ```bash mkdir build cd build cmake .. -DCMAKE_BUILD_TYPE=Release # 推荐使用Release模式以获得最佳性能 cmake --build . ``` * 构建成功后，可执行文件将位于 `build/bin/` 目录下。 ## 如何使用 ### 1. 初始化日志库 推荐使用 LoggerBuilder 来创建和配置您的日志记录器实例。 ```cpp #include "logger_builder.hpp" #include "logger_factory.hpp" #include "core/log_context.hpp" #include #include int main() { // 确保日志目录存在 std::filesystem::create_directories("logs"); // --- 1. 使用 LoggerBuilder 创建一个功能齐全的 Logger 实例 --- std::cout << "\n--- Creating logger with LoggerBuilder ---\n"; auto logger1 = LoggerBuilder() .withLogLevel(LogLevel::Debug) .withJsonFormat() // 使用JSON格式化器 .withConsoleSink(true) // 添加控制台输出，并应用过滤 .withFileSink("logs/app.log", 5 * 1024 * 1024, 3) // 5MB一个文件，最多保留3个 .withNetworkSink("http://127.0.0.1:8080/log") // 添加网络输出 .withFilter("\"password\":\"[^\"]+\"", "\"password\":\"[REDACTED]\"") // 添加过滤规则 .enableBacktrace(50) // 开启50条日志的回溯功能 .build(); // --- 2. (可选) 从配置文件创建另一个独立的 Logger 实例 --- std::cout << "\n--- Creating another logger from config/logger.json ---\n"; auto logger2 = LoggerFactory::createFromConfigFile("config/logger.json"); // --- 3. 开始使用 Logger --- std::cout << "\n--- Demonstrating Logging ---\n"; // 使用宏，传入 logger 实例指针和格式化参数 LOG_INSTANCE_INFO(logger1, "Application starting up with {} threads...", std::thread::hardware_concurrency()); // 使用带 _CTX 后缀的宏，传递独立的结构化上下文 nlohmann::json context = { {"user", "admin"}, {"ip", "192.168.1.1"}, {"password", "a_very_secret_password"} // 此字段将被 logger1 过滤 }; LOG_INSTANCE_WARN_CTX(logger1, "Admin login attempt detected.", context); // logger2 使用不同的配置 (来自logger.json) LOG_INSTANCE_INFO(logger2, "This is a message from the second logger."); // --- 4. 演示分布式追踪 --- { LogContextManager::ContextScope trace_scope("trace-id-12345", "span-id-abcde"); LOG_INSTANCE_ERROR_CTX(logger1, "Transaction failed inside trace scope.", {{"error_code", 500}}); } // trace_scope 在此处结束，上下文自动恢复 // --- 5. 等待异步线程刷写日志 --- std::cout << "\nWaiting for async threads to flush logs...\n"; std::this_thread::sleep_for(std::chrono::seconds(1)); std::cout << "\nExample finished. Check console output and log files in 'logs/' directory.\n"; // 当 main 函数结束，logger1 和 logger2 的 shared_ptr 会自动销毁， // 从而安全地触发其内部资源的回收，无需任何手动清理。 return 0; } ``` ## 运行测试 ### 1. 性能基准测试 `AxonLogger` 拥有极其出色的性能，以下是在典型硬件上（关闭Backtrace功能）的测试结果。 - **测试环境：** - 操作系统: Ubuntu 24.04.1 LTS (WSL2) - CPU: Intel(R) Core(TM) i5-9300H @ 2.40GHz (4核8线程) - **测试命令：** `./build/bin/test_perf` #### 性能测试结果(v1.1.0, 自研I/O核心) ```bash ============= MyLogger Performance Test Summary ===================================== --- Formatter: Basic --- Thread Count: 1 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2141605.34 0.46 0.74 3.80 128 2441604.18 0.39 0.66 1.76 256 2261775.56 0.43 0.74 3.71 Thread Count: 2 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2600531.44 0.80 1.82 5.53 128 3050670.52 0.62 1.82 2.64 256 3139901.03 0.59 1.80 2.86 Thread Count: 4 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2339702.13 1.84 3.07 22.26 128 2949618.22 1.29 2.97 8.71 256 2719610.07 1.38 3.07 9.54 Thread Count: 8 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2003629.70 4.48 11.43 78.39 128 2322584.61 3.31 9.12 34.52 256 2260767.91 3.44 10.57 42.06 Thread Count: 16 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 1911133.88 8.87 27.07 189.40 128 2221923.56 6.72 8.57 116.62 256 2088794.11 7.34 20.09 140.21 --- Formatter: JSON --- Thread Count: 1 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2475647.94 0.39 0.64 3.82 128 2523502.83 0.37 0.54 1.59 256 2255400.17 0.43 0.75 3.71 Thread Count: 2 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2500336.86 0.81 1.87 5.28 128 2969506.58 0.64 1.80 2.54 256 3128927.79 0.59 1.80 2.65 Thread Count: 4 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2735317.28 1.42 2.96 9.89 128 2711763.97 1.39 3.01 10.10 256 2401719.28 1.61 3.37 13.37 Thread Count: 8 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2436142.51 3.13 7.20 25.37 128 2109110.51 3.70 9.02 56.05 256 2081589.38 3.72 10.90 56.29 Thread Count: 16 Message Size Throughput (msg/s) Latency (μs) P95 (μs) P99 (μs) ------------------------------------------------------------------------------------- 64 2199984.66 6.98 20.84 133.65 128 2206314.78 6.97 22.36 133.11 256 2145376.31 7.13 18.16 137.13 ===================================================================================== ``` ### 2. 功能演示 运行 `basic_usage` 可执行文件，它会演示日志库的各项功能。 ```bash ./build/bin/basic_usage ``` ### 3. 网络日志接收端 (可选) 如果你想测试网络日志输出功能，可以运行 `examples/test_network.py` 来启动一个简单的 Flask 服务器作为日志接收端。 ```bash # 激活Python虚拟环境（如果使用的话） source venv_log_server/bin/activate # 运行Flask服务器 python3 examples/test_network.py ``` ## 项目演进 本项目目前已完成的开发阶段如下： 1. **阶段1：基础功能 (MVP)** * 实现同步日志、文件/控制台输出、基础格式化。 2. **阶段2：生产级功能 (核心特性)** * 添加异步队列、日志轮转、动态级别调整。 * **里程碑：** 实现高性能异步写入和文件日志轮转。 3. **阶段3：高级特性 (可用性与可分析性)** * 支持结构化日志 (JSON)、Trace ID/Span ID 注入。 * **里程碑：** 日志数据变为机器可读格式，支持分布式追踪。 4. **阶段4：健壮性与安全 (可靠性)** * 实现崩溃保护 (析构时强制刷新)、敏感信息过滤、日志回溯。 * **里程碑：** 提升日志系统在异常情况下的可靠性，增强数据安全。 5. **阶段5：生态集成 (网络输出)** * 实现日志通过网络发送到集中式日志收集系统。 * **里程碑：** 支持远程日志收集，实现多输出源聚合。 6. **阶段6：架构重构与现代化** * 从单例模式重构为**工厂和建造者模式**，实现了多实例和依赖注入。 * 全面引入**类型安全的格式化API** (`{fmt}` 库)，大幅提升了API的易用性和性能。 * 通过RAII等现代C++实践，重构了`NetworkSink` 等组件，使其更健壮、更安全。 7. **阶段7：核心独立(v1.1)** * 实现了独立的底层I/O模块，包括平台特定的彩色控制台输出和文件滚动逻辑。 * 完全移除了对spdlog的运行时依赖，成为一个100%自给自足的高性能日志库。 * 里程碑： 项目在核心功能上实现完全自主可控。