dt-obs-genai

AI 可观测性（GenAI）技能

使用 DQL 分析客户 GenAI 应用的 AI 可观测性信号——黄金信号、LLM 信号、Token 和成本分析（包括使用量归因和提示缓存的经济效益）、Agent 信号（包括循环/失控检测和 Smartscape 拓扑）、对话/会话级分析、护栏和评估质量。

适用场景

当你需要解答客户 GenAI 应用的可观测性问题时使用此技能——包括读取 OpenTelemetry GenAI span（gen_ai.*）或 LLM 评估 bizevents 的任何问题。示例触发词：

• “LLM 延迟”、“按模型统计错误率”
• “按模型统计 Token 使用量”、“Token 吞吐量 / TPM”、“我是否触及速率限制”、“提供商限流或 429 错误”
• “按模型和提供商统计成本”、“谁在消耗 Token 预算”、“我是否启用了提示缓存”
• “每段对话的成本”、“成本最高的会话”
• “Agent 工具调用失败”、“查找失控的 Agent”
• “响应被截断或拦截”、“完成原因”
• “评估失败”、“质量评分”

不适用场景

Davis CoPilot/MCP 遥测（dt-platform）、通用服务指标（dt-obs-services）、日志（dt-obs-logs）或非 GenAI 分布式追踪（dt-obs-tracing）。

示例问题

建议后续问题时（例如“每个主题给我一个示例问题”），请使用以下规范且可直接提问的表述——每项能力一个问题。建议的问题应为单分句，并避免使用字面短语“内容过滤”（改用“被拦截或经过安全过滤”）；过长的多分句问题可能会被拒绝。

• 流量、错误和延迟： 过去 24 小时内，按模型统计的 LLM 错误率和 p95 延迟是多少？
• Token 使用量和成本： 列出过去 24 小时内按模型和提供商细分的 Token 使用量与成本。
• Agent 和工具活动： 显示过去 24 小时内失败的 Agent 工具调用。
• 对话分析： 过去 24 小时内，按 Token 总使用量计算，成本最高的前 10 段对话是什么？
• 护栏： 过去 7 天内有多少响应被拦截或截断？受影响最多的是哪个模型？
• 评估质量： 显示过去 24 小时内失败的评估，并附上评审者的解释和问答对。

---

核心能力

黄金信号

四种经典可观测性信号——流量、错误、延迟和饱和度——同样适用于 GenAI 应用。流量是随时间变化的请求吞吐量；错误是 span.status_code == "error" 的 span；延迟是 duration 字段（Grail duration 值——除以 1ms 字面量，即 duration / 1ms，得到以毫秒为单位的数值）；饱和度则以每分钟的 Token 总吞吐量（输入和输出 Token 合计）作为近似指标。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.request.model)
| summarize total = count(), errors = countIf(span.status_code == "error"), by: {gen_ai.request.model}
| fieldsAdd error_rate_pct = if(total > 0, errors * 100.0 / total, else: 0.0)
| sort error_rate_pct desc

→ 完整的流量、延迟和饱和度查询： 参见 references/golden-signals.md

LLM 信号

LLM 信号说明每个请求由哪个模型和提供商处理、调用了哪种操作类型（chat、execute_tool、invoke_agent、create_agent），以及 Token 的消耗情况。使用这些信号可评估提供商的延迟表现、比较模型性能，并了解不同模型与提供商组合的 Token 分布。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.request.model)
| summarize p95_ms = percentile(duration, 95) / 1ms, requests = count(), by: {gen_ai.provider.name}
| sort p95_ms desc

→ 最慢的模型、按模型统计 Token 使用量： 参见 references/llm-signals.md

成本和 Token

Token 消耗是成本的主要驱动因素。Dynatrace 会在每个 span 上存储 gen_ai.usage.input_tokens 和 gen_ai.usage.output_tokens——不会存储成本字段；估算成本必须将 Token 总数乘以你提供的每个模型的价格。使用这些查询可找出支出最高的模型与提供商组合，并检测 Token 消耗激增。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.usage.input_tokens) or isNotNull(gen_ai.usage.output_tokens)
| summarize input_tokens = sum(gen_ai.usage.input_tokens), output_tokens = sum(gen_ai.usage.output_tokens), total_tokens = sum(gen_ai.usage.input_tokens) + sum(gen_ai.usage.output_tokens), by: {gen_ai.provider.name, gen_ai.request.model}
| sort total_tokens desc

