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调用链属性
您在代码中创建的Span属性（Attributes），需要遵守以下字段名称与规范。
| 字段名称 | 数据类型 | 是否必填 | 说明 |
|---|---|---|---|
| gen_ai.span.type | String | 是 | 区分节点类型。Root Span填写节点填"root"，除了Root Span之外的其余节点填 "model"。 |
| traceloop.workflow.type | String | 否 | 系统协议标识。大模型节点（Model Span）必须携带，固定填写 "LLM"（如果是插件或MCP，可填写 "PLUGIN"），用于在云端列表中进行过滤筛选。筛选时Model Span仅展示LLM数据，ALL Span展示包含PLUGIN在内的全部数据。 |
| gen_ai.resource.id | String | 是 | 接入智能体时返回的智能体ID。 |
| gen_ai.resource.type | String | 是 | 资源类型，默认值为 "agent"表示单智能体。（除此之外，多智能体为multiagents，工作流为workflow）。 |
| gen_ai.conversation.id | String | 是 | 唯一的会话ID，长度最大64字节。用于在会话大盘中串联同一用户的多轮交互。 |
| user.id | String | 是 | IAM用户ID（对应环境变量USER_ID）。用于在概览中去重统计活跃用户。 |
| domain.id | String | 是 | 账号ID，用于租户之间的数据安全隔离。 |
| input.value | String | 是 | 当前节点的输入文本。对Root节点记录用户原始提问，对Model节点记录模型输入。缺失会导致控制台该节点输入展示为空。 |
| output.value | String | 是 | 当前节点的输出文本。对Root节点记录最终回答，对Model节点记录模型输出。缺失会导致控制台该节点输出展示为空。 |
| gen_ai.agent.name | String | 是 | 智能体名称，需和平台创建接入时的名称保持一致。 |
| gen_ai.request.model | String | 否 | 调用的模型名称（如 "deepseek-v4-pro"）。仅大模型子节点（Model Span）需要上报。 |
| gen_ai.usage.input_tokens | String/Int | 否 | 本次大模型调用消耗的输入Token数。仅大模型子节点（Model Span）需要上报。 |
| gen_ai.usage.output_tokens | String/Int | 否 | 本次大模型调用生成的输出Token数。仅大模型子节点（Model Span）需要上报。 |
| gen_ai.usage.total_tokens | String/Int | 否 | 本次请求消耗的Token总数。仅大模型子节点（Model Span）需要上报。 |
| gen_ai.server.time_to_first_token | Float/Str | 否 | 流式输出时的首Token耗时。 |
| gen_ai.client.operation.duration | Float/Str | 否 | 单个大模型节点运行真实耗时。 |
| gen_ai.application_name | String | 是 | 统一填写 "default" 固定值。 |
| gen_ai.environment | String | 是 | 统一填写 "default" 固定值。 |
| gen_ai.call.type | String | 是 | 触发类型，统一填写 "API" 固定值。 |
| resource_version | String | 是 | 智能体版本号，默认为 "default"。 |
| gen_ai.operation.name | String | 条件必填 | Skill生命周期阶段标识，仅Skill相关工具执行Span携带。加载填写"load_skill"，释放填写"release_skill"。 |
| gen_ai.skill.name | String | 条件必填 | Skill名称（如"data_analysis"），仅Skill相关工具执行Span携带。 |
| gen_ai.skill.id | String | 条件必填 | Skill唯一标识，建议采用稳定可复现的生成规则（如对skill name做哈希后拼接前缀），仅Skill相关工具执行Span携带。 |
| gen_ai.skill.description | String | 否 | Skill功能描述，仅Skill相关工具执行Span携带。 |
| gen_ai.skill.version | String | 否 | Skill版本号，仅Skill相关工具执行Span携带。 |
上述skill字段中的“条件必填”示仅当Span属于Skill相关工具执行时必填，其他Span无需携带。Skill工具执行Span仍需同时携带gen_ai.resource.id、gen_ai.resource.type、domain.id、user.id等必填字段，否则可能出现数据被隔离过滤或节点跳转异常。
| Event | 触发时机 | 携带属性 | 说明 |
|---|---|---|---|
| skill.loaded | Skill加载完成后 | skill.name、skill.path | 记录Skill已加载及来源路径。 |
| skill.released | Skill释放完成后 | skill.name | 记录Skill生命周期结束。 |
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.server.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数，用于成本治理与优化。 |
上报上述表3中对应的指标时，必须在代码的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-pro"），用于模型排行分析。 |
| 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.server.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 |
