Trace数据上报

Trace数据用于记录智能体的单次请求详情，包括调用链路、节点耗时、模型输入输出等。

下面以Python语言开发的智能体为例，介绍如何将Trace数据上报至AgentArts观测平台。

第三方智能体上报的Trace数据将直接写入您的华为云应用性能管理APM服务。APM会根据上报的数据量按需计费。为避免在生产环境因大并发测试产生意外账单，请在部署前仔细阅读APM计费说明。

安装依赖库

安装OpenTelemetry Python SDK及相关依赖库。要求Python 3.9或以上版本。

pip install opentelemetry-distro==0.62b1
pip install opentelemetry-api==1.41.1
pip install opentelemetry-exporter-otlp==1.41.1
pip install traceloop-sdk==0.60.0

获取上报参数

在AgentArts平台左侧导航栏中选择“运营运维 > 观测”，并进入“智能体列表”页面。
单击“智能体接入”，填写智能体名称，并选择类型。类型按实际选择。

图1 智能体接入
填写完成后，单击“创建”等待平台自动创建接入信息，记录接入地址、鉴权信息、智能体ID等信息。请妥善保管该信息。

表1 接入信息说明

参数

说明

agent_id

智能体ID。

trace_endpoint

Trace数据接入地址。

trace_token

Trace上报鉴权Token。

图2 记录接入地址、鉴权信息、智能体ID等信息

表1 接入信息说明
参数	说明
agent_id	智能体ID。
trace_endpoint	Trace数据接入地址。
trace_token	Trace上报鉴权Token。

上报Trace数据

配置参数信息：

在上报Trace数据前，需配置环境变量。服务名称（OTEL_SERVICE_NAME）必须遵循AgentArts.{{智能体ID}}.{{版本号}} 的格式（版本号默认填写default）。

OTEL_SERVICE_NAME=AgentArts.{智能体ID}.default
OTEL_EXPORTER_OTLP_TRACES_HEADERS=Authentication={trace_token}
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT={trace_endpoint}
OTEL_EXPORTER_OTLP_TRACES_INSECURE=true

上报Trace数据示例代码：

本示例为连通性测试示例，为首次接入AgentArts时，验证上报地址、Token 和智能体ID是否配置正确使用，并确认平台能否正常接收数据。此阶段使用手动构造的静态数据。

import os
import time
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import BatchSpanProcessor

# 1. 替换为您的真实接入凭证
AGENT_ID = "您的智能体ID"
AGENT_NAME = "您的智能体名称"
TRACE_ENDPOINT = "您的Trace接入地址"
TRACE_TOKEN = "您的Trace鉴权Token"

# 2. 配置 OTel 环境变量
os.environ["OTEL_SERVICE_NAME"] = f"AgentArts.{AGENT_ID}.default"
os.environ["OTEL_EXPORTER_OTLP_TRACES_HEADERS"] = f"Authentication={TRACE_TOKEN}"
os.environ["OTEL_EXPORTER_OTLP_TRACES_ENDPOINT"] = TRACE_ENDPOINT
os.environ["OTEL_EXPORTER_OTLP_TRACES_INSECURE"] = "true"

tracer_provider = TracerProvider()
tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)

def test_connection():
    # 创建 Root Span (根节点)
    with tracer.start_as_current_span("test_user_request") as root:
        root.set_attribute("gen_ai.span.type", "root")
        root.set_attribute("gen_ai.resource.id", AGENT_ID)
        root.set_attribute("gen_ai.agent.name", AGENT_NAME)
        root.set_attribute("gen_ai.resource.type", "agent")
        root.set_attribute("gen_ai.application_name", "default")
        root.set_attribute("gen_ai.environment", "default")
        root.set_attribute("gen_ai.call.type", "API")

        # 创建 Model Span (大模型子节点)
        with tracer.start_as_current_span("test_llm_call") as model_span:
            model_span.set_attribute("gen_ai.span.type", "model")
            model_span.set_attribute("gen_ai.resource.id", AGENT_ID)
            model_span.set_attribute("gen_ai.resource.type", "agent")
            model_span.set_attribute("gen_ai.request.model", "deepseek-v4-pro")

            # 【注意】此处为模拟数据，仅供测试连通性，实际场景需要从真实的响应中提取参数
            time.sleep(0.5) 
            model_span.set_attribute("gen_ai.usage.input_tokens", "100")
            model_span.set_attribute("gen_ai.usage.output_tokens", "200")
            model_span.set_attribute("gen_ai.usage.total_tokens", "300")
            model_span.set_attribute("gen_ai.client.operation.duration", "0.5")
            model_span.set_attribute("input.value", "测试输入")
            model_span.set_attribute("output.value", "测试输出")

if __name__ == "__main__":
    test_connection()
    tracer_provider.shutdown() # 强制刷新内存数据至服务端
    print("测试 Trace 数据已发送，请前往 AgentArts 控制台查看。")

为了保证您的第三方 Trace 数据能够被 AgentArts 观测控制台正确识别、解析并展示在各种分析图表中，您在手动埋点上报时，必须严格遵守以下字段命名与数据类型规范。关于所有可设置的Attribute字段及含义，请参考OpenTelemetry字段映射。

表2 Attribute说明
Attribute	是否必填	说明
gen_ai.span.type	是	区分节点类型。Root Span填写节点填 "root"，Model Span节点填 "model"（对Model）。
gen_ai.resource.id	是	智能体ID，直接作为字符串写入（对Root Span和Model Span均需携带）。
gen_ai.resource.type	是	资源类型，固定填写"agent"（对Root Span和Model Span均需携带）。
gen_ai.conversation.id	是	用户本次对话的唯一会话 ID。用于在平台“会话分析”中串联并还原上下文。
gen_ai.agent.name	是	智能体名称。
gen_ai.call.type	是	触发类型固定填写“API”。
gen_ai.request.model	是	调用的模型名称（如 "deepseek-v4-pro"）。
gen_ai.usage.input_tokens	是	输入Token消耗量。
gen_ai.usage.output_tokens	是	输出Token消耗量。
gen_ai.usage.total_tokens	是	Token总消耗量。
gen_ai.client.operation.duration	否	模型调用真实耗时。

查看上报数据

数据上报后，在“运营运维 > 观测 > 智能体列表”页面，单击对应的智能体名称，在“调用链分析”中可以看到调用链数据。

图3 查看上报数据

常见问题

运行代码后，观测页面看不到Trace数据怎么办？

请按以下顺序排查：

检查接入参数：确认agent_id、trace_endpoint、trace_token是否与数据上报准备中获取的信息一致。
检查服务名称格式：确认OTEL_SERVICE_NAME遵循AgentArts.{智能体ID}.default格式。
检查网络连通性：确认网络是否能连通Trace接入地址。
等待数据同步：数据上报后通常需要几分钟才能在观测页面展示，请稍后再查看。

为什么在平台“调用链分析”中，单击模型节点的“指标”页签时报错，或者 F12 抓包发现后端 API 路径中出现了双斜杠（如/agent//span/...）

原因：出现该报错是由于您只在最外层的根节点（Root Span）上设置了智能体URN关联属性，而漏掉了在模型节点（Model Span）上设置gen_ai.resource.id和gen_ai.resource.type属性。

在AgentArts观测功能中，当您单击不同的节点查看调用链的Span详情时，页面会实时读取该节点上的属性来拼接查询API路径。如果模型节点缺少了这两个属性，路径就会因为缺省而拼错（出现双斜杠），导致页面请求报错、数据无法展示。

解决方案：在您的代码中，不仅要给最外层的Root Span设参，每一个内部创建的子Span（如大模型调用）也必须强制上报这两个对齐标签：

with tracer.start_as_current_span("test_llm_call") as model_span:
    # 必须给子节点也绑定智能体ID和资源类型，保证页面路由拼接正常
    model_span.set_attribute("gen_ai.resource.id", AGENT_ID)
    model_span.set_attribute("gen_ai.resource.type", "agent")
    model_span.set_attribute("gen_ai.span.type", "model")
    # ... 后续属性

图4 报错样例