→ Token 激增、成本估算、成本最高的提示词、使用量归因、提示缓存的经济效益： 参见 references/cost-and-tokens.md

Agent 信号

GenAI Agent 会为每次工具调用（execute_tool）、Agent 步骤（invoke_agent）和 Agent 创建（create_agent）生成 span。使用 Agent 信号识别调用频率最高的工具以及失败的 Agent。对于结构性问题——有哪些 Agent、模型和提供方，以及它们如何连接——请查询 GenAI Smartscape 实体（GENAI_AGENT、GENAI_MODEL、GENAI_PROVIDER、GENAI_SERVICE），而不要扫描 span；此功能为受功能标志控制的预览版。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.agent.name)
| summarize total = count(), errors = countIf(span.status_code == "error"), by: {gen_ai.agent.name}
| fieldsAdd error_rate_pct = if(total > 0, errors * 100.0 / total, else: 0.0)
| sort errors desc

→ **工具使用情况、失败的 Agent、Agent 步骤延迟、循环／失控检测、Smartscape 拓扑：**参见 references/agent-signals.md

对话分析

每个 span 和每条 trace 的信号衡量一次请求或一轮对话。当应用传播 gen_ai.conversation.id 时，可以将 span 汇总到会话级别——每次对话的成本、对话的深度，以及哪些会话成本失控或容易出错。这是进行成本分摊和衡量用户感知可靠性时重要的单位。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.conversation.id)
| summarize turns = countDistinct(trace.id), total_tokens = sum(gen_ai.usage.input_tokens) + sum(gen_ai.usage.output_tokens), errors = countIf(span.status_code == "error"), by: {gen_ai.conversation.id}
| sort total_tokens desc

→ **每次对话的成本／深度、会话错误率：**参见 references/conversation-analytics.md

防护措施

防护措施会作为 span 上的 gen_ai.response.finish_reasons 显示——content_filter 表示安全过滤器阻止或删去了输出，length 表示响应因达到 token 限制而被截断；也会作为评估 bizevent 中主动安全评估器（prompt-injection、pii-leakage、toxicity、bias）显示。利用这些信号量化被阻止和被截断的响应，并将其与 LLM 评判器的安全判定关联起来。

fetch spans, from: now()-24h
| filter isNotNull(gen_ai.response.finish_reasons)
| fieldsAdd finish_reason = gen_ai.response.finish_reasons
| expand finish_reason
| summarize calls = count(), by: {finish_reason, gen_ai.request.model}
| sort calls desc

→ **被阻止（经安全过滤）、被截断（长度）、结束原因明细：**参见 references/guardrails.md

评估质量

评估结果会以 bizevent（而非 span）的形式记录，且满足 event.type == "gen_ai.evaluation.result"。每个评估器会针对每条响应生成一个 bizevent，其中包含分数、通过／失败标签、说明以及确切的问答对。使用评估查询监控质量维度，并结合 LLM 评判器的推理过程找出失败的响应。每个 bizevent 还包含生成受评估响应的运行所对应的 trace.id，因此可以从质量问题追溯到导致问题的 span。

fetch bizevents, from: now()-24h
| filter event.type == "gen_ai.evaluation.result"
| filter gen_ai.evaluation.score.label == "fail"
| fields timestamp, gen_ai.evaluation.name, gen_ai.evaluation.score.value, gen_ai.evaluation.explanation, gen_ai.evaluation.input.question, gen_ai.evaluation.input.answer
| sort timestamp desc

→ **质量分数、失败的评估、失败率：**参见 references/evaluations.md

空状态检查

当任何信号查询未返回行时，不要报告“未找到数据”——应先确认应用是否发送了 GenAI 遥测数据。以下两项存在性检查会显示当前有哪些信号系列：

