需要操作 Datadog 资源时用 pup CLI…

在已安装并认证 Datadog pup CLI 的环境中，通过命令行处理日志、指标、APM、监控器、事故、仪表盘、SLO、安全、审计与成本等 Datadog API 操作。

适用场景

解决思路

1. 安装 pup：按设置说明安装，链接：https://github.com/datadog-labs/agent-skills/tree/main?tab=readme-ov-file#setup-pup。
2. 验证安装：运行 `which pup`；运行 `pup --version`。
3. 对需要特定 scope 值（`<env>`、`<service-name>`、`<team-id>`、资源 ID）的命令，先检查上下文（对话历史、先前命令输出、保存变量）。
4. 如果缺失 scope 值，先运行发现命令（list/search）获取有效值。
5. 如果仍缺失或歧义，向用户确认确切值。
6. 然后运行目标命令。
7. 绝不要用未解析占位符（如 `<env>`、`<monitor-id>`）运行命令。
8. 运行 `pup auth login` 进行 OAuth2 浏览器登录（推荐）。
9. 运行 `pup auth status` 检查 token 有效性。
10. 运行 `pup auth status` 查看 token 剩余过期时间。
11. 运行 `pup auth refresh` 刷新过期 token（无需浏览器）。
12. 运行 `pup auth logout` 清除凭据。
13. Token 约 1 小时过期；若命令在对话中因 401/403 失败，先运行 `pup auth refresh`，若刷新失败再运行 `pup auth login` 完整重新认证。
14. 若 Chrome 打开错误的 profile/window，使用 `pup auth login` 打印的一次性 OAuth URL（`If the browser doesn't open, visit: ...`），在正确账号会话中手动打开该链接。
15. Headless/CI 无浏览器时，设置 `export DD_API_KEY=your-api-key`、`export DD_APP_KEY=your-app-key`、`export DD_SITE=datadoghq.com`（或 `datadoghq.eu` 等），或使用环境变量认证。
16. 列出 monitors：`pup monitors list --limit 10`。
17. 按 tags 列出 monitors：`pup monitors list --tags "env:<env>"`。
18. 获取 monitor：`pup monitors get <monitor-id>`。
19. 搜索 monitor：`pup monitors search --query "<monitor-name>"`。
20. 创建 monitor：`pup monitors create --file monitor.json`。
21. 更新 monitor：`pup monitors update <monitor-id> --file monitor.json`。
22. 对比 monitor 定义：`pup monitors diff <monitor-id> monitor.json`。
23. 删除 monitor：`pup monitors delete <monitor-id>`。
24. 没有 `pup monitors mute/unmute` 命令；改用 downtime payload：`pup downtime create --file downtime.json`。
25. 搜索错误日志：`pup logs search --query "status:error" --from 1h`。
26. 按 service 搜索日志：`pup logs search --query "service:<service-name>" --from 1h --limit 100`。
27. 搜索 5xx HTTP 状态日志：`pup logs search --query "@http.status_code:5*" --from 24h`。
28. 按 env 和 level 搜索日志：`pup logs search --query "env:<env> level:error" --from 1h`。
29. 聚合日志：`pup logs aggregate --query "service:<service-name>" --compute count --from 1h`。
30. 查询 metrics：`pup metrics query --query "avg:system.cpu.user{*}" --from 1h --to now`。
31. 查询 trace 指标：`pup metrics query --query "sum:trace.express.request.hits{service:<service-name>}" --from 1h --to now`。
32. 列出 metrics：`pup metrics list --filter "system.*"`。
33. 先与用户确认 env tag，不要假设 production/prod/prd。
34. 列出 APM services：`pup apm services list --env <env> --from 1h --to now`。
35. 按 service 搜索 traces：`pup traces search --query "service:<service-name>" --from 1h`。
36. 搜索慢 traces：`pup traces search --query "service:<service-name> @duration:>500ms" --from 1h`。
37. 搜索错误 traces：`pup traces search --query "service:<service-name> status:error" --from 1h`。
38. 列出 incidents：`pup incidents list --limit 50`。
39. 获取 incident：`pup incidents get <incident-id>`。
40. 导入 incident payload：`pup incidents import --file incident.json`。
41. 列出 dashboards：`pup dashboards list`。
42. 只读获取 dashboard：`pup dashboards get <dashboard-id> --read-only`。
43. 生成 live 时间窗口 dashboard URL：`pup dashboards url <dashboard-id> --from now-1h --to now --live true`。
44. 创建 dashboard：`pup dashboards create --file dashboard.json`。
45. 更新 dashboard：`pup dashboards update <dashboard-id> --file dashboard.json`。
46. 删除 dashboard：`pup dashboards delete <dashboard-id>`。
47. 安全 dashboard 创建、克隆和更新工作流：用 `--read-only` 获取源或更新目标并保存为不可变快照：`pup dashboards get <dashboard-id> --read-only -o json > dashboard-source.json`；绝不用转换后的 JSON 覆盖该文件。
48. 安全 dashboard 工作流第 2 步：构建单独的 mutation payload，在 create/update 前用 jq 删除 response-only 字段：`jq 'del(.author_handle, .author_name, .created_at, .id, .modified_at, .url)' dashboard-source.json > dashboard-payload.json`。
49. 安全 dashboard 工作流第 3 步：备份或克隆时保持源 dashboard 不变，只改明确请求的字段（通常是 `title` 或 `description`）；保留 `layout_type`、`reflow_type`、widget 顺序及每个递归 widget `layout` 对象（`x`、`y`、`width`、`height`、`is_column_break`）；不要重排或压缩坐标。
50. 安全 dashboard 工作流第 4 步：从 `dashboard-payload.json` create 或 update，然后把目标获取到新文件：`pup dashboards create --file dashboard-payload.json`；`pup dashboards get <destination-id> --read-only -o json > dashboard-destination.json`。
51. 安全 dashboard 工作流第 5 步：归一化掉 response-only 字段并比较完整定义；差异应仅为有意修改字段。
52. 安全 dashboard 工作流第 6 步：单独比较 layout projections，防止 placement 回归隐藏在大 widget diff 中：`jq '{layout_type, reflow_type, layouts: [.. | objects | .layout? // empty]}' dashboard-source.json`；`jq '{layout_type, reflow_type, layouts: [.. | objects | .layout? // empty]}' dashboard-destination.json`。
53. Pup 1.6.3 不暴露 dashboard version history；若需要精确历史版本且没有不可变快照，先在 Datadog UI 检查版本历史再修改 dashboard。
54. 列出 SLOs：`pup slos list`。
55. 获取 SLO：`pup slos get <slo-id>`。
56. 查看 SLO status：`pup slos status <slo-id> --from 30d --to now`。
57. 创建 SLO：`pup slos create --file slo.json`。
58. 列出 synthetic tests：`pup synthetics tests list`。
59. 获取 synthetic test：`pup synthetics tests get <test-id>`。
60. 搜索 synthetic tests：`pup synthetics tests search --text "login"`。
61. 列出 synthetic locations：`pup synthetics locations list`。
62. 列出 on-call teams：`pup on-call teams list`。
63. 从 `pup on-call teams list` 输出中选择真实 team id。
64. 获取 team：`pup on-call teams get <team-id>`。
65. 列出 team memberships：`pup on-call teams memberships list <team-id>`。
66. 列出 hosts：`pup infrastructure hosts list --count 50`。
67. 按 env 过滤 hosts：`pup infrastructure hosts list --filter "env:<env>"`。
68. 获取 host：`pup infrastructure hosts get <host-name>`。
69. 列出 recent events：`pup events list --from 24h`。
70. 按 tags 列出 events：`pup events list --tags "source:deploy"`。
71. 搜索 events：`pup events search --query "deploy" --from 24h --limit 50`。
72. 获取 event：`pup events get <event-id>`。
73. 列出 downtimes：`pup downtime list`。
74. 创建 downtime：`pup downtime create --file downtime.json`。
75. 取消 downtime：`pup downtime cancel <downtime-id>`。
76. 列出 users：`pup users list`。
77. 获取 user：`pup users get <user-id>`。
78. 列出 security signals：`pup security signals list --query "*" --from 1h --limit 100`。
79. triage open critical security signals：`pup security signals list --query "status:open severity:critical" --from 1h --limit 100`。
80. 历史 triage 用更大回溯：`pup security signals list --query "severity:critical" --from 24h --limit 100`。
81. 列出 recent audit logs：`pup audit-logs list --from 1h --limit 100`。
82. 用 Lucene 语法搜索 audit logs（与 Log Explorer 相同）：`pup audit-logs search --query "@action:deleted" --from 24h`。
83. 按用户搜索 audit logs：`pup audit-logs search --query "@usr.email:user@example.com" --from 7d`。
84. 搜索认证登录事件：`pup audit-logs search --query "@evt.name:Authentication @action:login" --from 7d`。
85. 调查 API key：`pup audit-logs search --query "@metadata.api_key.id:KEY_ID" --from 90d --limit 200`。
86. 输出 JSON 供 jq 管道处理：`pup audit-logs search --query "@action:deleted" --from 24h -o json | jq '.data[].attributes'`。
87. 搜索 monitor 修改事件：`pup audit-logs search --query "@evt.name:Monitor @action:modified" --from 7d`。
88. `audit-logs` 是长形式，长/短形式都可用。
89. 列出 service catalog：`pup service-catalog list`。
90. 获取 service：`pup service-catalog get <service-name>`。
91. 列出 notebooks：`pup notebooks list`。
92. 获取 notebook：`pup notebooks get <notebook-id>`。
93. 获取 workflow：`pup workflows get <workflow-id>`。
94. 运行 workflow：`pup workflows run <workflow-id> --payload '{"key":"value"}'`。
95. 列出 workflow instances：`pup workflows instances list <workflow-id>`。
96. 列出 obs pipelines：`pup obs-pipelines list --limit 50`。
97. 获取 pipeline：`pup obs-pipelines get <pipeline-id>`。
98. 创建 pipeline：`pup obs-pipelines create --file pipeline.json`。
99. 更新 pipeline：`pup obs-pipelines update <pipeline-id> --file pipeline.json`。
100. 删除 pipeline：`pup obs-pipelines delete <pipeline-id>`。
101. 验证 pipeline：`pup obs-pipelines validate --file pipeline.json`。
102. 列出 LLM obs projects：`pup llm-obs projects list`。
103. 创建 LLM obs project：`pup llm-obs projects create --file project.json`。
104. 列出 experiments：`pup llm-obs experiments list`。
105. 按 project 过滤 experiments：`pup llm-obs experiments list --filter-project-id <project-id>`。
106. 按 dataset 过滤 experiments：`pup llm-obs experiments list --filter-dataset-id <dataset-id>`。
107. 创建 experiment：`pup llm-obs experiments create --file experiment.json`。
108. 更新 experiment：`pup llm-obs experiments update <experiment-id> --file experiment.json`。
109. 删除 experiment：`pup llm-obs experiments delete --file delete-request.json`。
110. 列出 datasets：`pup llm-obs datasets list --project-id <project-id>`。
111. 创建 dataset：`pup llm-obs datasets create --project-id <project-id> --file dataset.json`。
112. 搜索 spans：`pup llm-obs spans search --ml-app <ml-app-name> --from 1h --limit 20`。
113. 列出 reference tables：`pup reference-tables list --limit 50`。
114. 获取 reference table：`pup reference-tables get <table-id>`。
115. 创建 reference table：`pup reference-tables create --file table.json`。
116. 批量查询 reference table：`pup reference-tables batch-query --file query.json`。
117. 列出 AWS CUR configs：`pup cost aws-config list`。
118. 获取 AWS config：`pup cost aws-config get <account-id>`。
119. 创建 AWS config：`pup cost aws-config create --file config.json`。
120. 删除 AWS config：`pup cost aws-config delete <account-id>`。
121. 列出 Azure UC configs：`pup cost azure-config list`。
122. 获取 Azure config：`pup cost azure-config get <account-id>`。
123. 创建 Azure config：`pup cost azure-config create --file config.json`。
124. 删除 Azure config：`pup cost azure-config delete <account-id>`。
125. 列出 GCP usage cost configs：`pup cost gcp-config list`。
126. 获取 GCP config：`pup cost gcp-config get <account-id>`。
127. 创建 GCP config：`pup cost gcp-config create --file config.json`。
128. 删除 GCP config：`pup cost gcp-config delete <account-id>`。
129. 确认安装版本：`pup --version`。
130. 列出所有命令：`pup --help`。
131. 查看命令帮助：`pup <command> --help`。
132. 过滤输出再格式化：`pup dashboards get <dashboard-id> --jq '{title, layout_type}'`。
133. 如果本地 help 与本技能不同，在发明 workaround 前比较 `pup --version` 与最新稳定版。
134. 401 Unauthorized：token 过期，运行 `pup auth refresh`。
135. 403 Forbidden：缺少 scope，检查 app key 权限。
136. 404 Not Found：ID/资源错误，验证资源存在。
137. Rate limited：请求过多，在调用之间加入延迟。
138. US1 (default)：设置 `DD_SITE=datadoghq.com`。
139. US3：设置 `DD_SITE=us3.datadoghq.com`。
140. US5：设置 `DD_SITE=us5.datadoghq.com`。
141. EU1：设置 `DD_SITE=datadoghq.eu`。
142. AP1：设置 `DD_SITE=ap1.datadoghq.com`。
143. AP2：设置 `DD_SITE=ap2.datadoghq.com`。
144. US1-FED：设置 `DD_SITE=ddog-gov.com`。

适用边界 · 注意事项

• 未安装 pup、没有 Datadog 账号，或没有对应 Datadog API/app key 权限/scope 时不适用。
• 需要 Datadog UI 专属 dashboard 版本历史且没有不可变快照时不适用（pup 1.6.3 不暴露版本历史）。
• 非 Datadog 可观测性、监控、审计或成本管理场景不适用。