datadog-cli

datadog-cli skill 概览

datadog-cli skill 用来帮助 agent 通过命令行使用 Datadog，完成实际的可观测性工作：搜索日志、追踪请求链路、查询指标、列出服务，以及管理 dashboard。它最适合已经拥有 Datadog 访问权限、希望在不手动点 UI 的情况下更快完成问题分诊的工程师、SRE、平台团队，以及 AI 辅助的事故响应人员。

datadog-cli 适合用来做什么

当你的真实目标不是“总结一下 Datadog”，而是“用可重复执行的命令调查一个生产故障现象”时，就该用 datadog-cli。这个 skill 在以下场景尤其强：

• 按服务、错误类型或时间窗口缩小事故范围
• 从日志快速切到 trace 上下文
• 判断某个峰值是新出现的问题，还是正常波动
• 快速拉取某个服务或环境的指标
• 用 CLI 驱动的流程检查或更新 dashboard

最适合的用户

这个 datadog-cli skill 适合以下用户：

• 已经在 Datadog 中使用 logs、metrics、traces 或 dashboards
• 希望 agent 直接生成正确命令，而不是给出模糊的搜索建议
• 需要的是事故分诊工作流，而不是泛泛的可观测性建议
• 能提供服务名、时间范围、trace ID 或 dashboard ID 等上下文

如果你没有 Datadog keys，或者还不清楚自己团队的服务 / tag 约定，那么影响效果的往往不是 skill 本身，而是初始化配置和 prompt 质量。

为什么它比通用 prompt 更有用

普通 prompt 可能只会说“去看看 Datadog 日志”。而这个 skill 给 agent 的是命令级的执行路径：logs search、logs tail、logs trace、logs context、logs patterns、logs compare、metrics query、errors、services，以及 dashboard 相关操作。它还明确指向那些会直接影响执行正确性的参考文档，尤其是查询语法和 dashboard 更新风险说明。

在采用前需要先知道的关键阻碍

主要障碍不是概念理解，而是实际运行条件：

• 必须提供 DD_API_KEY 和 DD_APP_KEY
• 非美国区 Datadog 账户可能需要加 --site，例如 datadoghq.eu
• 查询结果高度依赖正确的 Datadog query syntax
• dashboard 更新是破坏性操作，遗漏字段就可能被覆盖掉

在评价 datadog-cli usage 的效果之前，最好先优先确认这些点。

如何使用 datadog-cli skill

安装方式与运行环境

这个 skill 本身位于 softaworks/agent-toolkit，但它实际教 agent 调用的 CLI 是：

npx @leoflores/datadog-cli <command>

先设置凭据：

export DD_API_KEY="your-api-key"
export DD_APP_KEY="your-app-key"

如果是非美国区 Datadog 站点，需要传入 --site：

npx @leoflores/datadog-cli logs search --query "*" --site datadoghq.eu

如果你是在做实际的 datadog-cli install 评估，重点要验证的是外部 CLI 本身是否可用，以及 Datadog API 访问是否正常。

第一次正式使用前，先看这些文件

这个 skill 对参考资料的依赖比一般工具更强。建议按这个顺序看：

1. SKILL.md
2. references/query-syntax.md
3. references/logs-commands.md
4. references/metrics.md
5. references/workflows.md
6. references/dashboards.md

按这个路径阅读，能避开大多数首次运行时的常见错误：过滤条件写错、时间窗口过弱，以及不安全的 dashboard 编辑。

让 datadog-cli skill 发挥效果，需要提供哪些输入

当请求里至少包含以下部分信息时，datadog-cli skill 表现最好：

• 服务名、团队名或环境名
• 像 15m、1h 或 24h 这样的时间窗口
• 问题类型：errors、latency、failed requests、deployment regression
• 如果你手头有，最好给 trace ID、request ID 或 timestamp
• 你想看的是 logs、metrics、dashboards，还是完整的 triage workflow
• 如果不是默认美国站点，要说明 Datadog site

弱输入示例：“Check Datadog.”
强输入示例：“Investigate payment-api 5xx errors in prod for the last hour, compare against the previous hour, then pull any related traces and CPU metrics.”

把模糊目标改写成可执行的 prompt

一个好的 datadog-cli guide 型 prompt，应该同时告诉 agent 目标是什么，以及该如何缩小范围。

可以直接套这个模式：

