排查 Dynatrace 分布式 trace 的慢请求…

在 Dynatrace Grail 中使用 DQL 对 spans 做分布式 trace 分析，适用于 span 级细节、失败、性能瓶颈、trace 关联和请求流分析。

适用场景

解决思路

1. 用 `fetch spans | limit 1` 获取并探索 span 数据结构。
2. 用 `fetch spans | summarize count(), by: { span.kind, code.namespace, code.function }` 按 span 种类、代码命名空间和函数汇总计数，探索 span 类型。
3. 用 `span.kind: server` 表示进入服务的调用，`span.kind: client` 表示服务发出的调用，`span.kind: consumer` 表示进入服务的消息消费调用，`span.kind: producer` 表示服务发出的消息生产调用，`span.kind: internal` 表示服务内部操作。
4. 用 `request.is_root_span == true` 识别请求根 span（进入服务的调用），用于端到端请求性能分析。
5. 使用关键 trace 属性：`trace.id`、`span.id`、`span.parent_id`、`request.is_root_span`、`request.is_failed`、`duration`、`span.timing.cpu`、`span.timing.cpu_self`、`dt.smartscape.service`、`dt.service.name`、`endpoint.name`。
6. 用 `fetch spans | summarize spans=count(), by: { dt.smartscape.service, dt.service.name }` 查看服务上下文；用 `getNodeName(dt.smartscape.service)` 获取可读服务名；用 `getNodeField(dt.smartscape.service, "attribute_name")` 访问节点属性。
7. 处理采样与推断：一个 span 可能代表多个真实操作，原因包括聚合 `aggregation.count`、ATM 头部采样、ALR 服务端采样、查询时 `samplingRatio` 读取采样。
8. 在计数真实操作数时始终使用 multiplicity 推断：计算 `sampling.probability = (power(2, 56) - coalesce(sampling.threshold, 0)) * power(2, -56)`，`sampling.multiplicity = 1 / sampling.probability`，`multiplicity = coalesce(sampling.multiplicity, 1) * coalesce(aggregation.count, 1) * dt.system.sampling_ratio`，然后 `summarize operation_count = sum(multiplicity)`。
9. 用 `fetch spans | filter request.is_root_span == true | fields trace.id, span.id, start_time, response_time = duration, endpoint.name | limit 100` 列出请求根 span。
10. 用 `fetch spans | filter request.is_root_span == true | summarize total_requests = count(), failed_requests = countIf(request.is_failed == true), avg_duration = avg(duration), p95_duration = percentile(duration, 95), by: {dt.service.name} | fieldsAdd error_rate = (failed_requests * 100.0) / total_requests | sort error_rate desc` 分析服务性能摘要和错误率。
11. 用 `fetch spans | filter trace.id == toUid("abc123def456") | fields span.name, duration, dt.service.name` 通过 trace ID 查找特定 trace 的所有 span。
12. 用 `fetch spans | filter request.is_root_span == true | summarize { requests=count(), avg_duration=avg(duration), p95=percentile(duration, 95), p99=percentile(duration, 99) }, by: { endpoint.name } | sort p99 desc` 按 endpoint 计算响应时间百分位；最佳实践是使用 p95/p99 而非平均值。
13. 用 `fetch spans, from:now() - 2h | filter request.is_root_span == true | filter duration > 5s | fields trace.id, span.name, dt.service.name, duration | sort duration desc | limit 50` 检测超过阈值的慢 trace。
14. 用 `fetch spans, from:now() - 24h | filter http.route == "/api/v1/storage/findByISBN" | summarize { spans=count(), trace=takeAny(record(start_time, trace.id)) }, by: { bin(duration, 10ms) } | fields `bin(duration, 10ms)`, spans, trace.id=trace[trace.id], start_time=trace[start_time]` 做 duration 分桶并带 exemplar。
15. 用 `fetch spans, from:now() - 24h | filter request.is_root_span == true | makeTimeseries { requests=count(), avg_duration=avg(duration), p95=percentile(duration, 95), p99=percentile(duration, 99) }, by: { endpoint.name }` 生成性能时间序列。
16. 用 `fetch spans | filter request.is_root_span == true | summarize total = count(), failed = countIf(request.is_failed == true), by: { dt.service.name } | fieldsAdd failure_rate = (failed * 100.0) / total | sort failure_rate desc` 按服务汇总失败请求。
17. 用 `fetch spans | filter request.is_failed == true and isNotNull(dt.failure_detection.results) | expand dt.failure_detection.results | summarize count(), by: { dt.failure_detection.results[reason] }` 按失败检测原因分析；失败原因包括 `http_code`、`grpc_code`、`exception`、`span_status`、`custom_rule`。
18. 用 `fetch spans | filter request.is_failed == true | filter iAny(dt.failure_detection.results[][reason] == "http_code") | summarize count(), by: { http.response.status_code, endpoint.name } | sort `count()` desc` 按 HTTP 状态码查找失败。
19. 用 `fetch spans | filter request.is_root_span == true and request.is_failed == true | fields start_time, trace.id, endpoint.name, http.response.status_code, duration | sort start_time desc | limit 100` 列出最近失败请求及详情。
20. 用 `fetch spans, from:now() - 1h | filter isNotNull(server.address) | fieldsAdd remote_side = server.address | summarize call_count = count(), avg_duration = avg(duration), by: {dt.service.name, remote_side} | sort call_count desc` 分析服务到服务通信模式。
21. 用 `fetch spans | filter span.kind == "client" and isNotNull(http.request.method) | summarize calls = count(), avg_latency = avg(duration), p99_latency = percentile(duration, 99), by: { dt.service.name, server.address, server.port } | sort calls desc` 识别出站 HTTP 外部 API 依赖。
22. 用 `fetch spans, from:now() - 30m | summarize { spans = count(), client_spans = countIf(span.kind == "client"), endpoints = toString(arrayRemoveNulls(collectDistinct(endpoint.name))), trace_root = takeMin(record(root_detection_helper = coalesce(if(request.is_root_span, 1), if(isNull(span.parent_id), 2), 3), start_time, endpoint.name, duration)) }, by: { trace.id } | fieldsFlatten trace_root | fieldsRemove trace_root.root_detection_helper, trace_root | fields start_time = trace_root.start_time, endpoint = trace_root.endpoint.name, response_time = trace_root.duration, spans, client_spans, endpoints, trace.id | sort start_time | limit 100` 聚合整个 trace 分析完整请求流；根检测优先级：1) `request.is_root_span == true`，2) 无 parent，3) 其他。
23. 用 `fetch spans, from:now() - 1h | summarize { services = collectDistinct(dt.service.name), trace_root = takeMin(record(root_detection_helper = coalesce(if(request.is_root_span, 1), 2), endpoint.name)) }, by: { trace.id } | fieldsAdd service_count = arraySize(services) | filter service_count > 1 | fields endpoint = trace_root[endpoint.name], service_count, services = toString(services), trace.id | sort service_count desc | limit 50` 查找跨多个服务的 trace。
24. 用 `fetch spans | filter request.is_root_span == true | filter isNotNull(request_attribute.PaidAmount) | makeTimeseries sum(request_attribute.PaidAmount)` 访问 OneAgent 在请求根 span 上捕获的自定义请求属性；字段模式 `request_attribute.<name>`、`captured_attribute.<name>`（始终为数组）。
25. 按 span 类型检测和查询 HTTP server（入站）：`span.kind == "server" and isNotNull(http.request.method)`，关键字段 `http.route`、`http.request.method`、`http.response.status_code`。
26. 按 span 类型检测和查询 HTTP client（出站）：`span.kind == "client" and isNotNull(http.request.method)`，关键字段 `server.address`、`server.port`。
27. 按 span 类型检测和查询数据库：`span.kind == "client" and isNotNull(db.system)`，关键字段 `db.system`、`db.namespace`、`db.statement`。
28. 按 span 类型检测和查询消息：`isNotNull(messaging.system)`，关键字段 `messaging.system`、`messaging.destination.name`、`messaging.operation.type`。
29. 按 span 类型检测和查询 RPC/gRPC：`isNotNull(rpc.system)`，关键字段 `rpc.system`、`rpc.service`、`rpc.method`、`rpc.grpc.status_code`。
30. 按 span 类型检测和查询 Serverless/FaaS：`isNotNull(faas.name) and span.kind == "server"`，关键字段 `faas.name`、`faas.trigger.type`、`cloud.provider`。
31. 数据库 span 可能被聚合（一个 span = 多次调用），计数准确操作数时始终使用 `aggregation.count` 推断。
32. 用 `fetch spans | filter iAny(span.events[][span_event.name] == "exception") | expand span.events | fieldsFlatten span.events, fields: { exception.type } | summarize { count(), trace=takeAny(record(start_time, trace.id)) }, by: { exception.type } | fields exception.type, `count()`, trace.id=trace[trace.id], start_time=trace[start_time]` 做异常分析；用 `iAny()` 检查 span event 数组中的条件。
33. 参考 `references/logs-correlation.md` 进行日志和 trace 关联，按日志内容过滤 trace。
34. 参考 `references/networking-analysis.md` 分析客户端 IP、DNS 解析、子网和通信映射。
35. 最佳实践-过滤：先应用 `request.is_root_span == true` 和 endpoint 过滤。
36. 最佳实践-采样：使用 `samplingRatio`（例如 `100` = 读取 1%）提升性能。
37. 最佳实践-百分位：性能分析使用 p95/p99 而非平均值。
38. 最佳实践-根 span：端到端分析使用 `request.is_root_span == true`。
39. 最佳实践-trace 分组：按 `trace.id` 分组获得完整 trace 指标。
40. 最佳实践-请求分组：按 `request.id` 分组获得仅 OneAgent 的请求指标。
41. 最佳实践-推断：计数时始终应用 multiplicity 进行准确操作数推断。
42. 最佳实践-exemplar：使用 `takeAny(record(start_time, trace.id))` 作为 exemplar 支持 UI 下钻。
43. 故障排查-duration：`duration` 单位是纳秒而非毫秒，需除以 `1000000` 或与 `5s`（DQL duration 字面量）比较。
44. 故障排查-span 计数：span 计数与预期请求量不匹配时，考虑采样或聚合未计入，使用 multiplicity 推断。
45. 故障排查-getNodeName：`getNodeName(dt.smartscape.service)` 返回 null 时，验证 OneAgent 是否监控该服务；实体解析可能有短延迟。
46. 故障排查-request.is_root_span：过滤无结果且查询 OpenTelemetry-only trace 时，用 `isNull(span.parent_id)` 作为根 span 检测回退。
47. 故障排查-trace.id：`trace.id` 过滤无结果时，用 `toUid("abc123...")` 将字符串 trace ID 转为 UID 格式。
48. 故障排查-数据库 span：数据库 span 计数偏低时，数据库 span 被聚合，始终使用 `aggregation.count` 推断。
49. 用例-慢请求：查找并诊断超过延迟阈值的请求，输出慢 trace 列表含 duration、endpoint、service、trace ID 用于下钻。
50. 用例-请求失败：识别失败请求、失败原因和异常模式，输出按原因（HTTP code、exception、gRPC status）的失败分解及 exemplar trace。
51. 用例-服务依赖：理解服务到服务通信模式和外部 API 调用，输出依赖图含调用数、延迟、错误率。

适用边界 · 注意事项

• 不用于解释现有查询、产品文档或配置问题
• 不用于服务级 RED 指标（应使用 dt-obs-services）
• 不用于日志搜索（应使用 dt-obs-logs）或问题分析（应使用 dt-obs-problems）