BqLog (扁鹊日志) V 2.7.1

English | 简体中文

BqLog 是一个轻量级、高性能的工业级日志系统，已在线上广泛应用于《王者荣耀》等项目。

💡 如果您有以下困扰，可以尝试 BqLog

如果您的客户端产品（尤其是游戏）希望同时满足以下「不可能三角」：
- 方便追溯问题（日志应写尽写）
- 性能足够好（日志要少写）
- 节约存储空间（日志最好就别写）
如果您是后台服务开发者，现有日志库在高并发场景下性能不足，导致日志丢失或程序阻塞。
如果您的编程语言是 C++、Java、C#、Kotlin、TypeScript、JavaScript、Python、Go 之一，或者同时使用多种语言，希望有一套统一的跨语言日志解决方案。

🎯 BqLog 的定位

极限性能是 BqLog 的起点，而不是全部。 它是一个成熟的工业级组件，为要发布上线的产品而生：

甘心做配角。 一台现代设备上，日志系统要尽可能少占用系统资源。不管是日志线程还是消费者线程，都要尽量少占用 CPU、内存和磁盘 I/O。我们不是单纯为了跑分，我们所有的优化都针对实际应用场景。
跑在哪里都兼容。 Windows、macOS、Linux、iOS、Android、HarmonyOS、OpenHarmony 和各类 Unix；C++、Java/Kotlin、C#、Python、TypeScript/ArkTS、Go 共用同一个内核，甚至可以共用同一个日志对象；游戏引擎、不带 STL 的移动端工具链、开着 -Werror 的严格构建都没问题。
为出事的那一天准备好。 进程崩溃后能把崩溃前写下的日志恢复回来；磁盘写满时既不崩溃也不卡死；损坏的文件也能尽可能恢复；日志文件可加密，保护隐私。
关注代码体验。 一行创建日志、一行写日志；内部机制尽可能透明，避免复杂配置；所有的接口都对IDE代码提示友好；提供UE蓝图等方便的接入工具适配。

📋 v2.7.x 更新亮点

C++20 模块：import bq.log;，可替代 #include "bq_log/bq_log.h"，写日志的代码无需改动。
无宏的快速模式（C++20）：log.fast_info<"...">(args...)，性能与 BQ_LOG_FAST_INFO 相同，IDE 提示完整，任何日志对象都能用。见 API 参考：快速模式。
包管理器：支持 Homebrew、vcpkg、NuGet，见集成指南。
多进程：多个进程可以共用同一个日志目录，各自拥有独立的崩溃恢复数据。
问题修复：修复了快速模式、恢复、格式化、配置解析与解码器等多处问题。

Warning

该版本更改了 ABI。 头文件（或各语言 wrapper）和库需要一起升级。

完整更新日志 → CHANGELOG_CHS.md

✨ 特点

相比常见开源日志库有显著性能优势（详见 Benchmark），不仅适用于服务器和客户端，也非常适合移动端设备。
内存消耗少：在 Benchmark 用例中（10 线程、每线程 200 万条日志），macOS 上整个 benchmark 进程的峰值内存不超过 3.1 MB。移动平台上，BqLog 自身一般在 1 MB 左右。
提供高性能、高压缩比的实时压缩日志格式。
以接近于0的性能损耗，提供高强度的非对称混合加密日志，保护日志内容安全（可选）。
可在游戏引擎（Unity、Unreal 等）中正常使用，对 Unreal 提供蓝图和常用类型的支持。
支持 utf8、utf16、utf32 字符及字符串，支持 bool、float、double、各种长度与类型的整数等常用参数类型。
支持 C++20 的 std::format 规范（不含排序序号与时间格式化）。
异步日志支持 Crash 复盘机制，尽量避免日志数据丢失。
在 Java、C#、TypeScript 上可以做到「零额外 Heap Alloc」（或极少），不会随着运行不断 new 对象。
仅依赖标准 C 语言库与平台 API，可在 Android 的 ANDROID_STL = none 模式下编译通过。
支持 C++11 及之后的标准，可在极其严格的编译选项下工作。
编译系统基于 CMake，并提供多平台编译脚本，集成简单。
可通过 Homebrew、vcpkg、NuGet 安装，支持 find_package 与 pkg-config。
支持自定义参数类型。
对代码提示非常友好。

