OpenTelemetry字段映射
在AgentArts观测看板中，您看到的每一个图表（如用户数趋势、Token 消耗排行、平均耗时等），底层均依赖于您通过OpenTelemetry (OTel) SDK上报的数据。
为了方便您快速对照，下表将 AgentArts 观测看板上的业务指标与您在代码探针中需要上报的底层字段进行了统一映射。
当您了解了字段的映射关系后，如需在代码中进行具体集成，请直接参考以下操作指南：
- Trace（调用链）上报实操：请阅读Trace数据上报章节。
- Metric（指标）上报实操：请阅读Metric数据上报章节。
Trace调用链属性
您在代码中创建的Span属性（Attributes），需要遵守以下字段名称与规范。
| 字段名称 | 数据类型 | 是否必填 | 说明 |
|---|---|---|---|
| gen_ai.span.type | String | 是 | 区分节点类型。Root Span填写节点填"root"，除了Root Span之外的其余节点填 "model"。 |
| traceloop.workflow.type | String | 否 | 系统协议标识。大模型节点（Model Span）必须携带，固定填写 "LLM"（若为插件，可写 "PLUGIN"），用于在云端列表中进行Model Span过滤筛选。 |
| 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"。 |
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数量。 |
上报上述表2中对应的指标时，必须在代码的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），平台以此计算服务成功率趋势。 |
观测看板与底层探针映射说明
在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 |
