一文掌握log-cj:8大日志级别与13种Pattern格式化占位符全解
一文掌握log-cj:8大日志级别与13种Pattern格式化占位符全解
log-cj 是一款面向仓颉语言(Cangjie)的日志管理框架,提供控制台与文件双通道日志输出、JSON 配置能力,内置 8 大日志级别与 13 种 Pattern 格式化占位符。本文带你零基础理解 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、什么级别、发生了什么。
四、配置实战: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 |
📚 延伸阅读
- 接口详细说明:feature_api.md
- 设计文档:log-cj_design.md
- 控制台输出实现:console_logger_appender.cj
- 文件输出实现:file_logger_appender.cj
- 日志记录结构:log_record.cj
- 级别定义源码:log_level.cj
- Pattern 转换源码:pattern_converter.cj
总结:记住"8 个级别管过滤,13 种占位符管格式"——级别决定输出什么,Pattern 决定长什么样。掌握这两点,你已经能用 log-cj 为任何仓颉项目搭建一套专业、易读的日志体系了。
