跳到主要内容

可观测性（Telemetry / HPA）

快速上手​

  1. 在 values 的 modules/telemetry.yaml 配置需要的 trace/metrics 导出目标， 使用对应 otelcol 配置准备 Collector。
  2. 生成配置并运行服务，使用一次 RPC 检查 trace，查看服务内置 metrics。
  3. 新业务 action 沿用自动 trace；需要额外业务指标时使用已有 telemetry API。
  4. 需要自动伸缩时，在 modules/hpa.yaml 配置查询与策略，注册业务就绪和状态检查。 Kubernetes 还需指标适配器与原生 HPA，按HPA 接入步骤验证。

设计与故障处理见可观测性与动态策略白皮书。 订单撮合、搜索索引和战斗房间的指标用途示例见应用场景。

定制与详细设计​

OpenTelemetry 封装​

src/server_frame/rpc/telemetry/ 提供 OpenTelemetry 封装：

  • rpc_trace：tracer/span 管理，task action 自动挂载 trace（task_action_base 集成）；
  • rpc_global_service、opentelemetry_utility：全局 meter/tracer provider；
  • exporter/：Prometheus 导出器（file / push 两种）；OTLP 导出由 opentelemetry-cpp 自带导出器在 rpc_global_service 中接入。

配置由 svr.telemetry.config.proto 定义，实例配置在 logic.telemetry 段；部署侧见 install/cloud-native/values/default/modules/telemetry.yaml 与 install/otelcol/（Collector 启动脚本， daemon / systemd 两种模式）。

Trace 传播​

  • CS 链路：客户端可在 CSMsg.head.rpc_trace 中传入上下文，服务侧据此建立父子 span； 未提供上下文时由 task action 开始 trace。atgateway 透传业务消息体，不负责注入业务 trace；
  • SS 链路：rpc_context（src/server_frame/rpc/rpc_context.{h,cpp}）随 SSMsg 传播 trace 上下文， 跨服务串联 span；
  • DB 调用：Redis 命令作为子 span。

Metrics 与 HPA​

src/server_frame/logic/hpa/ 实现 HPA 自动伸缩支持：

  • pull/prometheus/：从 Prometheus 拉取指标；
  • discovery provider：更新本进程的服务发现 metadata 标签，供 logic_hpa_discovery_select_mode（如 kReady） 选择目标节点（dtmq 等组件按此选择副本节点）。
  • 自定义 policy 与 discovery：拉取业务指标、计算参数，并通过 etcd 写入和监听分发业务策略；
  • 副本控制：发布预期副本数和仍 Ready 节点的状态索引，分阶段调整 hpa_scaling_target / hpa_scaling_ready。

状态检查、对象转移和扩缩容执行器需要按业务接入。指标采集成功不表示策略已应用， 详见动态策略最小接入与HPA 详细设计。

router_manager_set、dispatcher 等也暴露内置 metrics（对象数、task 数、RPC 延迟）。

日志​

  • 框架日志走 atframe_utils 日志模块（libatapp 日志 sink 配置在 atapp YAML）；
  • 结构化日志协议：protocol/private/protocol/log/（svr.mon.log.proto 监控日志、svr.oss.log.proto OSS 日志）；
  • 部署侧由 vector（K8s）或本地文件采集，modules/vector.yaml 配置。