OpenTelemetry字段映射
在AgentArts观测看板中，您看到的每一个图表（如用户数趋势、Token 消耗排行、平均耗时等），底层均依赖于您通过OpenTelemetry (OTel) SDK上报的数据。
为了方便您快速对照，下表将 AgentArts 观测看板上的业务指标与您在代码探针中需要上报的底层字段进行了统一映射。
当您了解了字段的映射关系后，如需在代码中进行具体集成，请直接参考以下操作指南：
- Trace（调用链）上报实操：请阅读Trace数据上报章节。
- Metric（指标）上报实操：请阅读Metric数据上报章节。
| 观测看板指标明细 | 指标业务说明 | 探针需上报的底层字段/指标名称 | 数据类型/上报方式 | 必须携带的维度/属性 (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 |
