跳转到内容

运行日志与故障证据 ​

实现状态: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. 验收 ​

验证本地写入、字符转义、查询、收集断线与缓存水位,再验证日志设施故障和进程崩溃。性能敏感路径检查输出延迟与模拟预算;重试不允许无界占用内存。

8. 关联设计 ​

基于 MIT 许可发布