Use datadog-cli for Observability triage.
Goal: identify why checkout failures increased after the last deploy.
Scope: service:payment-api env:prod
Time: last 1h, compare with previous 1h
Need: error summary, common log patterns, likely trace IDs, and key metrics
Site: datadoghq.eu

为什么这样写有效：

• 它给的是一个工作流，而不只是单条命令
• 它包含了 CLI 真正能用上的 query tags
• 它能避免 agent 搜得过宽、噪声太大

常见任务下，最适合先跑的 datadog-cli 命令

做事故分诊时，建议先广撒网，再逐步收窄：

npx @leoflores/datadog-cli errors --from 1h --pretty
npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty
npx @leoflores/datadog-cli logs patterns --query "status:error" --from 1h --pretty

然后再收敛到具体服务：

npx @leoflores/datadog-cli logs search --query "service:payment-api status:error env:prod" --from 1h --pretty

如果你已经有 trace：

npx @leoflores/datadog-cli logs trace --id "TRACE_ID" --from 24h --pretty

如果想看服务健康状况：

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{env:prod,service:payment-api}" --from 1h --pretty

Query syntax 的重要性比大多数人想象得更高

很多看起来像是 datadog-cli usage 效果差的问题，本质上其实都是 query 写得不够好。这个 skill 依赖 Datadog 的搜索语法，比如：

• service:api status:error
• @http.status_code:>=500
• service:api OR service:payment
• @duration:[1000 TO 5000]
• -status:info

如果你清楚自己的字段，直接明确写进去。
如果你还不清楚，就让 agent 先从更宽的 discovery queries 开始，再根据返回的属性逐步收紧。

用 datadog-cli 做事故响应的实用工作流

一个高效的 datadog-cli 调查闭环通常是：

1. 用 errors 获取错误总览
2. 用 logs compare 对比当前时间段和上一时间段
3. 用 logs patterns 聚类重复出现的失败模式
4. 用 logs search 按 service / env 缩小范围
5. 用 logs context 查看周边活动
6. 用 logs trace 切入分布式调用链路
7. 用 metrics query 确认资源或吞吐层面的信号

这比反复让 agent “多看点日志”要有效得多，因为每个命令回答的是不同的诊断问题。

使用 dashboards 时要格外谨慎

这个仓库里最重要的安全提示之一是：dashboards update 会替换整个 dashboard，而不是只更新改动过的字段。如果像 template variables、description 或 notify list 这样的字段被遗漏，它们就可能被直接删掉。

任何更新前，安全流程都应该是：

1. 先用 --output 把 dashboard 导出到临时文件
2. 保留现有字段
3. 基于完整保留结构执行更新

因此，只有当你能严格执行备份和全量状态更新流程时，datadog-cli skill 才适合用于 dashboard 相关工作。

这些输出质量技巧，真的会影响结果

如果你想让 agent 给出更好的结果：

• 明确说明你要的是 discovery、explanation，还是 exact commands
• 尽量同时提供 service 和 env tags
• 先限定一个明确时间窗口，只有在必要时再扩大
• 判断 regression 时，要求对比上一时间段
• 如果已有 trace ID 或 timestamp，优先提供
• 需要人工审阅时，主动要求加 --pretty

通常情况下，最大的质量提升来自“给出更精确的查询目标”，而不是让 agent 写得更长。

datadog-cli 中，什么时候该用 logs、metrics 或 dashboards

当你需要看到具体事件、错误或请求细节时，用 logs。
当你需要看趋势、资源占用或速率 / 延迟信号时，用 metrics。
当你需要复用现有运维视图，或者想把一个视图交付给团队时，用 dashboards。

如果你一次性要求 agent 同时使用这三者，请明确说明你的决策目标：root cause、blast radius、regression check，还是 dashboard creation。

datadog-cli skill 常见问题

datadog-cli 适合新手吗？

适合，前提是你已经有 Datadog 访问权限，并理解 services、tags、time windows 这些基础概念。
不太适合，如果你还在学习 logs、traces、metrics 分别代表什么。这个 skill 能减少命令层面的猜测，但它不能替代你对环境命名和可观测性约定的基本了解。

它和直接使用 Datadog UI 有什么区别？

当你需要可重复、可脚本化、由 agent 生成的调查步骤时，datadog-cli 更有优势。它尤其适合快速 triage、由 prompt 驱动的调试，以及共享精确命令。
但在深度可视化探索和临时浏览方面，UI 仍然更强。

什么情况下 datadog-cli 不适合用？

以下情况不建议使用这个 skill：

