dd-apm

Datadog APM

分布式追踪、服务映射和性能分析。

路由 — 请先阅读

将用户请求与下方条目匹配。每个条目的结构都相同：触发条件 → 要加载的子技能 → 要避免的反模式。如果一个请求似乎符合多个条目，请参阅“重叠情形判别”。如果没有匹配项，请参阅末尾的“以上都不适用”。

---

Kubernetes APM 安装 / 插桩 / 接入 — 当用户提到 Kubernetes、K8s、EKS、GKE、AKS、kind、minikube、K3s、helm、DatadogAgent CR、kubectl、集群上的 SSI、Pod 注入或 init 容器时触发。

立即阅读 .claude/skills/dd-apm/k8s-ssi/agent-install/SKILL.md，然后阅读 .claude/skills/dd-apm/k8s-ssi/enable-ssi/SKILL.md，再阅读 .claude/skills/dd-apm/k8s-ssi/verify-ssi/SKILL.md — 不要凭记忆继续操作。

常见的错误做法，看起来可行，实际上却会悄无声息地失败：

• helm install datadog datadog/datadog — 标准 chart 不支持通过 DatadogAgent CR 使用 SSI。
• 在应用中添加 ddtrace 导入或 ddtrace-run — SSI 会自动插桩，无需更改任何代码。
• 使用 admission.datadoghq.com/enabled 注解 — 这是 admission controller 的配置注入，不是 SSI init 容器注入。

---

Linux APM 安装 / 插桩 / 接入 — 当用户提到单台主机、VM、EC2 实例、裸机、RHEL/Ubuntu/Debian、systemd 或没有编排器时触发。

立即阅读 .claude/skills/dd-apm/linux-ssi/agent-install/SKILL.md，然后阅读 .claude/skills/dd-apm/linux-ssi/enable-ssi/SKILL.md，再阅读 .claude/skills/dd-apm/linux-ssi/verify-ssi/SKILL.md — 不要凭记忆继续操作。

不要通过普通的 apt-get install datadog-agent（或等效的 yum 命令）安装 Agent 后就认为 SSI 会随之启用 — 主机自动插桩需要使用带 SSI 标志的安装脚本，子技能会逐步介绍相关操作。

---

服务重命名 / 服务重新映射 — 当用户提到重命名服务、合并多个服务名称、移除后缀/前缀或清理推断出的服务时触发。

立即阅读 .claude/skills/dd-apm/service-remapping/SKILL.md — 不要凭记忆继续操作。

不要通过更改 tags.datadoghq.com/service 标签或 DD_SERVICE 环境变量来重命名 Datadog 中的服务。这需要进行一次发布，而且只会影响新数据。请使用服务重新映射规则 — 它会在数据摄取时改写名称，无需更改部署。

---

数据流监控（DSM）/ 队列和管道监控：当用户提到数据流、DSM、消费者或队列延迟、管道延迟、跨队列端到端延迟，或提到监控服务之间的 Kafka / RabbitMQ / SQS / SNS / Kinesis / Pub/Sub 流程时触发。

立即阅读 .claude/skills/dd-apm/enable-dsm/SKILL.md。不要凭记忆继续操作。

不要安装单独的 DSM Agent、软件包或库。DSM 在 APM 已注入的 Datadog SDK 中运行，并且每个服务只需一个设置即可启用。不要在未告知用户它包含在 APM Pro 和 Enterprise 中，且会在基础 APM 费用之外单独计费之前启用它。

---

重叠情况的判定

当一个请求看起来可能符合上面多个条目时，请使用以下判断规则：

提示	路由到
提到集群编排器（EKS/GKE/AKS/kind/K3s/minikube）——即使“只有一个节点”	k8s-ssi
单台主机、VM 或 EC2，且没有编排器	linux-ssi
“有几个服务，但它们应该是一个服务”	service-remapping——该子技能会根据重复项是真正经过监测的服务，还是推断出的实体（数据库、队列、外部 API），来选择规则类型
“我的服务显示的名称不对”	首先检查部署中的 DD_SERVICE。如果配置正确，但名称仍不对 → service-remapping。
“监控 Kafka” / “监控我的队列”	询问他们指的是代理/集群健康状况（Kafka Console、Agent 检查：https://docs.datadoghq.com/data_streams/kafka/setup/），还是服务之间的消息流（启用 enable-dsm）
“减少 APM 用量 / 成本 / 噪声”	目前还没有对应的子技能。建议命令前，先询问用户指的是采样（减少摄取的跟踪数据）还是保留过滤器（减少索引的数据）。

---

以上都不符合

如果请求与以上任何条目都不匹配，请继续阅读下面有关跟踪搜索、服务分析和指标的内容。如果仍然不符合，请让用户澄清——不要凭空编造工作流。

---

要求

必须安装 Datadog Labs Pup。如果尚未安装，请参阅 设置 Pup。

命令执行顺序（节省令牌）

对于范围明确的命令，请按以下顺序执行：

1. 首先检查上下文（之前的输出、对话、已保存的值）。
2. 如果缺少必需的值，先运行发现命令。
3. 如果仍有歧义，请询问用户确认。
4. 然后运行目标命令。
5. 避免运行可能失败的推测性命令。

快速开始

pup auth login
# Confirm env tag with the user first (do not assume production/prod/prd).
pup apm services list --env <env> --from 1h --to now
pup traces search --query "service:api-gateway" --from 1h

服务

列出服务

pup apm services list --env <env> --from 1h --to now
pup apm services stats --env <env> --from 1h --to now

服务统计信息

pup apm services stats --env <env> --from 1h --to now

服务映射

# View dependencies
pup apm flow-map --query "service:api-gateway&from=$(($(date +%s)-3600))000&to=$(date +%s)000" --env <env> --limit 10

跟踪

搜索跟踪

# By service
pup traces search --query "service:api-gateway" --from 1h

# Errors only
pup traces search --query "service:api-gateway status:error" --from 1h

# Slow traces (>1s)
pup traces search --query "service:api-gateway @duration:>1000ms" --from 1h

# With specific tag
pup traces search --query "service:api-gateway @http.url:/api/users" --from 1h

跟踪详情

# No direct get command for a single trace ID.
# Use traces search with a narrow query and time window.
pup traces search --query "trace_id:<trace_id>" --from 1h

关键指标

指标	衡量内容
trace.http.request.hits	请求数
trace.http.request.duration	延迟
trace.http.request.errors	错误数
trace.http.request.apdex	用户满意度

服务级目标

将 APM 与 SLO 关联：

pup slos create --file slo.json

常见查询

目标	查询
最慢的端点	avg:trace.http.request.duration{*} by {resource_name}
错误率	sum:trace.http.request.errors{*} / sum:trace.http.request.hits{*}
吞吐量	sum:trace.http.request.hits{*}.as_rate()

故障排查

问题	解决方法
没有跟踪数据	检查是否已安装 ddtrace，DD_TRACE_ENABLED=true
缺少服务	检查 DD_SERVICE 环境变量
跟踪数据未关联	检查跟踪标头是否已传播
基数过高	不要使用 user_id/request_id 作为标签

参考资料/文档

• APM 设置
• 跟踪搜索