🖥️ 支持的平台和语言

平台	语言
Windows 64-bit、macOS、Linux（含嵌入式）、iOS、Android、HarmonyOS、OpenHarmony、Unix（FreeBSD、NetBSD、OpenBSD、Solaris 等）	C++（C++11+）、Java / Kotlin、C#（Unity、.NET）、ArkTS / C++（HarmonyOS 与 OpenHarmony 同一份包）、JavaScript / TypeScript（Node.js）、Python 3.7+、Go、Unreal Engine（UE4、UE5 与 UE6 开发版）

硬件架构：x86、x86_64、ARM32、ARM64 引入方式：动态库、静态库、源代码

📦 安装

生态	安装命令	库	命令行工具	平台主页
Homebrew macOS · Linux	`brew install bqlog`	✅	✅	formulae.brew.sh
vcpkg Windows · Linux · macOS	`vcpkg install bqlog`	✅	`bqlog[tools]`	vcpkg.io
NuGet C# · .NET · Unity	`dotnet add package BqLog`	✅	—	nuget.org
Maven Central — Java Java · Kotlin · 服务端	`implementation("com.tencent.bqlog:java:2.+")`	✅	—	com.tencent.bqlog:java
Maven Central — Android Android · Kotlin	`implementation("com.tencent.bqlog:android:2.+")`	✅	—	com.tencent.bqlog:android
PyPI Python 3.7+	`pip install bqlog`	✅	—	pypi.org
npm Node.js · TypeScript	`npm install @pippocao/bqlog`	✅	—	npmjs.com
ohpm HarmonyOS · OpenHarmony	`ohpm install bqlog`	✅	—	ohpm.openharmony.cn
Go modules Go	`go get github.com/Tencent/BqLog/go/v2@latest`	✅	—	pkg.go.dev
Unity UPM tarball	从 tarball 安装	✅	—	release 页面
Unreal Engine UE4 · UE5	放进 `Plugins/`	✅	—	release 页面 · Fab

Important

表格里没有你的平台？ iOS、tvOS 等 Apple 平台不走包管理器，需要通过 Xcode 或 CMake 集成 —— 见集成指南：iOS / Apple 平台。嵌入式 Linux、各类 BSD、以及从源码构建的情况，同样见集成指南与 release 页面的预编译包。

📖 为何 BqLog 如此快？—— 三部曲系列文章

BqLog 的快不是变魔术变出来的。这个系列从一行日志出发，配示意图，把整套设计一步步推导出来：

之一：高性能实时压缩日志格式 —— 从一行文本推导出压缩格式：模板、VLQ、UTF-Mixed、分段与加密
之二：从环形队列到自适应数据总线 —— 从 kFifo、LMAX Disruptor 到 BqLog 自适应总线：fetch_add + 回滚、MISO/SISO、无锁增删线程与崩溃复盘
之三：压缩日志执行路径优化 —— 一次内存读取能顺便做多少事：融合拷贝哈希、模板缓存、长度回填、批量 I/O

全部插图和系列目录见性能设计。

🏗️ 架构介绍

您的程序通过 BqLog 提供的 BqLog Wrapper（C++、Java、C#、TypeScript、Python 等）来访问核心引擎。每个 Log 对象可挂载一个或多个 Appender（控制台 / 文本文件 / 压缩文件）。同一进程内，不同语言的 Wrapper 可以访问同一个 Log 对象。

Appender	输出目标	可读	性能	尺寸	加密
ConsoleAppender	控制台	Yes	低	-	No
TextFileAppender	文件	Yes	低	大	No
CompressedFileAppender	文件	No	高	小	Yes

🚀 快速上手

调用 API 前，请先将 BqLog 集成到您的项目：

常规编程环境（C++、Java、C#、Python、Node.js 等）→ 集成指南

游戏引擎（Unity、团结引擎、Unreal Engine）→ 游戏引擎集成指南

其他问题 → 常见问题（FAQ）

C++

#include <string>
#include <bq_log/bq_log.h>

int main() {
    std::string config = R"(
        appenders_config.appender_console.type=console
        appenders_config.appender_console.levels=[all]
    )";
    auto log = bq::log::create_log("main_log", config);
    log.info("Hello BqLog 2.0! int:{}, float:{}", 123, 3.14f);
    log.force_flush();
    return 0;
}

