用 DQL 分析调试 GenAI/LLM…

当需要排查 Dynatrace 中客户 GenAI/LLM 应用的 LLM 延迟/错误、token 成本与缓存、agent/tool 失败、会话级花费、安全拦截与评估质量时使用。

适用场景

解决思路

1. 用 DQL 从客户 GenAI 应用读取 OpenTelemetry GenAI span（`gen_ai.*`）和 LLM 评估 bizevent，覆盖 golden signals、LLM signals、token/成本分析（含用量归因与 prompt-caching 经济性）、agent signals（含 loop/runaway 检测与 Smartscape 拓扑）、会话级分析、guardrails、评估质量。
2. Golden Signals：用 traffic（请求吞吐量随时间）、errors（`span.status_code == "error"`）、latency（`duration` 字段，Grail duration 值；用 `duration / 1ms` 得到数值毫秒）、saturation（每分钟总 token 吞吐量，input+output）四个经典信号分析 GenAI 应用。
3. Golden Signals DQL：`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`；完整 traffic、latency、saturation 查询见 `references/golden-signals.md`。
4. LLM Signals：分析每个请求由哪个 model 和 provider 服务、调用 operation type（`chat`、`execute_tool`、`invoke_agent`、`create_agent`）以及 token 消耗；用于 provider latency 基准、模型性能比较和 model-provider 组合的 token 分布。
5. LLM Signals DQL：`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`；slowest models、token usage by model 见 `references/llm-signals.md`。
6. Cost and Tokens：token 消耗是主要成本驱动；Dynatrace 在每个 span 上存储 `gen_ai.usage.input_tokens` 和 `gen_ai.usage.output_tokens`，没有存储 cost 字段；估算成本必须用 token 汇总值乘以用户提供的每模型价格。
7. Cost and Tokens DQL：`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 spikes、cost estimation、most expensive prompts、usage attribution、prompt-caching economics 见 `references/cost-and-tokens.md`。
8. Agent Signals：GenAI agent 为每次 tool invocation（`execute_tool`）、agent step（`invoke_agent`）、agent creation（`create_agent`）发出 span；用这些识别最常调用的 tool 和失败的 agent。
9. Agent Signals DQL：`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`；tool usage、failing agents、agent step latency、loop/runaway detection、Smartscape topology 见 `references/agent-signals.md`。
10. Agent 结构性问题：不要扫描 span，改为查询 GenAI Smartscape 实体（`GENAI_AGENT`、`GENAI_MODEL`、`GENAI_PROVIDER`、`GENAI_SERVICE`）来判断存在哪些 agent/model/provider 以及它们如何连接；这是 feature-flag-gated preview。
11. Conversation Analytics：当应用传播 `gen_ai.conversation.id` 时，将 span 上卷到 session 级，分析 cost per conversation、conversation depth、runaway-expensive 或 error-prone sessions；这是 chargeback 和用户感知可靠性的单位。
12. Conversation Analytics DQL：`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`；cost/depth per conversation、session error rate 见 `references/conversation-analytics.md`。
13. Guardrails：从 span 的 `gen_ai.response.finish_reasons` 识别 guardrail：`content_filter` 表示安全过滤器阻止或脱敏输出，`length` 表示响应因 token 限制被截断；同时使用评估 bizevent 中的主动安全评估器（`prompt-injection`、`pii-leakage`、`toxicity`、`bias`）。
14. Guardrails DQL：`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`；blocked（safety-filtered）、truncated（length）、finish-reason breakdown 见 `references/guardrails.md`。
15. Evaluation Quality：评估结果存为 bizevent（不是 span），条件 `event.type == "gen_ai.evaluation.result"`；每个 evaluator 对每个响应发出一个 bizevent，包含 score、pass/fail label、explanation、准确 Q&A pair；用它监控质量维度并展示失败响应与 LLM judge 理由。
16. Evaluation Quality DQL：`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`；quality scores、failed evaluations、fail rates 见 `references/evaluations.md`。
17. Evaluation trace 关联：每个评估 bizevent 带有产生被评估响应的 run 的 `trace.id`，从质量失败 pivot 到造成该失败的 span。
18. Empty-State Check：任何 signal query 返回 0 行时，不要报告 no data found；先确认应用是否发送 GenAI telemetry。
19. Empty-State spans presence check：`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()`。
20. Empty-State bizevents presence check：`fetch bizevents, from: now()-24h | filter event.type == "gen_ai.evaluation.result" | summarize evals = count()`。
21. Empty-State 解读：若 `has_genai` 为 0，报告应用似乎尚未为 AI Observability 插桩，而不是 no data found；若 `has_genai` 非 0 但某个 family（`has_tokens`、`has_agents`、`has_tools`、`has_conversation`、`has_finish_reason`、`has_cached_tokens`、`evals`）为 0，则只有该 signal type 缺失；例如 `has_conversation == 0` 表示应用未传播 conversation id，无法做 session-level analytics；`has_cached_tokens == 0` 表示未上报 prompt-caching telemetry。可选 family 可能因 provider/SDK 使用不同属性名，报告缺失前先验证。
22. Act First, Refine Later：用户请求分析时，立即用合理默认值继续，不要询问可合理假设的参数值。
23. 默认值：未指定 timeframe 时用 last 24 h（`from: now()-24h`），覆盖完整运营日；未指定 model scope 时用 all models（无 model filter），先展示全貌再由用户缩小；未指定 provider scope 时用 all providers；未指定 token threshold 时不用阈值，展示全部让数据暴露异常值。
24. 成本价格例外：per-model prices 是唯一不能默认的输入（数据中没有 cost 字段）；估算 USD 前先询问用户，绝不凭记忆使用价格；见 `references/cost-and-tokens.md`。
25. Empty-State Rule：任何 signal query 返回 0 行时，在响应前运行上面两个 presence checks，绝不回复 no data found；若 `has_genai` 为 0，报告尚未插桩；若只有特定 family 为 0，说明缺失的是哪种 signal type。
26. Scope Boundary：本技能只覆盖客户 GenAI 应用的 AI Observability signals；产品文档和配置 how-to（例如如何配置 Dynatrace OTLP endpoint）转到 `ask-dynatrace-docs`，本技能不包含产品配置 how-tos。
27. 路由：'Understand AI Observability signals' → All signal categories overview → 本 SKILL.md。
28. 路由：'Analyze LLM latency and errors'、'LLM errors'、'error rate by model' → Golden Signals → references/golden-signals.md。
29. 路由：'Which models are slowest right now?'、'compare latency across providers' → LLM Signals → references/llm-signals.md。
30. 路由：'Show token usage by model'、'token usage spikes' → Cost and Tokens → references/cost-and-tokens.md。
31. 路由：'Break down cost by model and provider'、'which prompts are most expensive?' → Cost and Tokens → references/cost-and-tokens.md。
32. 路由：'Trace a failing agent run'、'show failed tool calls' → Agent Signals → references/agent-signals.md。
33. 路由：'Break down agent steps by latency' → Agent Signals → references/agent-signals.md。
34. 路由：'Map agent topology'、'which models does this agent use?'、'list GenAI agents/models/providers' → Agent Signals (Smartscape) → references/agent-signals.md。
35. 路由：'Is an agent stuck in a loop?'、'find runaway agents'、'what caused the token spike?' → Agent Signals (loops) → references/agent-signals.md。
36. 路由：'Cost per conversation'、'most expensive sessions'、'how deep do conversations run?' → Conversation Analytics → references/conversation-analytics.md。
37. 路由：'Stitch together an agent trajectory'、'filter by session id'、'connect traces across a session' → Conversation Analytics → references/conversation-analytics.md。
38. 路由：'How often are responses blocked/filtered?'、'are responses being truncated?'、'finish reasons' → Guardrails → references/guardrails.md。
39. 路由：'Cost by application/user/tenant'、'who is driving token spend?' → Cost and Tokens (attribution) → references/cost-and-tokens.md。
40. 路由：'Do I have prompt caching?'、'cache hit rate'、'caching savings' → Cost and Tokens (caching) → references/cost-and-tokens.md。
41. 路由：'Summarize evaluation quality scores'、'show low-scoring responses'、'show failed evaluations' → Evaluation Quality → references/evaluations.md。
42. 路由：'What signals am I missing?'、'why is there no data?' → Empty-State Check → 本 SKILL.md。
43. Cost Investigation 工作流：1) 运行 token usage by model and provider（cost-and-tokens.md → 'Token usage by model and provider'）；2) 按 total_tokens 找出 top model-provider 组合；3) 对 top offenders 运行 token usage spikes 检查异常时间窗口；4) 用 'Most expensive prompts and models' 中的 cost-estimation template 估算 USD spend，先询问用户 per-model prices（见 Agent Instructions 的 'Exception — cost prices'）；5) 检查 prompt-size outliers，高 input_tokens/output_tokens ratio 表示大 context windows；6) 将花费归因到 consumer（cost-and-tokens.md → 'Usage attribution'），并检查 prompt caching 是否启用且有效（cost-and-tokens.md → 'Prompt caching economics'）。
44. Token-Spike / Runaway Investigation 工作流：1) 运行 token usage spikes（cost-and-tokens.md → 'Token usage spikes'）找到异常时间窗口；2) 在该窗口内运行 repeated-tool-calls 与 runaway-turn 查询（agent-signals.md → 'Agent loops and runaway detection'）；3) 对标记的 trace.id 打开 trace 查看 agent 在什么上循环；4) 如果存在 conversation ids，按 gen_ai.conversation.id 重新运行 loop 查询以捕获跨 turn loops（conversation-analytics.md）。
45. Failing Agent Run 工作流：1) 运行 failing agent activity 查询（agent-signals.md → 'Failing agent activity'）；2) 按 errors desc 排序找出最易出错的 agent；3) 从失败 span 取 trace.id 并在 Dynatrace distributed-tracing view 打开；4) 检查 agent steps by latency（agent-signals.md）看哪个 operation type 最慢。
46. Guardrail & Safety Review 工作流：1) 运行 guardrails presence check（guardrails.md）确认记录 finish reasons；2) 运行 finish-reason breakdown，然后运行 blocked（content_filter）和 truncated（length）查询；3) 将 safety-filter spikes 与 prompt-injection evaluator 关联，将 truncation 与 answer-completeness failures 关联（evaluations.md）；4) 对特定 block 或 failure，取 trace.id 并 pivot 到 originating spans（evaluations.md → 'Correlating evaluations to traces'）。
47. Evaluation Review 工作流：1) 运行 evaluation quality scores（evaluations.md → 'Evaluation quality scores'）按 avg_score asc 对 evaluator 排名；2) 关注最低分 evaluator；3) 运行 failed evaluations（evaluations.md → 'Failed evaluations'）展示准确 Q&A pairs 和 LLM judge explanations；4) 用 'Fail rate by evaluator' 查询查看每个 evaluator 失败多少响应及占总评估比例；5) 为特定 failure 根因分析，取其 trace.id 并 pivot 到 originating spans（evaluations.md → 'Correlating evaluations to traces'）。
48. references/golden-signals.md — traffic、errors、latency、saturation。
49. references/llm-signals.md — slowest models、provider latency、token usage by model。
50. references/cost-and-tokens.md — token usage、spikes、cost-estimation template、usage attribution、prompt-caching economics。
51. references/agent-signals.md — tool usage、failing agents、step latency、loop/runaway detection、Smartscape agent topology（preview）。
52. references/conversation-analytics.md — session-level cost、depth、error rate（`gen_ai.conversation.id`）。
53. references/guardrails.md — blocked（safety-filtered）和 truncated（length）responses via finish reasons。
54. references/evaluations.md — quality scores、failed evals、fail-rate、trace correlation（bizevents）。
55. 建议 follow-up 问题时，使用 canonical ready-to-ask phrasings，每个能力一个；保持 single-clause，避免字面短语 'content filter'（用 'blocked or safety-filtered' 代替）；过长、multi-clause 问题可能被拒绝。
56. 示例问题（Traffic, errors & latency）：What is my LLM error rate and p95 latency by model in the last 24 hours?
57. 示例问题（Token usage & cost）：Break down token usage and cost by model and provider in the last 24 hours.
58. 示例问题（Agent & tool activity）：Show me failing agent tool calls in the last 24 hours.
59. 示例问题（Conversation analytics）：What are my top 10 most expensive conversations by total token usage in the last 24 hours?
60. 示例问题（Guardrails）：How many responses were blocked or truncated in the last 7 days, and which model was affected most?
61. 示例问题（Evaluation quality）：Show me failed evaluations from the last 24 hours with the judge's explanation and the question-answer pair.

适用边界 · 注意事项

• 不适用于 Davis CoPilot/MCP telemetry（dt-platform）、通用 service metrics（dt-obs-services）、logs（dt-obs-logs）、非 GenAI distributed tracing（dt-obs-tracing）。
• 不适用于产品文档与配置 how-to 问题（例如如何配置 Dynatrace OTLP endpoint），这些应交给 `ask-dynatrace-docs`。
• 不适用于未向 Dynatrace 发送 GenAI/OTel telemetry（`gen_ai.*`）或评估 bizevent 的应用；此时只能报告尚未为 AI Observability 插桩。