fetch spans, from: now()-24h
| summarize 
    has_genai = countIf(isNotNull(gen_ai.request.model)), 
    has_tokens = countIf(isNotNull(gen_ai.usage.input_tokens) or isNotNull(gen_ai.usage.output_tokens)), 
    has_agents = countIf(isNotNull(gen_ai.agent.name)), 
    has_tools = countIf(gen_ai.operation.name == "execute_tool"), 
    has_conversation = countIf(isNotNull(gen_ai.conversation.id)), 
    has_finish_reason = countIf(isNotNull(gen_ai.response.finish_reasons)), 
    has_cached_tokens = countIf(isNotNull(gen_ai.usage.cache_read.input_tokens) or isNotNull(gen_ai.usage.cache_creation.input_tokens)),
    total = count()
    

fetch bizevents, from: now()-24h
| filter event.type == "gen_ai.evaluation.result"
| summarize evals = count()

如果 has_genai 为零，应报告该应用似乎尚未接入 AI 可观测性，而不是“未找到数据”。如果 has_genai 不为零，但某个特定系列（has_tokens、has_agents、has_tools、has_conversation、has_finish_reason、has_cached_tokens、evals）为零，则仅表示缺少该信号类型——例如，has_conversation == 0 表示由于应用未传播 conversation id，会话级分析不可用；has_cached_tokens == 0 表示未报告提示缓存遥测数据。这些可选系列可能因提供方／SDK 不同而使用不同的属性名称；在报告其缺失之前，请先核实。

---

Agent 说明

先行动，后优化

用户要求进行分析时，使用合理的默认值立即开始。不要询问可以合理假设的参数值。

未指定时的默认值：

参数	默认值	原因
时间范围	最近 24 h（from: now()-24h）	覆盖完整的运行日，范围又不会过窄
模型范围	所有模型（不筛选模型）	展示全貌；用户查看结果后可进一步缩小范围
提供商范围	所有提供商	理由与模型范围相同
Token 阈值	无	全部展示，让数据揭示异常值

例外 — 成本价格。 每个模型的价格是唯一无法设为默认值的输入（数据中没有成本字段）。在估算 USD 之前，先向用户询问价格；切勿使用记忆中的价格。请参阅 cost-and-tokens.md。

空结果规则

当任何信号查询未返回行时，先运行上方 空结果检查功能中的两项存在性检查，再作出答复——切勿回复“未找到数据”。 如果 has_genai 为零，则报告该应用似乎尚未接入 AI Observability；如果只有某个特定系列的值为零，则说明缺少哪种信号类型。

范围边界

此技能仅涵盖客户 GenAI 应用的 AI Observability 信号。 产品文档和配置操作说明类问题（例如“如何配置 Dynatrace OTLP 端点？”）应交由 ask-dynatrace-docs 处理——此技能不包含产品配置操作说明。

理解用户意图

将用户请求和提示词起始语句映射到相应能力：

用户请求 / 提示词起始语句	能力	参考文件
“了解 AI 可观测性信号”	所有信号类别概览	此 SKILL.md
“分析 LLM 延迟和错误”、“LLM 错误”、“按模型查看错误率”	黄金信号	golden-signals.md
“目前哪些模型最慢？”、“比较不同提供商的延迟”	LLM 信号	llm-signals.md
“按模型查看令牌用量”、“令牌用量激增”	成本和令牌	cost-and-tokens.md
“按模型和提供商细分成本”、“哪些提示词最贵？”	成本和令牌	cost-and-tokens.md
“追踪一次失败的 Agent 运行”、“显示失败的工具调用”	Agent 信号	agent-signals.md
“按延迟细分 Agent 步骤”	Agent 信号	agent-signals.md
“绘制 Agent 拓扑”、“此 Agent 使用哪些模型？”、“列出 GenAI Agent/模型/提供商”	Agent 信号（Smartscape）	agent-signals.md
“Agent 是否陷入循环？”、“查找失控的 Agent”、“是什么导致令牌用量激增？”	Agent 信号（循环）	agent-signals.md
“每次对话的成本”、“成本最高的会话”、“对话会进行多深？”	对话分析	conversation-analytics.md
“串联 Agent 轨迹”、“按会话 ID 筛选”、“关联跨会话的追踪”	对话分析	conversation-analytics.md
“响应被拦截/过滤的频率有多高？”、“响应是否被截断？”、“结束原因”	安全护栏	guardrails.md
“按应用程序/用户/租户查看成本”、“谁在推动令牌支出？”	成本和令牌（归因）	cost-and-tokens.md
“是否启用了提示词缓存？”、“缓存命中率”、“缓存节省额”	成本和令牌（缓存）	cost-and-tokens.md
“汇总评估质量分数”、“显示低分响应”、“显示失败的评估”	评估质量	evaluations.md
“我缺少哪些信号？”、“为什么没有数据？”	空状态检查	此 SKILL.md

