APMPlus

APMPlusExporter 将 span 数据以 OTLP（gRPC）协议上报至火山引擎 APMPlus 平台。除追踪链路外，它还会通过内置的指标上报器采集模型调用次数、token 用量、操作耗时、异常次数以及工具耗时等指标，写入 APMPlus 的指标面板。

何时使用

需要在火山引擎 APMPlus 平台上统一观测智能体的调用链路；
需要模型级别的指标分析，如 token 消耗、调用延迟与错误率；
生产环境中需要成本追踪与性能监控。

使用示例

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.demo_tools import get_city_weather
from veadk.tracing.telemetry.exporters.apmplus_exporter import APMPlusExporter
from veadk.tracing.telemetry.opentelemetry_tracer import OpentelemetryTracer

exporters = [APMPlusExporter()]
tracer = OpentelemetryTracer(exporters=exporters)

agent = Agent(tools=[get_city_weather], tracers=[tracer])

runner = Runner(agent=agent, short_term_memory=ShortTermMemory())

asyncio.run(runner.run(messages="北京天气怎么样？", session_id="session_id_demo"))

也可以通过 APMPlusExporterConfig 显式传入连接参数：

from veadk.tracing.telemetry.exporters.apmplus_exporter import (
    APMPlusExporter,
    APMPlusExporterConfig,
)

exporter = APMPlusExporter(
    config=APMPlusExporterConfig(
        endpoint="http://apmplus-cn-beijing.volces.com:4317",
        app_key="your-apmplus-app-key",
        service_name="apmplus_veadk_demo",
    )
)

参数

构造参数

APMPlusExporter 的连接参数由 config 字段承载，类型为 APMPlusExporterConfig；不传时各字段自动从对应环境变量读取。

参数	类型	默认值	说明
`config`	`APMPlusExporterConfig`	自动从环境变量读取	APMPlus 连接与认证配置。
`resource_attributes`	`dict`	`{}`	附加到 span 的资源属性；导出器会自动并入 `service.name`。
`headers`	`dict`	`{}`	附加的请求头；导出器会自动并入认证头 `x-byteapm-appkey`。

APMPlus 连接配置

config 为 APMPlusExporterConfig，各字段默认从 APMPlusConfig 读取，环境变量如下：

配置项	环境变量	类型	默认值	说明
`endpoint`	`OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT`	`str`	`http://apmplus-cn-beijing.volces.com:4317`	APMPlus OTLP 接入点（gRPC）。
`app_key`	`OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY`	`str`	未设置时自动获取 APMPlus 令牌	应用程序密钥，用于认证。
`service_name`	`OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME`	`str`	`veadk_tracing`	服务名，显示在 APMPlus 控制台，用于标识来源。

app_key 未通过环境变量提供时，导出器会调用火山引擎鉴权自动获取 APMPlus 令牌，因此需要配置有效的火山引擎凭证。endpoint 使用 gRPC 协议、以非加密方式连接。

环境变量配置

export OBSERVABILITY_OPENTELEMETRY_APMPLUS_ENDPOINT="http://apmplus-cn-beijing.volces.com:4317"
export OBSERVABILITY_OPENTELEMETRY_APMPLUS_API_KEY="your-apmplus-app-key"
export OBSERVABILITY_OPENTELEMETRY_APMPLUS_SERVICE_NAME="apmplus_veadk_demo"

也可以让 Agent 依据环境变量自动挂载 APMPlus 导出器，无需显式构造：

export ENABLE_APMPLUS=true

设置 ENABLE_APMPLUS=true 后，即便智能体未显式提供 tracers，Agent 也会自动创建 OpentelemetryTracer 并挂载 APMPlusExporter。

概览

快速开始

核心组件

可观测

扩展

前端

安全

何时使用

使用示例

参数

构造参数

APMPlus 连接配置

环境变量配置

​何时使用

​使用示例

​参数

​构造参数

​APMPlus 连接配置

​环境变量配置

何时使用

使用示例

参数

构造参数

APMPlus 连接配置

环境变量配置