OpenTelemetry协议字段映射
在AgentArts观测看板中，您看到的每一个图表（如用户数趋势、Token消耗排行、平均耗时等），底层均依赖于您通过OpenTelemetry(OTel) SDK上报的数据。
为了方便您快速对照，下表将AgentArts观测看板上的业务指标与您在代码探针中需要上报的底层字段进行了统一映射。
当您了解了字段的映射关系后，如需在代码中进行具体集成，请直接参考以下操作指南：
- Trace（调用链）上报实操：请阅读上报Trace数据章节。
- Metric（指标）上报实操：请阅读上报Metric数据章节。
当智能体运行过程中涉及Skill（技能）调用时，Skill信息通过在工具执行Span（如skill_tool、skill_complete）上设置gen_ai.skill.*属性进行链路追踪，不创建独立Span；Skill的调用次数、平均耗时、成功率等统计趋势通过gen_ai.skill.*指标上报，平台基于上报的指标与维度进行聚合计算与展示。示例如下：
<root span>
├── <model/chat span> ← LLM决策调用skill_tool
├── <tool execute span: skill_tool> ← gen_ai.operation.name="load_skill"
│ └── event: skill.loaded {skill.name, skill.path}
├── <model/chat span> ← Skill步骤推理
├── <tool execute span: skill_complete> ← gen_ai.operation.name="release_skill"
│ └── event: skill.released {skill.name}
└── <model/chat span> ← 最终回答 Trace调用链属性
本节文档定义上报到华为云AgentArts平台可观测中Trace数据的字段规范，包括每个字段的含义、数据类型和取值示例。
文中所有定义的Trace字段是华为云参考OpenTelemetry标准以及大语言模型应用领域概念制定的，能够反映Agent调用时的输入输出请求、Token消耗、调用时延等关键操作。Agent 可观测控制台中的会话分析、调用链、Token 用量与工具分析统计等功能，均基于这些字段计算和展示。此语义字段将随着社区的发展而不断更新和优化。
Span类型
Span类型参考OpenTelemetry开源标准（https://opentelemetry.io/docs/specs/semconv/gen-ai/）和OpenInference（https://arize-ai.github.io/openinference/spec/）定义。下表列举Span类型 gen_ai.span.kind 的所有取值及其对应的 gen_ai.operation.name。其中WORKFLOW， MEMORY，RETRIEVER，RERANKER ，EMBEDDING为可选类型，仅在接入支持记忆，支持编排管道或RAG的框架时出现。
查阅字段时，请先确认Span类型，再参见对应章节。
| gen_ai.span.kind | gen_ai.operation.name | 说明 |
|---|---|---|
| AGENT | invoke_agent；create_agent | Agent应用入口 |
| STEP | react_step；react | ReAct 推理与行动轮次 |
| LLM | chat；text_completion；generate_content | 大模型调用 |
| TOOL | execute_tool | 工具调用 |
| WORKFLOW | workflow；task | 工作流/链路编排环节 |
| MEMORY | memory.create_memory_session；memory.add_messages等 | 记忆调用 |
公共属性
所有span都应该上报的属性内容，主要内容为用户和智能体信息，用于做用户分析和会话分析等。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | Span类型，(AGENT，LLM，TOOL，STEP，MEMORY) | LLM |
| gen_ai.resource.id | string | 必须 | 智能体 ID，华为云可观测界面的智能体ID | 9e880ba442564a3db017bac9944f9a07 |
| gen_ai.resource.type | string | 必须 | 资源类型：agent / multiagents / workflow | agent |
| gen_ai.conversation.id | string | 推荐 | 会话 ID（Session ID） | session-20261026_105132 |
| gen_ai.user.id | string | 推荐 | 用户 ID，智能体应用的C端用户标识 | user_20261026_13530c8a |
| gen_ai.agent.name | string | 推荐 | 智能体名称 | myAgent |
| gen_ai.agent.type | string | 否 | 智能体类型 | hermes，codex |
| domain.id | string | 否 | 账号 ID，用于租户之间的数据安全隔离 | 07f3037b29e645a5adf662d70a4155fd |
| resource_version | string | 否 | 智能体版本 | 0.1.1 |
AGENT
AGENT类型Span描述一次Agent问答的完整生命周期（Agent应用入口，Trace根节点），例如可能涉及到LLM以及Tool的多次调用，一步步决策得出最终答案。当Agent通过delegate派发子Agent时，子Agent的AGENT Span显式挂接在派发回合之下，汇总回合也会挂接回根节点。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | span类型 | AGENT |
| gen_ai.operation.name | string | 否 | 操作名称，Agent 应用入口调用 | invoke_agent；create_agent |
| gen_ai.agent.name | string | 必须 | 智能体名称 | myAgent |
| gen_ai.input.messages | string | 推荐 | 用户输入内容 | [{"role":"user","parts":[{"type":"text","content":"今天天气怎么样？"}]}] 今天天气怎么样？ |
| gen_ai.output.messages | string | 推荐 | Agent 最终回复内容 | [{"role":"assistant","parts":[{"type":"text","content":"北京今天晴，25°C"}]}] |
| gen_ai.usage.input_tokens | int | 必须 | 该回合累计输入 Token 数 | 1280 |
| gen_ai.usage.output_tokens | int | 必须 | 该回合累计输出 Token 数 | 356 |
| gen_ai.usage.total_tokens | int | 必须 | 该回合累计 Token 总数（输入 + 输出） | 1636 |
LLM
LLM类型Span描述一次大模型推理调用，覆盖请求、响应与Token用量。LLM Span通常作为AGENT或STEP Span的子节点。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | span类型 | LLM |
| gen_ai.operation.name | string | 推荐 | 大模型调用操作名 | chat；text_completion；generate_content |
| gen_ai.request.model | string | 必须 | 请求使用的模型标识 | maas-DeepSeek-V4.1-Flash |
| gen_ai.request.temperature | number | 否 | 采样温度 | 0.7 |
| gen_ai.request.max_tokens | int | 否 | 最大输出 Token 上限 | 4096 |
| gen_ai.request.is_stream | bool | 否 | 是否流式返回 | true |
| gen_ai.request.top_k | int | 否 | Top-K 采样参数 | 50 |
| gen_ai.request.frequency_penalty | number | 否 | 频率惩罚系数 | 0.1 |
| gen_ai.request.presence_penalty | number | 否 | 存在惩罚系数 | 0.1 |
| gen_ai.request.seed | int | 否 | 随机采样种子 | 42 |
| gen_ai.request.stop_sequences | string[] | 推荐 | 停止序列 | ["stop"] |
| gen_ai.input.messages | string | 推荐 | 请求消息列表 JSON | [{"role":"user","parts":[{"type":"text","content":"1+1=?"}]}] |
| server.address | string | 否 | 模型服务地址 | api.example.com |
| server.port | int | 否 | 模型服务端口 | 443 |
| http.request.method | string | 否 | HTTP 请求方法 | POST |
| gen_ai.response.model | string | 推荐 | 实际响应模型标识 | maas-DeepSeek-V4.1-Flash |
| gen_ai.response.finish_reasons | string[] | 推荐 | 模型返回的结束原因 | ["stop"]; ["stop", "length"]; ["stop", "length", "error"] |
| gen_ai.response.time_to_first_token | int | 推荐 | 流式响应场景下的首 Token 时延(ms) | 128 |
| gen_ai.output.messages | string | 推荐 | 响应消息列表 JSON | [{"role":"assistant","parts":[{"type":"text","content":"2"}]}] |
| gen_ai.usage.input_tokens | int | 必须 | 本次调用输入 Token 数 | 145 |
| gen_ai.usage.output_tokens | int | 必须 | 本次调用输出 Token 数 | 23 |
| gen_ai.usage.total_tokens | int | 必须 | 本次调用 Token 总数（输入 + 输出） | 168 |
| gen_ai.usage.cache_read.input_tokens | int | 否 | 缓存命中的输入 Token 数 | 100 |
| gen_ai.usage.cache_creation.input_tokens | int | 否 | 缓存写入的输入 Token 数 | 45 |
TOOL
TOOL类型Span描述一次工具调用，例如可能调用计算器或者请求天气API获取最新的天气情况。TOOL Span通常挂接在请求该工具调用的STEP Span之下；无STEP时直接挂接AGENT Span。当工具执行表示将Skill加载到上下文中时，应设置gen_ai.skill.*相关字段。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | span类型 | TOOL |
| gen_ai.operation.name | string | 推荐 | 工具调用操作名 | execute_tool |
| gen_ai.tool.name | string | 必须 | 工具名称 | calculator |
| gen_ai.tool.call.arguments | string | 必须 | 工具调用参数 | {"expression": "1+1"} |
| gen_ai.tool.call.result | string | 必须 | 工具返回结果 | "2" |
| gen_ai.tool.call.id | string | 否 | 工具 id | call_t0lnn230sdzti4pps48qz6yw |
| gen_ai.tool.type | string | 否 | 工具类型 | function |
| gen_ai.skill.id | string | 否 | skill 的唯一标识ID（调用skill时上报） | skill_d45462 |
| gen_ai.skill.name | string | 推荐 | skill名称（调用skill时必须上报） | code_review |
| gen_ai.skill.version | string | 否 | skill版本（调用skill时上报） | 0.2.1 |
STEP
STEP类型Span描述ReAct（推理-行动）循环中的一轮推理决策步，作为AGENT与TOOL/LLM之间的中间层。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | span类型 | STEP |
| gen_ai.operation.name | string | 否 | ReAct推理步操作名 | react_step;react |
| gen_ai.react.finish_reason | string | 否 | 该推理步的结束原因 | tool_calls;stop |
| gen_ai.react.round | int | 否 | ReAct迭代轮次，通常从1开始递增 | 9 |
WORKFLOW
WORKFLOW类型Span描述一次工作流/链路编排层的调度节点，位于Agent问答链路中除AGENT、STEP、LLM、TOOL之外的编排环节，通常作为AGENT Span的子节点挂接（其下可再挂LLM、STEP、TOOL子节点）。
说明：OpenTelemetry社区尚未具备该类型Span的语义规范。当前WORKFLOW Span仅用于涉及工作流编排，RAG等场景。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | span类型 | WORKFLOW |
| gen_ai.operation.name | string | 否 | 编排节点操作名（链/图/工作流节点统一标识） | workflow；task |
| input.value | string | 否 | 输入内容 | 你好 |
| output.value | string | 否 | 输出内容 | 下午好呀！今天过得怎么样？\n\n有什么我可以帮您的吗？无论是计算一些数据、查看文件内容，还是聊聊天，我都很乐意奉陪！ |
MEMORY
MEMORY类型Span描述一次记忆服务调用，覆盖记忆会话管理、消息写入与语义检索。
| 属性名 | 类型 | 是否必填 | 说明 | 示例值 |
|---|---|---|---|---|
| gen_ai.span.kind | string | 必须 | span类型 | MEMORY |
| gen_ai.operation.name | string | 否 | 记忆操作名称 | memory.create_memory_session；memory.add_messages；memory.search_memories |
| gen_ai.memory.type | string | 必须 | 记忆类型 | short_term；long_term |
| gen_ai.memory.operation | string | 否 | 记忆调用方法名 | add_messages；search_memories；get_last_k_messages |
| gen_ai.memory.session.id | string | 否 | 记忆会话 ID | sess-8f3a5d2c |
| gen_ai.memory.space.id | string | 否 | 记忆空间 ID | spc-7e2b9c41 |
| gen_ai.memory.endpoint | string | 否 | 记忆服务端点 | memory.cn-southwest-301.myhuaweicloud.com |
| gen_ai.memory.input.messages | string | 否 | 请求正文 | {"session_id": "11c7d27d-4519-4dd9-bb1b-574150cdecc9", "k": 10, "space_id": "4c35aeb5-8223-4002-931f-44346c2fdad4"} |
| gen_ai.memory.output.messages | string | 否 | 响应正文 | {"items": [{"id": "b608376f-87a1-4116-9b57-60ad608af3ca", "session_id": "11c7d27d-4519-4dd9-bb1b-574150cdecc9", "seq": 1, "actor_id": null, "assistant_id": null, "role": "user", "parts": [{"type": "text", "text": "你好"}], "idempotency_key": null, "meta": null, "message_time": 1792983098355, "created_at": "2026-10-26T10:51:38.355063531+08:00"}]} |
| gen_ai.memory.operation.latency_ms | int | 否 | 单次记忆调用耗时(ms) | 24 |
Metric监控指标
如果您在第三方智能体代码中手动上报指标数据，您必须首先在代码中注册以下标准的指标名称（Metric Name），并在指标累加上报（.add()）时，在属性字典中强制附带关联的维度（Attributes）。
| 注册的指标名 | 数据类型 | 说明 |
|---|---|---|
| gen_ai.usage.status | Gauge | 用于统计和计算当前智能体的“用户数”。 |
| gen_ai.session.count | Gauge | 用于统计和计算当前智能体的“会话数”。 |
| total.requests | Counter | 智能体累计被调用的总请求次数，用于计算系统的QPS/QPM和响应成功率。 |
| gen_ai.total.requests | Counter | 大语言模型累计被调用的总请求次数，用于单独统计大模型调用情况。 |
| client.operation.duration | Histogram | 智能体应用单次端到端调用的完整响应耗时时延。 |
| gen_ai.client.operation.duration | Histogram | 大语言模型单次调用的网络请求真实耗时时延。 |
| gen_ai.response.time_to_first_token | Histogram | 大模型流式输出时，首次响应首个Token的时延。 |
| gen_ai.usage.input_tokens | Counter | 大语言模型累计消耗的输入Token数量，用于计算算力成本趋势。 |
| gen_ai.usage.output_tokens | Counter | 大语言模型累计生成的输出Token数量。 |
| gen_ai.skill.call.count | Counter | Skill调用次数，在skill_tool调用时累加；同时作为Skill调用成功率的计算基础，需通过gen_ai.call.status维度区分成功与失败。 |
| gen_ai.skill.duration | Histogram | Skill调用耗时分布（单位秒），在skill_complete时记录从激活到完成的时长，平台据此计算Skill调用平均耗时。 |
| gen_ai.skill.error.count | Counter | Skill错误次数，Skill执行结果含错误时累加，用于辅助成功率与稳定性分析。 |
| gen_ai.skill.token.usage | Counter | Skill内容Token消耗。每次LLM调用前记录Skill内容消耗的Token数，用于成本治理与优化。 |
上报上述表9中对应的指标时，必须在代码的Attributes里，上报以下字段：
| 字段名称 | 是否必填 | 说明 |
|---|---|---|
| gen_ai.resource.id | 是 | 您在AgentArts创建接入时平台自动分配的智能体ID。 |
| gen_ai.resource.type | 是 | 资源类型，固定填写"agent"。 |
| domain.id | 是 | 账号ID，用于租户之间的数据安全隔离。 |
| gen_ai.project.id | 是 | 华为云项目ID（Project ID）。 |
| gen_ai.user.id | 是 | IAM用户ID（对应环境变量USER_ID），用于在概览中去重统计活跃用户。 |
| gen_ai.conversation.id | 是 | 用户当前对话的会话ID（Session ID），用于在会话看板中聚合分析。 |
| gen_ai.model.id | 是 | 大模型实际标识（如“deepseek-v4.1-flash”），用于模型排行分析。 |
| gen_ai.call.status | 是 | 请求执行是否成功（True/False），平台以此计算应用及Skill的调用成功率趋势。上报gen_ai.skill.call.count时必须携带此维度，否则平台无法计算Skill调用成功率。 |
| gen_ai.skill.name | 是 | Skill名称，上报gen_ai.skill.*指标时必填，用于按Skill聚合、排行与计算Skill数。 |
| gen_ai.skill.version | 否 | Skill版本号，上报gen_ai.skill.call.count/duration/error.count时如可获取则携带。 |
| gen_ai.system | 否 | 系统/框架来源标识，上报gen_ai.skill.call.count/duration/error.count时如可获取则携带。 |
| gen_ai.request.model | 否 | 调用的模型名称，上报gen_ai.skill.token.usage时建议携带，用于按模型对比Skill Token成本。 |
观测看板与底层探针映射说明
在AgentArts观测看板中，您看到的每一个业务统计指标，其底层的数据解析和过滤依赖于您在探针端上报的底层数据名称。
| 观测看板指标明细 | 指标业务说明 | 探针需上报的底层字段/指标名称 | 数据类型/上报方式 | 必须携带的维度/属性 (Attributes) |
|---|---|---|---|---|
| 用户数 用户数趋势 用户数今日新增 | 统计所选时间区间内使用当前应用的用户总和（去重）、趋势及新增。 | gen_ai.usage.status 注：后端Prom对应gen_ai_usage_status、gen_ai_usage_status_ratio及gen_ai.user.usage | Metric (Gauge) | gen_ai.resource.id gen_ai.resource.type domain.id user.id |
| 在线应用数 | 所选时间区间内所有被调用的应用总数（仅选择全部应用时生效）。 | gen_ai.usage.status 注：后端Prom对应gen_ai_usage_status_ratio | Metric (Gauge) | gen_ai.resource.id gen_ai.resource.type domain.id user.id |
| 会话数 | 所选时间区间内应用的会话总数。 | gen_ai.usage.status或gen_ai.session.count 注：后端Prom对应gen_ai_session_count_ratio | Metric (Gauge) | gen_ai.resource.id gen_ai.resource.type domain.id gen_ai.conversation.id |
| 应用调用次数 服务QPS/QPM趋势 服务响应成功率趋势 | 统计智能体（应用）被调用的总次数、并发率及整体成功率。 | requests_total | Metric (Counter) | gen_ai.resource.id gen_ai.resource.type domain.id gen_ai.conversation.id gen_ai.call.status |
| 应用调用平均耗时趋势 | 所选时间范围内，智能体每次调用的整体平均耗时。 | client.operation.duration 注：后端Prom对应client_operation_duration_seconds | Metric (Histogram) | gen_ai.resource.id gen_ai.resource.type domain.id gen_ai.conversation.id gen_ai.call.status |
| 模型调用次数 模型请求成功率趋势 | 统计大模型被调用的次数及稳定性（成功数量占比）。 | gen_ai.total.requests | Metric (Counter) | gen_ai.resource.id gen_ai.resource.type gen_ai.model.id domain.id user.id gen_ai.call.status |
| 模型调用平均耗时趋势 | 模型调用的平均耗时（Model Span总耗时 / 总数量）。 | gen_ai.client.operation.duration | Metric (Histogram) | gen_ai.resource.id gen_ai.resource.type gen_ai.model.id domain.id user.id gen_ai.call.status |
| 模型首Token耗时 | 模型流式输出时，首次调用消耗的首个Token时延。 | gen_ai.response.time_to_first_token | Metric (Histogram) | gen_ai.resource.id gen_ai.resource.type gen_ai.model.id domain.id |
| 模型数 | 所选时间范围内，智能体关联的模型数量。 | gen_ai.requests_total | Metric (Counter) | gen_ai.resource.id gen_ai.resource.type gen_ai.model.id domain.id |
| Tokens消耗今日总数/总数/趋势 | 大模型调用过程中，输入 (Input) 与输出 (Output) 消耗的Token数量及趋势。 | gen_ai.usage.input_tokens gen_ai.usage.output_tokens | Metric (Counter) | gen_ai.resource.id gen_ai.resource.type gen_ai.model.id domain.id<br>user.id |
| 首次请求平均Token消耗 | 智能体初始化/首次调用时的平均Token消耗。 | application_init_avg_tokens | Metric (Counter) | gen_ai.resource.id gen_ai.resource.type domain.id |
| 模型调用平均Token消耗 | 模型每次调用的平均Token消耗。 | 需同时上报： gen_ai.requests_total gen_ai.usage.input_tokens gen_ai.usage.output_tokens | Metric (Counter) | gen_ai.resource.id gen_ai.resource.type gen_ai.model.id domain.id user.id |
| TOP N消耗/调用量排行 (含单智能体/工作流/多智能体/大模型) | 各类型智能体及大模型的Token消耗、调用次数、耗时排行榜。 | 依赖基础指标：gen_ai.usage.input_tokens gen_ai.usage.output_tokens requests_total gen_ai.client.operation.duration | 综合指标 | 必须确保上述基础指标的维度填写完整，上报基础指标时，attributes字典中必须包含gen_ai.model.id、gen_ai.resource.id等用于排行的分类字段。 |
| Tokens消耗会话/Trace排行 | 基于会话 (Session) 和链路 (Trace) 维度的Token消耗排行。 | session_token_total trace_token_total | Metric (Counter) | 在代码上报时，attributes字典中必须显式包含gen_ai.conversation.id字段。 |
| Trace数/Span数/Span成功率 | 产生的调用链 (Trace) 和节点 (Span) 的数量及成功率。 | 探针需上报完整的Trace Span结构及状态。 注：后端Prom对应trace_count_total、span_count_total、span_success_rate | Trace Span属性 | gen_ai.resource.id gen_ai.resource.type |
| 链路平均耗时 | 完整链路消耗的平均时间。 | gen_ai.client.operation.duration 注：后端Prom对应client_operation_duration_seconds | Trace Span属性 | gen_ai.resource.id |
| Skill数 / Skill调用次数 / Skill调用数排行(Top5) | Skill数：当前应用关联的Skill数量；Skill调用次数：所选时间段内Skill被调用的次数；Top5排行：按调用次数的排行。 | gen_ai.skill.call.count | Metric（Counter） | gen_ai.resource.id, gen_ai.skill.name, domain.id |
| Skill调用成功率 / Skill调用成功率排行(Top5) | Skill调用成功率：成功调用数占总调用数的比例（成功率=成功数/调用数）；Top5排行：按成功率的排行。 | gen_ai.skill.call.count | Metric（Counter） | gen_ai.resource.id, gen_ai.skill.name, domain.id, gen_ai.call.status |
| Skill调用平均耗时 / Skill调用平均耗时排行(Top5) | Skill调用平均耗时：调用总耗时/调用总数；Top5排行：按平均耗时的排行。 | gen_ai.skill.duration | Metric（Histogram） | gen_ai.resource.id, gen_ai.skill.name, domain.id |
| 工具调用次数 / 调用数排行 (Top5) | 工具被调用的总次数；Top5：按调用次数排行 | gen_ai.client.tool_call.total | Metric (Counter) | gen_ai.resource.id, gen_ai.tool.name, tool.type, gen_ai.call.status |
| 工具调用平均耗时 / 耗时排行 (Top5) | 工具调用的平均耗时；Top5：按平均耗时排行 | gen_ai.client.tool_call.duration | Metric (Histogram) | gen_ai.resource.id, tool.name, tool.type, gen_ai.call.status |
| 工具调用成功率 / 成功率排行 (Top5) | 工具调用成功率：成功调用数占总调用数的比例（成功率 = 成功数 / 调用数）；Top5：按成功率排行 | gen_ai.client.tool_call.total | Metric (Counter) | gen_ai.resource.id, tool.name, tool.type, gen_ai.call.status |
