AI 工作台

主题

bkmonitor2026-05-24apmservice-configlog-relationcode-redefinecode-remarkapp-level
需求概述方案

APM 支持应用级别配置 ​

0x01 背景 ​

a. 痛点 ​

当前 APM 的服务关联配置全部以 (bk_biz_id, app_name, service_name) 为粒度。

日志关联、返回码重定义和返回码备注均没有「应用级（全局）」或「按服务列表共享」的概念。

用户想为应用下所有服务设置统一配置时，只能逐服务手动配置，成本高且易遗漏。

b. 现状 ​

  • 核心模型为 ServiceBase（抽象基类），下挂 7 个子类子表。
  • 各子表的查询、写入散落在不同调用方，模式不统一。
  • 若只改造部分子表，后续扩展时容易重复劳动、遗漏保护逻辑。

c. 目标 ​

  • 支持应用级别（全局）的日志关联、返回码重定义和返回码备注配置。
  • 支持指定服务列表作为配置生效范围，而不仅是单个服务。
  • 全局配置与服务级配置可共存。
  • 返回码备注展示优先级为服务级覆盖全局。
  • 改造后模式统一，便于维护和扩展。

0x02 需求范围 ​

a. 日志关联（LogServiceRelation） ​

  • Setup 写入、按应用名查询、服务级配置界面展示，均需支持应用级关联。
  • 获取关联信息需收口，避免多处自行拼 (bk_biz_id, app_name, service_name) 条件。

b. 返回码重定义（CodeRedefinedConfigRelation） ​

  • List、Set 接口需支持全局与跨服务共享规则。
  • 支持按 service_names 展开写入，以及按 scope 选择更新策略（服务级 / 全局 / 全量）。
  • 全局返回码配置页面仅 RPC 场景需要展示（应用配置模块的业务约束）。

c. 返回码备注（Code Remarks） ​

  • Get、Set 接口需同时支持应用级（全局）视角与服务视角。
  • 支持框架内置错误码默认备注补齐。
  • 增加返回码备注的统一管理能力，支持全局生效与按服务列表生效。

d. 非目标与后续议题 ​

  • 除 Log、CodeRedefine 外，ServiceBase 下另有 5 张子表，建议后续统一纳入查询、写入收口范围。
  • 但本轮核心交付仍聚焦在日志关联、返回码重定义与返回码备注。

0x03 设计约束 ​

a. 配置分层 ​

  • 日志关联、返回码重定义等关系型配置继续基于 ServiceBase 体系扩展应用级能力。
  • 返回码备注继续使用 ApmMetaConfig 维护，不进入关系表。
  • 返回码备注与返回码重定义共用业务概念，但存储模型和写入路径保持分离。

b. 作用域与兼容 ​

  • 关系表配置需支持全局与服务级两种作用域，并保持旧服务视角调用方式可兼容。
  • 返回码备注需同时支持全局视角与服务视角。
  • 返回码备注保留 kind 作为调用视角维度。
  • 返回码备注服务视角返回值保持 {code: remark} 不变。
  • 返回码备注全局视角改为批量维护 remarks。

c. 展示与默认值 ​

  • 返回码备注展示优先级固定为：服务规则覆盖全局规则（内置默认 < 全局规则 < 服务规则）。
  • 框架内置错误码默认备注仅在服务视角读取时做后置补齐，全局视角不返回内置默认项。
  • 返回码重定义全局规则下发到采集端时，仍需支持应用级通配生效。

d. 写入保护 ​

  • 引入全局配置后，服务级写入需从机制上排除对全局记录的误改。
  • 返回码备注服务级写入需避免同一服务在相同 (kind, code) 下命中多条服务规则。

e. 代码清理 ​

  • 部分接口、方法可能已无引用，制定实施方案时需识别并标记待废弃/删除项。

0x04 参考 ​