Skip to content

refactor(metrics): 解耦 Portal 指标打点与 Exporter - #814

Draft
feng-95 wants to merge 4 commits into
volcengine:mainfrom
feng-95:refactor/apmplus-meter-uploader
Draft

refactor(metrics): 解耦 Portal 指标打点与 Exporter#814
feng-95 wants to merge 4 commits into
volcengine:mainfrom
feng-95:refactor/apmplus-meter-uploader

Conversation

@feng-95

@feng-95 feng-95 commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

改动说明

本次改造将 VeADK Portal 指标的“执行打点”和“创建导出链路”拆分为两项独立职责:

  • LLM、Tool、Skill 指标始终执行打点,不再检查 ENABLE_APMPLUSAPMPlusExporter 或其他 Exporter 是否存在;
  • PortalMetricRecorder 直接通过 OpenTelemetry Global MeterProvider 创建测量工具并记录;
  • APMPlusExporter 不再创建或注册指标记录器,只在当前仍为 _ProxyMeterProvider 时兜底创建带 APMPlus Reader 的 Global MeterProvider
  • 已有真实 Global MeterProvider 时,APMPlus 不替换 Provider、不追加 Reader,也不接管其生命周期;
  • 删除基于 Exporter 激活的 MetricUploaderRegistry,进程内只保留一份 portal_metrics.portal_metric_recorder

修改原因

旧实现把 Portal 指标是否打点绑定在 APMPlus Exporter 注册流程上,会产生两个问题:

  1. 业务已经配置 Global MeterProvider、但没有启用 APMPlus 时,VeADK 指标不会执行打点;
  2. 指标记录器同时承担 Provider、Reader 和 Exporter 创建职责,埋点逻辑与导出配置互相耦合。

改造后,VeADK 只负责产生指标;由业务配置、自动埋点或 APMPlus 兜底创建的 Global MeterProvider 决定是否以及向哪里导出。

运行规则

当前状态 VeADK 打点行为 APMPlus 行为 外部输出
未启用 APMPlus,未配置真实 Provider 始终调用代理测量工具 不创建 Provider 无;默认代理直接丢弃
未启用 APMPlus,已有真实 Provider 指标进入已有 Provider 不参与 由已有 Reader / Exporter 决定
启用 APMPlus,当前为 _ProxyMeterProvider 指标进入后续安装的 Provider 创建 APMPlus Provider、Reader 和 Exporter APMPlus
启用 APMPlus,已有真实 Provider 指标进入已有 Provider 不替换、不追加 Reader 由已有 Reader / Exporter 决定

OpenTelemetry 1.37.0 会在安装真实 Provider 后,将已有代理测量工具绑定到真实 Provider。安装前发生的打点不会缓存或补报。

与 Trace 的关系

Trace 与 Metrics 保持正交:

  • 已有 Global TracerProvider 时,沿用 fix(tracing): trust preconfigured provider for APMPlus #813 的规则,跳过 APMPlus Span Processor 注册,避免 Trace 重复上报;
  • Portal 指标始终打点,不依赖 Trace Provider 或 APMPlus Span Processor 是否注册;
  • 已有 Global MeterProvider 时,指标始终交给该 Provider。

依赖和合入顺序

  1. fix(tracing): trust preconfigured provider for APMPlus #813 已合入 main,本次没有修改其分支;
  2. fix(tracing): register exporters added after initialization #810 远端分支仍为 018cc56dbad7e8fcf192276c7874cd3c252f194d,本次没有更新;
  3. refactor(metrics): 解耦 Portal 指标打点与 Exporter #814 依赖 fix(tracing): register exporters added after initialization #810,按 fix(tracing): trust preconfigured provider for APMPlus #813fix(tracing): register exporters added after initialization #810refactor(metrics): 解耦 Portal 指标打点与 Exporter #814 的顺序合入。

#814 已重放到最新 origin/main。本次最终提交为 e064701de0f3e40d6746cf0c51bdcdce56e5f2e5

E2E 验证

场景 APMPlus Exporter 数量 Global Provider / Reader 云端 span / 唯一 span 云端 gen_ai_chat_count
未启用 APMPlus,未配置全局 Provider 0 _ProxyMeterProvider / 0 0 / 0 0 条时序
未启用 APMPlus,代码预配置全局 Provider 0 MeterProvider / 1 4 / 4 1
环境变量启用 APMPlus,无预配置 Provider 1 MeterProvider / 1 4 / 4 1
手动传入 APMPlusExporter(),无预配置 Provider 1 MeterProvider / 1 4 / 4 1
环境变量启用 APMPlus,代码预配置全局 Provider 1 MeterProvider / 1 4 / 4 1
手动传入 APMPlusExporter(),代码预配置全局 Provider 1 MeterProvider / 1 4 / 4 1
环境变量与手动 Exporter 同时启用,代码预配置全局 Provider 1 MeterProvider / 1 4 / 4 1
opentelemetry-instrument 自动埋点并启用 APMPlus 1 MeterProvider / 1 5 / 5 1

7 个存在导出链路的指标查询都只有 1 条时序,且 current=min=max=1。所有云端 Trace 的 span 总数与唯一 span 数一致,错误 span 为 0。

自动化检查

  • pytest -q tests/test_agent.py tests/test_portal_metrics.py tests/test_tracing.py tests/test_tracing_content.py:48 项通过;
  • Ruff 0.11.12 检查和格式检查:通过;
  • git diff --check:通过;
  • 完整 pre-commit 在安装 gitleaks 环境时被本机旧 Go 阻塞,原因是当前 Go 无法解析 gitleaks 的 Go 1.23 toolchain 指令;该问题发生在 hook 安装阶段,Ruff 已单独执行并通过。

测试报告

  • 飞书测试报告
  • 本地报告:/Users/bytedance/go/src/code.byted.org/byteapm/docs-feng/veadk-python/VeADK_APMPlus_MeterUploader_优化测试报告.md

@feng-95
feng-95 force-pushed the refactor/apmplus-meter-uploader branch from 15fa31d to e064701 Compare August 5, 2026 08:01
@feng-95 feng-95 changed the title refactor(metrics): decouple APMPlus meter uploader refactor(metrics): 解耦 Portal 指标打点与 Exporter Aug 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant