trace数据上报-j9九游会登录

安装依赖库

安装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

获取上报参数

1. 在agentarts平台左侧导航栏中选择“运营运维 > 观测”，并进入“智能体列表”页面。
2. 单击“智能体接入”，填写智能体名称，并选择类型。类型按实际选择。
   图1 智能体接入
   
3. 填写完成后，单击“创建”等待平台自动创建接入信息，记录接入地址、鉴权信息、智能体id等信息。请妥善保管该信息。

   表1 接入信息说明

   参数	说明
   agent_id	智能体id。
   trace_endpoint	trace数据接入地址。
   trace_token	trace上报鉴权token。

   图2 获取接入地址、鉴权信息、智能体id等信息
   

上报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():
    # 模拟数据专用的会话 id 与用户 id
    mock_session_id = "test_session_12345"
    mock_user_id = "test_user"
    # 创建 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")
        root.set_attribute("gen_ai.conversation.id", mock_session_id)
        root.set_attribute("gen_ai.user.id", mock_user_id)
        root.set_attribute("input.value", "测试输入")
        # 创建 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.agent.name", agent_name)
            model_span.set_attribute("gen_ai.conversation.id", mock_session_id)
            model_span.set_attribute("gen_ai.user.id", mock_user_id)
            model_span.set_attribute("traceloop.workflow.type", "llm")
            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", "测试输出")
        root.set_attribute("output.value", "测试输出")
if __name__ == "__main__":
    test_connection()
    tracer_provider.shutdown() # 刷新数据至服务端
    print("测试 trace 数据已发送，请前往 agentarts 控制台查看。")

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

查看上报数据

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

示例：真实对话中的trace（调用链）数据上报

本示例中的脚本会启动一个本地交互式终端，您可以像聊天一样在终端输入问题跟智能体对话。在对话过程中，代码会自动创建root span和model span两层span，并在调用模型成功后，动态提取真实的提问、回复、token消耗以及网络耗时上报给agentarts。

本地环境准备与依赖安装：

请在你的电脑终端（windows的cmd或macos/linux的terminal）中执行以下命令，安装所需的python依赖库：

pip install opentelemetry-api==1.41.1
pip install opentelemetry-sdk==1.41.1
pip install opentelemetry-exporter-otlp==1.41.1
pip install openai==1.14.0
pip install python-dotenv==1.0.0

配置环境变量：

安装完成后，在您的代码文件夹下创建一个名为.env的文本文件。填写华为云maas服务的模型api key和agentarts平台上获取的真实凭证：

# ==========================================
# 1. 智能体大模型的 api 凭证（以接入 maas 的 openai 兼容接口为例）
# ==========================================
model_name=deepseek-v4-pro
model_url=https://api.modelarts-maas.com/openai/v1
model_api_key=换成在maas上申请的模型api_key
# ==========================================
# 2. 华为云 agentarts 观测接入凭证
# ==========================================
agent_id=换成智能体id
domain_id=换成华为云账号id（在控制台右上角“我的凭证”中复制，不要填假数据，否则会被平台隔离过滤）
user_id=换成华为云iam用户id（在控制台右上角“我的凭证”中复制，不要填假数据，否则会被平台隔离过滤）
# trace 上报通道配置
trace_endpoint=换成trace数据接入地址（格式如 apm-access.cn-southwest-2.myhuaweicloud.com）
trace_token=换成trace上报鉴权token

编写智能体调用及数据上报脚本：

创建一个名为agent_trace.py的代码文件，并填写如下内容：

import os
import time
import uuid
from openai import openai
from dotenv import load_dotenv
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
# 自动加载同目录下的 .env 文件
load_dotenv()
# 读取配置参数
agent_id = os.getenv("agent_id")
agent_name = os.getenv("agent_name")
trace_endpoint = os.getenv("trace_endpoint")
trace_token = os.getenv("trace_token")
user_id = os.getenv("user_id")
# 配置标准 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"
# 初始化 otel tracer 提供者
tracer_provider = tracerprovider()
tracer_provider.add_span_processor(batchspanprocessor(otlpspanexporter()))
trace.set_tracer_provider(tracer_provider)
tracer = trace.get_tracer(__name__)
def chat_with_agent(user_query: str, session_id: str):
    """模拟与智能体对话，并在执行过程中自动上报 trace 链路数据"""
    # 实例化大模型客户端（调用华为云 maas 的接口）
    client = openai(
        api_key=os.getenv("model_api_key"),
        base_url=os.getenv("model_url")
    )
    # 1. 启动最外层 root span，记录整个交互会话的生命周期
    with tracer.start_as_current_span("agent_dialogue_session") as root_span:
        root_span.set_attribute("gen_ai.span.type", "root")
        root_span.set_attribute("gen_ai.resource.id", agent_id)
        root_span.set_attribute("gen_ai.agent.name", agent_name)
        root_span.set_attribute("gen_ai.resource.type", "agent")
        root_span.set_attribute("gen_ai.call.type", "api")
        root_span.set_attribute("gen_ai.conversation.id", session_id) 
        root_span.set_attribute("gen_ai.user.id", user_id)
        root_span.set_attribute("input.value", user_query)               # 记录root节点的原始输入
        # 2. 启动大模型子 span，专门记录 llm 推理过程
        with tracer.start_as_current_span("llm_inference_call") as model_span:
            # 作用说明：标识当前节点类型为模型调用节点，用于控制台解析
            model_span.set_attribute("gen_ai.span.type", "model")
            # 作用说明：模型节点上也必须携带资源 id 与类型，防止 urn 路径拼接错乱
            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.agent.name", agent_name)
            model_span.set_attribute("gen_ai.conversation.id", session_id) 
            model_span.set_attribute("gen_ai.user.id", user_id)
            model_span.set_attribute("traceloop.workflow.type", "llm")
            # 作用说明：记录实际请求调用的模型名称
            model_span.set_attribute("gen_ai.request.model", os.getenv("model_name"))
            # 记录大模型 api 网络调用开始时间
            start_time = time.time()
            # 发起真实的大模型对话调用
            completion = client.chat.completions.create(
                model=os.getenv("model_name"),
                messages=[{"role": "user", "content": user_query}]
            )
            # 计算大模型请求真实时延
            duration = time.time() - start_time 
            # 动态捕获模型返回的真实响应数据与 token 消耗
            usage = completion.usage
            response_content = completion.choices[0].message.content
            # 3. 将真实捕获的运行时参数动态注入属性中
            model_span.set_attribute("gen_ai.usage.input_tokens", usage.prompt_tokens)      # 作用说明：记录输入 token
            model_span.set_attribute("gen_ai.usage.output_tokens", usage.completion_tokens)  # 作用说明：记录输出 token
            model_span.set_attribute("gen_ai.usage.total_tokens", usage.total_tokens)        # 作用说明：记录总 token 消耗
            model_span.set_attribute("gen_ai.client.operation.duration", str(duration))      # 作用说明：记录大模型调用耗时
            model_span.set_attribute("input.value", user_query)                              # 作用说明：记录真实提问
            model_span.set_attribute("output.value", response_content)                       # 作用说明：记录模型真实回复
        # 在 root span 上记录最终输出答案，保证调用链树根节点的输入/输出展示完整
        root_span.set_attribute("output.value", response_content)
        return response_content
if __name__ == "__main__":
    # 动态生成本轮对话的唯一会话 id，保证在平台“会话分析”中能聚合在一起
    current_session_id = f"sess-{uuid.uuid4().hex[:12]}"
    print(f"==================================================")
    print(f" 智能体运行时已启动！会话 id: {current_session_id}")
    print(f"==================================================")
    while true:
        user_input = input("\nuser: ")
        if user_input.strip().lower() in ["exit", "quit", "q"]:
            print("正在退出并刷新数据上报...")
            break
        print("智能体正在思考并上报调用链...")
        reply = chat_with_agent(user_input, current_session_id)
        print(f"agent: {reply}")
    # 刷新 trace 缓冲并一键上传
    tracer_provider.shutdown()
    print("数据刷新上报完成！")

执行测试，验证上报数据：

在您的代码文件夹下，打开终端并运行：

python agent_trace.py

运行后，可与智能体进行会话，可通过ctrl c命令退出会话。退出后，登录agentarts平台，在“运营运维 > 观测 > 智能体列表”页面，单击对应的智能体名称。在“调用链分析”中可以看到调用链数据。

常见问题

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

请按以下顺序排查：

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

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

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

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

j9九游会登录的解决方案：在您的代码中，不仅要给最外层的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")
    # ... 后续属性