C++ 专属的快速模式。 在 C++ 最热的代码路径上，可以用 BQ_LOG_FAST_* 宏写同样的日志，调用线程的开销只有普通模式的一小部分。详见 API 参考：快速模式。

BQ_LOG_FAST_INFO(log, "Hello BqLog fast mode! int:{}, float:{}", 123, 3.14f);
log.fast_info<"Hello BqLog fast mode! int:{}, float:{}">(123, 3.14f);  // C++20，import bq.log; 时只能用这种

输出和 log.info 完全一样。代价是内存使用稍高一点。宏的每个调用点还会绑定第一次调用时的日志对象和格式串，所以同一个宏调用点要固定使用同一个日志对象；fast_info<...> 没有这个限制。

Java

String config = """
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
""";
bq.log.Log log = bq.log.Log.createLog("java_log", config);
log.info("Hello Java! value: {}", 3.14);

C#

string config = @"
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
";
var log = bq.log.create_log("cs_log", config);
log.info("Hello C#! value:{}", 42);

TypeScript (Node.js)

import { bq } from "@pippocao/bqlog";
const config = `
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
`;
const log = bq.log.create_log("node_log", config);
log.info("Hello from Node.js! params: {}, {}", "text", 123);
bq.log.force_flush_all_logs();

Python

from bq.log import log
config = """
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
"""
my_log = log.create_log("python_log", config)
my_log.info("Hello from Python! params: {}, {}", "text", 123)
log.force_flush_all_logs()

Go

package main

import bq "github.com/Tencent/BqLog/go/v2"

func main() {
    config := `
appenders_config.console.type=console
appenders_config.console.levels=[all]
`
    log := bq.Create_log("go_log", config, nil)
    if !log.Is_valid() {
        panic("invalid log config")
    }
    defer log.Force_flush()

    log.Info("Hello from Go! params: {}, {}", "text", 123)
}

TypeScript (鸿蒙 / OpenHarmony ArkTS)

同一个 ohpm 上的 bqlog 包同时适用于 HarmonyOS（NEXT）和 OpenHarmony（4.1+ / API 11+）。安装、引用、API 完全一致。

import { bq } from "bqlog";
const config = `
    appenders_config.console.type=console
    appenders_config.console.levels=[all]
`;
const log = bq.log.create_log("ohos_log", config);
log.info("Hello from HarmonyOS / OpenHarmony! params: {}, {}", "text", 123);
bq.log.force_flush_all_logs();

各平台完整集成步骤请见集成指南和游戏引擎集成指南。

📊 Benchmark 结果

日志系统不是业务的核心，占用大量 CPU 或内存的日志库是不合格的。所以 Benchmark 测的是真实场景下的总消耗：所有日志落盘的总耗时，连同为此花掉的 CPU 和内存；另外还测了日志线程上单次调用的延迟。完整的测试用例和数据见 Benchmark。

吞吐，4 个参数，macOS（Apple M4 Pro）。每线程 2,000,000 条，计时到全部落盘；所有库都用固定大小、写满阻塞的缓冲区；BqLog 为 C++ 快速模式：

	1 线程	4 线程	10 线程
BqLog，压缩	39 ms / CPU 76 ms	148 ms / CPU 734 ms	375 ms / CPU 3984 ms
BqLog，文本	152 ms / CPU 303 ms	617 ms / CPU 3047 ms	1548 ms / CPU 16307 ms
quill	331 ms / CPU 493 ms	1517 ms / CPU 4697 ms	4338 ms / CPU 29048 ms
fmtlog	254 ms / CPU 475 ms	1089 ms / CPU 5310 ms	2982 ms / CPU 32093 ms
Log4j2（Java）	665 ms / CPU 2810 ms	1872 ms / CPU 9206 ms	3754 ms / CPU 19383 ms
spdlog（异步）	535 ms / CPU 966 ms	6758 ms / CPU 20142 ms	-
glog（同步）	2322 ms / CPU 2318 ms	9929 ms / CPU 30661 ms	-

