一文掌握log-cj:8大日志级别与13种Pattern格式化占位符全解

原创2026-11-16 21:02:211,662 阅读
文章标签:可观测性后端

一文掌握log-cj:8大日志级别与13种Pattern格式化占位符全解

log-cj 是一款面向仓颉语言(Cangjie)的日志管理框架,提供控制台与文件双通道日志输出、JSON 配置能力,内置 8 大日志级别与 13 种 Pattern 格式化占位符。本文带你零基础理解 log-cj 的级别过滤机制与日志格式定制方法,让你快速写出清晰、可追溯的应用日志。

log-cj日志框架开发里程碑时间线图

一、log-cj 是什么:仓颉生态的一站式日志方案

log-cj 类似 Java 生态中的 log4j,核心特性包括:

  • 💡 支持控制台日志(stdout/stderr)和文件日志两种输出方式
  • 🚀 支持通过 JSON 文件(logcj.json)自定义日志级别、输出格式与滚动策略
  • 🧵 多线程写入日志文件,自动处理文件切分

从源码目录看,log-cj 的设计非常清晰(详见 log-cj 设计文档):

模块 路径 职责
日志级别与工具 src/utils/ 级别定义、日志记录、Pattern 格式转换
日志记录器 src/logger/ Logger 与 LoggerManager
输出附加器 src/appender/ 控制台/文件输出实现
配置解析 src/config/ 解析 JSON 配置文件

二、8大日志级别全解:ALL 到 OFF 一次看懂

log-cj 在 log_level.cj 中定义了 8 个日志级别,从低到高依次为:

序号 级别 含义 Logger 调用方法 适用场景
1 ALL 开启全部日志 logger.all() 最详细的调试
2 TRACE 跟踪信息 logger.trace() 追踪代码执行路径
3 DEBUG 调试信息 logger.debug() 开发阶段排查问题
4 INFO 通知信息 logger.info() 记录关键业务节点
5 WARN 警告信息 logger.warn() 潜在风险但不影响运行
6 ERROR 错误信息 logger.error() 功能执行失败
7 FATAL 致命错误 logger.fatal() 系统级故障,需立即处理
8 OFF 关闭日志 logger.off() 关闭输出

💡 每个级别对应一个 1~8 的数值(见 log_level.cj#L32-L44),数值越大级别越高。

级别过滤是怎么工作的?

在 logger.cj 中,日志写入前会判断:

if (level >= appenderRef.getLevel()) { ... 输出日志 ... }

也就是说:只有日志级别 ≥ 记录器配置级别时才会输出。比如配置文件中 root logger 设置为 "level": "info",则 info、warn、error 都会打印,而 debug、trace 会被静默过滤。配置里填 info 表示"输出 info 级别及以上日志"。

三、13种Pattern占位符全解:打造你的日志格式

log-cj 的日志格式由 Pattern 字符串控制,核心实现在 pattern_converter.cj。完整占位符清单如下:

🕒 时间类(6 个)

占位符 含义 输出示例
%D 完整日期 2022/11/21
%d 短日期 11/21/22
%T 完整时间(含时区) 11:15:11 CST
%t 短时间(无时区) 11:15
%m 毫秒(3位补零) 281
%n 纳秒(9位补零) 794411287
%o Unix 毫秒时间戳 1649224315937

📋 内容类(5 个)

占位符 含义 输出示例
%L 日志级别 INFO
%l 标签名(Logger 名) Demo
%S 来源(完整包/类路径) com.test.ClassA
%s 来源(仅最后一段) ClassA
%M 日志消息内容 你的日志文本

🧵 线程类(2 个)

占位符 含义 输出示例
%I 线程 ID 1
%o Unix 毫秒时间戳 1649224315937

⚠️ 遇到不识别的格式字符会被自动忽略,不会报错。时间解析逻辑见 time_slice.cj。

官方推荐 Pattern

[%D %T %m] [%L] [%I] [%l] <%S> %M

实际输出效果(来自 README.md 功能示例):

[2024/07/19 11:43:23 CST 928] [INFO] [1] [root] <> 4
[2024/07/19 11:43:23 CST 928] [WARN] [1] [root] <> 5
[2024/07/19 11:43:23 CST 928] [ERROR] [1] [root] <> 6

一眼就能看出:何时、什么线程、哪个 Logger、什么级别、发生了什么。

log-cj日志框架运行时调用栈火焰图

四、配置实战:logcj.json 一分钟上手

log-cj 通过 JSON 文件驱动,完整字段说明见 配置文件说明文档。一个最小可用配置:

{
    "appenders": [
        {
            "enabled": "true",
            "name": "console",
            "type": "console",
            "pattern": "[%D %T %m] [%L] [%l] (%S) %M"
        },
        {
            "enabled": "true",
            "name": "file",
            "type": "file",
            "pattern": "[%D %T %m] [%L] [%l] (%S) %M",
            "properties": [
                { "name": "filename", "value": "root.log" },
                { "name": "rotate", "value": "true" },
                { "name": "maxsize", "value": "20M" },
                { "name": "daily", "value": "false" }
            ]
        }
    ],
    "loggers": [
        { "name": "Demo", "level": "warn", "appender-refs": [ { "ref": "console" }, { "ref": "file" } ] }
    ],
    "root": { "level": "info", "appender-refs": [ { "ref": "console" }, { "ref": "file" } ] }
}

关键配置速查

配置项 位置 说明
level loggers / root 该记录器输出的最低级别,如 info 表示输出 info 及以上
pattern appenders 日志格式,使用上文 13 种占位符自由组合
type appenders console(系统输出)或 file(文件输出)
filename file properties 日志文件名,如 root.log
rotate / maxsize file properties 是否滚动、单文件最大体积(如 20M)
daily file properties 是否按天滚动日志文件

💡 技巧:未配置独立 logger 的代码会自动落到 root 记录器(见 logger.cj#L35-L46),因此 root 的 level 是全局兜底阈值。

五、快速参考:级别 × 占位符组合示例

你想要的效果 Pattern 写法
标准生产格式 [%D %T %m] [%L] [%I] [%l] <%S> %M
精简格式 [%T] [%L] %M
排查线程问题 [%D %T %m] [T:%I] [%l] %M
仅时间戳+消息 [%o] %M
只关心短日期 [%d %t] [%L] %M

📚 延伸阅读

总结:记住"8 个级别管过滤,13 种占位符管格式"——级别决定输出什么,Pattern 决定长什么样。掌握这两点,你已经能用 log-cj 为任何仓颉项目搭建一套专业、易读的日志体系了。

登录后查看全文
log-cj