• 你的组织禁止使用 Datadog API key
• 你需要的是 CLI 工作流没有暴露的 UI-only 功能
• 你想要的是宽泛的 observability 理论，而不是 Datadog-specific execution
• 你无法提供足够上下文，让 agent 形成有效 query

除了 skill 本身，还需要安装别的吗？

需要。关键运行依赖是下面这个 Datadog CLI：

npx @leoflores/datadog-cli <command>

你还需要配置 DD_API_KEY 和 DD_APP_KEY。部分账户还必须传入 --site。

datadog-cli 只能做 Observability 查询，还是也能修改内容？

它主要用于检查和调查，但 dashboard 相关命令确实可能修改状态。这也是最需要谨慎的部分。在允许任何更新流程前，先读 references/dashboards.md。

它比直接让 agent “check logs” 更好吗？

是的，因为这个 skill 给 agent 的不是空泛指令，而是明确的命令族和参考文档。这通常意味着更快的范围收窄、更少格式错误的 query，以及比普通自由提问更可用的事故处理流程。

如何改进 datadog-cli skill 的使用效果

在 prompt 开头就说明操作约束

想快速提升 datadog-cli 输出质量，最有效的做法是把 CLI 真正需要的约束一开始就说清楚：

• Datadog site
• environment
• service names
• time range
• 像 trace ID 或 dashboard ID 这样的 identifiers
• 这是只读任务，还是允许修改 dashboards

否则，agent 往往会默认生成范围过大、信号很弱的命令。

不要只要一条命令，要直接要一个工作流

一个常见失败模式是：问题本来需要一串命令，你却只让它做单次查询。更好的 prompt 是：

Use datadog-cli to triage a spike in 5xx responses for service:checkout in env:prod over the last hour.
First compare against the prior hour, then identify top error patterns, then pull relevant traces, then check CPU and memory metrics.

之所以效果更好，是因为它直接映射到了仓库里已有的 workflow references。

提供更强的 query 原料

好的输入应该尽量包含真实 Datadog 字段：

• service:payment-api
• env:prod
• @http.status_code:>=500
• @error.kind:TimeoutError
• @duration:>=1000

如果你只给自然语言描述，比如“the API is slow”，那 agent 就必须自己猜字段名和过滤条件。字段级输入越具体，datadog-cli usage 的结果通常越好。

涉及 dashboard 编辑时，用安全优先的 prompt

如果任务涉及 dashboards，请明确要求先备份再修改：

Use datadog-cli to update dashboard abc-def-ghi, but first export the current dashboard to a temp file, preserve template variables and description, and show the exact safe update command.
Do not produce a partial update.

这能显著降低这个 skill 里最危险、也最容易造成破坏的问题。

拿到第一轮输出后，靠收窄来迭代，不要盲目放大范围

在第一组命令出来后，更好的优化方式是继续收窄：

• 从全量 errors 缩到单个 service
• 从 24h 缩到精确故障窗口
• 从通用 logs 缩到 pattern grouping
• 从 symptom 缩到 trace-level evidence
• 从 logs 切到 metrics 做确认

这比直接让 agent “再给我更多细节”更有效，因为后者往往只会放大噪声。

需要避免的常见错误

最常见的采用问题和输出问题包括：

• 缺少 DD_API_KEY 或 DD_APP_KEY
• 在非美国区 Datadog 中忘记加 --site
• 使用了弱查询或无效 query syntax
• 一开始就查太大的时间范围
• 把 dashboard update 当成 patch，而不是全量替换
• 请求 observability 帮助时，没有说明受影响的 service 或 env

当结果偏弱时，应该回头检查仓库里的哪些内容

如果 agent 的回答显得过于泛泛，可以回去重点看：

• references/query-syntax.md，提升过滤精度
• references/logs-commands.md，优化命令选择
• references/workflows.md，理清调查顺序
• references/dashboards.md，确认安全修改模式

相比从头重写整个请求，这条阅读路径通常更快修复效果差的 prompt。

安装后评估 datadog-cli 是否可用的最佳方式

一个实用的 datadog-cli install 验收测试可以这样做：

1. 运行一个已知可命中的 logs search
2. 运行一个带明确范围的 metrics query
3. 测试一个 workflow 命令，如 errors 或 logs patterns
4. 如果不在美国区，确认 --site 行为正确
5. 在验证完备份流程前，不要执行 dashboard 写操作

如果这些都能顺利通过，基本就可以认为这个 datadog-cli skill 已经能投入真实的事故处理和可观测性工作。