BqLog 压缩格式的总耗时和CPU负载都明显倍数快于其它同类日志库。
峰值内存：BqLog 在 10 线程时不超过 3.1 MB。
开启扩容时，与同样可以扩容的队列相比，BqLog 快 2～8 倍，CPU 时间更少，峰值内存约为一半。
日志线程上单次调用的延迟：BqLog 是所测库中最低的一档（1 线程 p50 4 ns、p99 29 ns）。

🔄 从 1.x 版本升级到 2.x 版本的变化

增加对鸿蒙系统的支持，包括 ArkTS 和 C++ 两种语言。
增加对 Node.js 的支持（CJS 和 ESM）。
增强跨平台兼容性、稳定性与通用性，支持更多 Unix 系统。
utf8编码下性能平均提升约 80%，utf16编码环境（C#，Unreal，Unity）提升超过500%。
Android 不再强制要求与 Java 一起使用。
移除 is_in_sandbox 配置，改用 base_dir_type；对 snapshot 增加过滤配置，支持每次启动新开日志文件。详见配置说明。
支持高性能非对称混合加密，几乎无额外性能损耗，详见高级用法 — 加密。
提供 Unity、团结引擎、Unreal 引擎插件，方便在游戏引擎中使用；Unreal 插件支持 UE4、UE5 与当前 UE6 开发版，并提供 ConsoleAppender 日志重定向和蓝图支持。UE4/UE5 插件同时发布于 Fab，UE6 插件目前仅通过 GitHub Releases 提供。详见游戏引擎集成指南。
仓库不再包含二进制产物，从 2.x 版本起请从 Releases 页面下载对应平台和语言的二进制包。
单条日志长度不再受log.buffer_size限制。
可以精确手动设置时区。
raw_file类型的appender已删除。配置为type=raw_file的appender会打印警告并被忽略，请用compressed_file类型替代。
复盘能力增加可靠性，从实验性功能变成正式能力。见高级用法 — 数据保护。

📑 文档导航

文档	说明
开发规范	贡献代码的编码规范
常见问题（FAQ）	常见问题：对比、平台与语言、发布渠道、崩溃恢复
集成指南	所有平台完整集成步骤 + 各语言 Demo
游戏引擎集成	Unity、团结引擎、Unreal Engine 插件与蓝图使用
API 参考	核心 API、同步/异步日志、Appender 介绍、构建与工具
配置说明	完整配置参考（appenders、log、snapshot）
高级用法	无 Heap Alloc、Category、崩溃恢复、自定义类型、加密
Benchmark	Benchmark 代码、测试方法和结果
性能设计三篇	压缩文件格式、自适应数据总线与写入路径优化

🤝 如何贡献代码

请先阅读开发规范。

若您希望贡献代码，请确保您的改动能通过仓库中 GitHub Actions 下的以下工作流：

AutoTest
Build

建议在提交前本地运行对应脚本，确保测试与构建均正常通过。

Navigation Menu

Repository navigation

README_CHS.md

README_CHS.md

BqLog (扁鹊日志) V 2.7.1

💡 如果您有以下困扰，可以尝试 BqLog

🎯 BqLog 的定位

📋 v2.7.x 更新亮点

✨ 特点

🖥️ 支持的平台和语言

📦 安装

📖 为何 BqLog 如此快？—— 三部曲系列文章

🏗️ 架构介绍

🚀 快速上手

C++

Java

C#

TypeScript (Node.js)

Python

Go

TypeScript (鸿蒙 / OpenHarmony ArkTS)

📊 Benchmark 结果

🔄 从 1.x 版本升级到 2.x 版本的变化

📑 文档导航

🤝 如何贡献代码

FilesExpand file tree

README_CHS.md

Latest commit

History

README_CHS.md

File metadata and controls

BqLog (扁鹊日志) V 2.7.1

💡 如果您有以下困扰，可以尝试 BqLog

🎯 BqLog 的定位

📋 v2.7.x 更新亮点

✨ 特点

🖥️ 支持的平台和语言

📦 安装

📖 为何 BqLog 如此快？—— 三部曲系列文章

🏗️ 架构介绍

🚀 快速上手

C++

Java

C#

TypeScript (Node.js)

Python

Go

TypeScript (鸿蒙 / OpenHarmony ArkTS)

📊 Benchmark 结果

🔄 从 1.x 版本升级到 2.x 版本的变化

📑 文档导航

🤝 如何贡献代码