# C++多模式日志系统

**Repository Path**: andy0523/c-multi-mode-logging-system

## Basic Information

- **Project Name**: C++多模式日志系统
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-30
- **Last Updated**: 2026-03-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于双缓冲的高性能 C++ 异步日志系统

一个基于 C++11 实现的高性能日志库，支持同步与异步两种写入模式，可将格式化日志输出到标准输出、文件及按大小滚动的日志文件。

---

## 特性

- 支持 DEBUG / INFO / WARN / ERROR / FATAL / OFF 六个日志等级
- 支持自定义格式化 pattern，灵活组合日志字段
- 支持标准输出、固定文件、滚动文件三种落地方式
- 同步/异步双模式，异步模式采用双缓冲区设计，显著降低锁竞争
- 多日志器并存，不同模块可独立配置策略
- 对外提供简洁的宏接口，使用方便

---

## 开发环境

- OS：Linux（Ubuntu）
- 编译器：g++（C++11）
- 编辑器：VSCode + SSH 远程开发
- 构建工具：Makefile

---

## 项目结构

```
.
├── level.hpp       # 日志等级枚举及字符串转换
├── message.hpp     # 日志消息结构体（时间、线程ID、文件名、行号等）
├── format.hpp      # 格式化模块，状态机解析 pattern，组合模式构建格式化链
├── sink.hpp        # 日志落地模块（标准输出 / 文件 / 滚动文件），工厂模式
├── buffer.hpp      # 双缓冲区实现，支持动态扩容
├── looper.hpp      # 异步工作器，独立线程消费缓冲区
├── logger.hpp      # 同步/异步日志器，Builder 模式构建，单例 Manager 管理
├── util.hpp        # 工具类（时间、文件、目录）
└── bitlog.hpp      # 统一入口，宏接口定义
```

---

## 快速开始

### 编译

```bash
g++ -std=c++11 -pthread your_main.cpp -o your_app
```

### 使用全局根日志器（最简方式）

```cpp
#include "bitlog.hpp"

int main() {
    DEBUG("hello %s", "world");
    INFO("server start, port=%d", 8080);
    ERROR("open file failed: %s", "test.txt");
    return 0;
}
```

### 创建自定义日志器

```cpp
#include "bitlog.hpp"

int main() {
    // 同步日志器，输出到文件
    std::unique_ptr<bitlog::LoggerBuilder> builder(new bitlog::GlobalLoggerBuilder());
    builder->buildLoggerName("mylogger");
    builder->buildLoggerLevel(bitlog::LogLevel::value::INFO);
    builder->buildLoggerFormatter("[%d{%H:%M:%S}][%p][%c] %m%n");
    builder->buildSink<bitlog::FileSink>("./logs/app.log");
    builder->build();

    auto logger = bitlog::getLogger("mylogger");
    logger->info("server started");

    return 0;
}
```

### 创建异步日志器

```cpp
#include "bitlog.hpp"

int main() {
    std::unique_ptr<bitlog::LoggerBuilder> builder(new bitlog::GlobalLoggerBuilder());
    builder->buildLoggerName("async_logger");
    builder->buildLoggerType(bitlog::LoggerType::LOGGER_ASYNC);
    builder->buildSink<bitlog::RollSink>("./logs/roll", 10 * 1024 * 1024); // 10MB 滚动
    builder->build();

    auto logger = bitlog::getLogger("async_logger");
    logger->warn("this is async mode");

    return 0;
}
```

---

## 格式化 Pattern 说明

| 占位符 | 含义 | 示例输出 |
|--------|------|----------|
| `%d{fmt}` | 时间，子格式同 strftime | `14:35:02` |
| `%p` | 日志等级 | `INFO` |
| `%t` | 线程 ID | `140234567` |
| `%c` | 日志器名称 | `mylogger` |
| `%f` | 源文件名 | `main.cpp` |
| `%l` | 源代码行号 | `42` |
| `%m` | 日志消息主体 | `server started` |
| `%T` | 制表符 | |
| `%n` | 换行符 | |

默认 pattern：`[%d{%H:%M:%S}][%p][%t][%c][%f][%l]%T%m%n`

---

## 核心设计

### 双缓冲区异步写入

异步模式下，业务线程只将格式化后的字符串写入**生产者缓冲区**，后台消费线程在合适时机通过 `swap` 交换两块缓冲区的指针，随后对**消费者缓冲区**做批量 I/O。整个切换过程锁的持有时间极短，大幅减少了线程间的锁竞争。

```
业务线程 ──写入──▶ 生产者缓冲区
                        │  swap（短暂加锁）
消费线程 ◀──读取── 消费者缓冲区 ──▶ 批量写入 Sink
```

### 异步安全模式 vs 非安全模式

| 模式 | 行为 | 适用场景 |
|------|------|----------|
| ASYNC_SAFE（默认） | 缓冲区满时阻塞生产者 | 不允许丢日志的场景 |
| ASYNC_UNSAFE | 缓冲区自动扩容，不阻塞 | 追求极低延迟的场景 |

---

## 宏接口一览

```cpp
// 使用全局根日志器
DEBUG("fmt", ...);
INFO("fmt", ...);
WARN("fmt", ...);
ERROR("fmt", ...);
FATAL("fmt", ...);

// 使用具名日志器实例（自动附加文件名和行号）
logger->debug("fmt", ...);
logger->info("fmt", ...);
```