运行日志与故障证据
实现状态:Apollo 已有自研日志、MetricRegistry 和 span/trace 原语;尚未集成专用 Profiler、OpenTelemetry SDK 或 OTLP exporter。本页的工具比较及观测方案不代表运行链路已经接入。
当前日志实现归 modules/core/log。应用通过统一日志管理器配置控制台、本地文件和可选推送。本文区分已有路径、部署规则和待验收的故障保证,不保留按日期追加的收敛记录。
执行摘要
本地结构化日志、集中收集、指标、调用链采样和崩溃报告承担不同职责。集中收集不成为模拟依赖;日志成功返回也不能自动解释成断电后的持久保证。
1. 故障边界
| 场景 | 需要验证的结果 |
|---|---|
| 正常运行 | 进程身份、级别、类别与消息可检索,输出开销受控 |
| 收集器不可用 | 本地日志继续可用,推送缓存有界 |
| 本地文件失败 | 故障可见,避免无界重试或缓存 |
| 进程崩溃 | 由独立崩溃采集路径留证 |
| 进程重启 | 旧日志、dump、监督事件可关联,但不代表活动副本恢复 |
2. 所有权
日志 API 和文件输出归 core/log;进程身份及输出配置由应用入口设置;收集与查询归 logger 工具;指标汇聚和管理出口归 admin。业务进程不直接向聊天机器人或外部告警系统发送 HTTP。
3. 本地日志
3.1 等级与持久性
日志接口支持等级过滤、追加器和 flush。当前存在带锁的日志及文件输出路径,不能写成热路径已经完全无锁、零格式化开销或高等级日志绝不丢失。
ERROR 旁路、FATAL 同步 fsync、磁盘满降级和日志线程故障属于需要专门故障注入验证的保证。没有对应实现和证据时,不以日志等级名称替代持久性承诺。
3.2 线程与预算
模拟线程避免高频字符串构造和大量同步输出。推送客户端使用自己的有界队列及泵,不能阻塞模拟等待收集器。队列溢出、重连及丢弃必须有可观察结果。
3.3 启停
应用先初始化日志,再初始化可能产生日志的运行时设施。停止时保留日志至业务和依赖关闭完成,再释放日志输出。当前各应用仍有显式入口逻辑,需要分别验证启动失败与停止路径。
4. 崩溃取证
4.1 独立路径
崩溃报告通过 runtime 的 Crashpad 集成生成,不以普通日志器仍能取锁或工作为前提。详见崩溃采集。
4.2 信号边界
信号上下文不得执行带锁日志、线程 join 或复杂业务停止。信号应转交正常执行线程处理;当前入口的统一信号接线仍需检查,不能从存在 signalHandler 推断异步信号安全。
4.3 运行证据
记录进程身份、运行代次、构建版本与故障时间,关联日志、监督死亡事件和 dump。平台 core dump 配置和符号仓属于部署工作,编译选项本身不完成验收。
5. 集中收集与指标
logger 提供 scan/follow 检索和 serve 收集。业务进程可通过 APOLLO_LOG_PUSH_ADDR 启用 M1 日志推送;未配置时不建立此出口。收集失败不改变玩家权威或业务结果。
5.1 数据格式与外采
结构化行使用稳定键序:ts、level、proc、tick、cat、msg,后接扩展键。值中的空白、引号、反斜线和控制字符按格式规则转义,避免一条消息破坏多行采集。
APOLLO_METRICS_PUSH_ADDR 启用指标快照推送,admin 提供聚合及 HTTP 指标出口。已有出口不等于已经部署 Prometheus/Grafana。trace 子集围绕消息边界传播标识和采样信息,不宣称已经接入完整外部追踪平台。
日志用于事件证据,指标用于统计趋势,运行时内省用于当前状态。业务结算和玩家资料仍走持久化路径,不通过日志收集作为数据权威。
5.2 告警
admin 的 notifier 和 webhook 原语属于运维出口,需要配置、目标限制、速率及失败策略。业务进程不等待告警发送。外部观测系统按具体部署需求接入,不能从模板或库依赖宣称其已上线。
6. 当前边界
现役能力包括应用结构化文件配置、logger 查询/收集、M1 推送、指标出口、采样和崩溃采集原语。进程恢复、活动副本恢复、日志零丢失和外部观测部署分别验收,不按旧批次记录推导。
7. 验收
验证本地写入、字符转义、查询、收集断线与缓存水位,再验证日志设施故障和进程崩溃。性能敏感路径检查输出延迟与模拟预算;重试不允许无界占用内存。