---

常见工作流

工作流：成本调查

1. Run token usage by model and provider (cost-and-tokens.md → "Token usage by model and provider")
2. Identify the top model-provider combinations by total_tokens
3. For the top offenders, run token usage spikes to check for abnormal time windows
4. Use the cost-estimation template in "Most expensive prompts and models" to estimate USD spend — ask the user for per-model prices first (see "Exception — cost prices" under Agent Instructions)
5. Check for prompt-size outliers: high input_tokens / output_tokens ratio indicates large context windows
6. Attribute spend to a consumer (cost-and-tokens.md → "Usage attribution") and check whether prompt caching is enabled and effective (cost-and-tokens.md → "Prompt caching economics")

工作流：令牌用量激增 / 失控调查

1. Run token usage spikes (cost-and-tokens.md → "Token usage spikes") to find the abnormal time window
2. Within that window, run repeated-tool-calls and runaway-turn queries (agent-signals.md → "Agent loops and runaway detection")
3. For a flagged trace.id, open the trace to see what the agent looped on
4. If conversation ids are present, re-run the loop query grouped by gen_ai.conversation.id to catch cross-turn loops (conversation-analytics.md)

工作流：失败的 Agent 运行

1. Run failing agent activity query (agent-signals.md → "Failing agent activity")
2. Sort by errors desc to find the most error-prone agent
3. Take the trace.id from a failing span and open in Dynatrace distributed-tracing view
4. Check agent steps by latency (agent-signals.md) to see which operation type is slowest

工作流：安全护栏与安全审查

1. Run the guardrails presence check (guardrails.md) to confirm finish reasons are recorded
2. Run the finish-reason breakdown, then the blocked (content_filter) and truncated (length) queries
3. Correlate safety-filter spikes with the prompt-injection evaluator and truncation with answer-completeness failures (evaluations.md)
4. For a specific block or failure, take the trace.id and pivot to the originating spans (evaluations.md → "Correlating evaluations to traces")

工作流：评估审查

1. Run evaluation quality scores (evaluations.md → "Evaluation quality scores") to rank evaluators by avg_score asc
2. Focus on the lowest-scoring evaluator
3. Run failed evaluations (evaluations.md → "Failed evaluations") to surface the exact Q&A pairs and LLM judge explanations
4. Use the "Fail rate by evaluator" query to see how many responses fail each evaluator and the share of total evaluations
5. To root-cause a specific failure, take its trace.id and pivot to the originating spans (evaluations.md → "Correlating evaluations to traces")

---

参考资料

• references/golden-signals.md — 流量、错误、延迟、饱和度
• references/llm-signals.md — 最慢的模型、提供商延迟、按模型查看令牌用量
• references/cost-and-tokens.md — 令牌用量、激增、成本估算模板、用量归因、提示词缓存经济效益
• references/agent-signals.md — 工具用量、失败的 Agent、步骤延迟、循环/失控检测、Smartscape Agent 拓扑（预览）
• references/conversation-analytics.md — 会话级成本、深度和错误率（gen_ai.conversation.id）
• references/guardrails.md — 通过结束原因识别被拦截（安全过滤）和被截断（长度限制）的响应
• references/evaluations.md — 质量分数、失败的评估、失败率、追踪关联（bizevents）