dd-pup

pup（Datadog CLI）

用于执行 Datadog API 操作的 Pup CLI。支持 OAuth2 和 API 密钥身份验证。

快速参考

任务	命令
搜索错误日志	pup logs search --query "status:error" --from 1h
列出监控器	pup monitors list
比较监控器定义	pup monitors diff <monitor-id> monitor.json
安排监控器停机时间	pup downtime create --file downtime.json
在实时时间范围内打开仪表板	pup dashboards url <dashboard-id> --from now-1h --to now --live true
查找某项服务最近的慢速跟踪（过去 1h）	pup traces search --query "service:<service-name> @duration:>500ms" --from 1h
列出事件	pup incidents list --limit 50
导入事件负载	pup incidents import --file incident.json
查询指标	pup metrics query --query "avg:system.cpu.user{*}"
列出主机	pup infrastructure hosts list --count 50
检查 SLO	pup slos list
值班团队	pup on-call teams list
分流未解决的严重安全信号（过去 1h）	pup security signals list --query "status:open severity:critical" --from 1h --limit 100
搜索审计日志	pup audit-logs search --query "@action:deleted" --from 24h
按用户查看审计活动	pup audit-logs search --query "@usr.email:[email protected]" --from 7d
调查 API 密钥	pup audit-logs search --query "@metadata.api_key.id:KEY_ID" --from 90d
检查身份验证状态	pup auth status
查看令牌过期时间（剩余时间）	pup auth status
刷新令牌	pup auth refresh

前置条件

按照设置说明安装 pup。

必填输入解析

对于需要特定范围值（<env>、<service-name>、<team-id>、资源 ID）的命令，请按以下顺序处理：

1. 首先检查上下文（对话历史记录、先前命令输出、已保存的变量）。
2. 如果缺少值，先运行发现命令（列表/搜索）以获取有效值。
3. 如果仍然缺少值或存在歧义，请让用户确认准确值。
4. 然后运行目标命令。
5. 切勿使用尚未解析的占位符（如 <env> 或 <monitor-id>）运行命令。

身份验证

pup auth login          # OAuth2 browser flow (recommended)
pup auth status         # Check token validity
pup auth refresh        # Refresh expired token (no browser)
pup auth logout         # Clear credentials

令牌会过期（约 1 小时）。如果对话过程中命令返回 401/403 错误：

pup auth refresh        # Try refresh first
pup auth login          # If refresh fails, full re-auth

如果 Chrome 打开了错误的个人资料或窗口，请使用 pup auth login 打印的一次性 OAuth URL （If the browser doesn't open, visit: ...），并在正确的账户会话中手动打开该链接。

无头环境/CI（无浏览器）

# Use env vars or:
export DD_API_KEY=your-api-key
export DD_APP_KEY=your-app-key
export DD_SITE=datadoghq.com    # or datadoghq.eu, etc.

命令参考

监控器

pup monitors list --limit 10
pup monitors list --tags "env:<env>"
pup monitors get <monitor-id>
pup monitors search --query "<monitor-name>"
pup monitors create --file monitor.json
pup monitors update <monitor-id> --file monitor.json
pup monitors diff <monitor-id> monitor.json
pup monitors delete <monitor-id>
# No pup monitors mute/unmute commands; use downtime payloads instead.
pup downtime create --file downtime.json

日志

pup logs search --query "status:error" --from 1h
pup logs search --query "service:<service-name>" --from 1h --limit 100
pup logs search --query "@http.status_code:5*" --from 24h
pup logs search --query "env:<env> level:error" --from 1h
pup logs aggregate --query "service:<service-name>" --compute count --from 1h

指标

pup metrics query --query "avg:system.cpu.user{*}" --from 1h --to now
pup metrics query --query "sum:trace.express.request.hits{service:<service-name>}" --from 1h --to now
pup metrics list --filter "system.*"

APM / 跟踪

# 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:<service-name>" --from 1h
pup traces search --query "service:<service-name> @duration:>500ms" --from 1h
pup traces search --query "service:<service-name> status:error" --from 1h

事件

pup incidents list --limit 50
pup incidents get <incident-id>
pup incidents import --file incident.json

仪表板

pup dashboards list
pup dashboards get <dashboard-id> --read-only
pup dashboards url <dashboard-id> --from now-1h --to now --live true
pup dashboards create --file dashboard.json
pup dashboards update <dashboard-id> --file dashboard.json
pup dashboards delete <dashboard-id>

安全的仪表板创建、克隆和更新工作流

目标是获得可恢复的源版本和经过验证的目标版本。API 成功响应本身并不能证明小组件内容或位置得到了保留。

1. 使用 --read-only 获取源仪表板或更新目标，并将完整响应保存为不可变快照。切勿用转换后的 JSON 覆盖此文件。

   pup dashboards get <dashboard-id> --read-only -o json > dashboard-source.json
   

2. 单独构建变更负载。创建或更新前，移除仅用于响应的字段：author_handle、author_name、created_at、id、modified_at 和 url。

   jq 'del(.author_handle, .author_name, .created_at, .id, .modified_at, .url)' \
     dashboard-source.json > dashboard-payload.json
   

3. 备份或克隆时，保持源仪表板不变，仅修改明确要求的字段，通常是 title 或 description。保留 layout_type、reflow_type、小组件顺序，以及每个递归小组件的 layout 对象（x、y、width、height 和 is_column_break）。重新打包或压缩坐标会生成派生布局，而非精确克隆。
4. 使用 dashboard-payload.json 创建或更新，然后将目标仪表板获取到新文件中。

   pup dashboards create --file dashboard-payload.json
   pup dashboards get <destination-id> --read-only -o json > dashboard-destination.json
   

5. 去除仅用于响应的字段后，比较完整定义。差异应仅限于有意修改的字段。
6. 另外单独比较布局投影，以免位置回归问题被大量小组件差异掩盖：

   jq '{layout_type, reflow_type, layouts: [.. | objects | .layout? // empty]}' dashboard-source.json
   jq '{layout_type, reflow_type, layouts: [.. | objects | .layout? // empty]}' dashboard-destination.json
   

Pup 1.6.3 不支持查看仪表板版本历史。如果需要精确的历史版本，但不存在不可变快照，请在更改仪表板前检查 Datadog UI 中的版本历史。

SLO

pup slos list
pup slos get <slo-id>
pup slos status <slo-id> --from 30d --to now
pup slos create --file slo.json

Synthetics

pup synthetics tests list
pup synthetics tests get <test-id>
pup synthetics tests search --text "login"
pup synthetics locations list

On-Call

pup on-call teams list
# Pick a real team id from `pup on-call teams list` output.
pup on-call teams get <team-id>
pup on-call teams memberships list <team-id>

主机 / 基础设施

pup infrastructure hosts list --count 50
pup infrastructure hosts list --filter "env:<env>"
pup infrastructure hosts get <host-name>

事件

pup events list --from 24h
pup events list --tags "source:deploy"
pup events search --query "deploy" --from 24h --limit 50
pup events get <event-id>

停机时间

pup downtime list
pup downtime create --file downtime.json
pup downtime cancel <downtime-id>

用户 / 团队

pup users list
pup users get <user-id>

安全

pup security signals list --query "*" --from 1h --limit 100
pup security signals list --query "status:open severity:critical" --from 1h --limit 100
# Broader lookback for historical triage
pup security signals list --query "severity:critical" --from 24h --limit 100

审计日志

# List recent events
pup audit-logs list --from 1h --limit 100

# Search with query (Lucene syntax, same as Log Explorer)
pup audit-logs search --query "@action:deleted" --from 24h
pup audit-logs search --query "@usr.email:[email protected]" --from 7d
pup audit-logs search --query "@evt.name:Authentication @action:login" --from 7d
pup audit-logs search --query "@metadata.api_key.id:KEY_ID" --from 90d --limit 200

# JSON output for piping to jq
pup audit-logs search --query "@action:deleted" --from 24h -o json | jq '.data[].attributes'

# audit-logs is the long form (both work)
pup audit-logs search --query "@evt.name:Monitor @action:modified" --from 7d

服务目录

pup service-catalog list
pup service-catalog get <service-name>

笔记本

pup notebooks list
pup notebooks get <notebook-id>

工作流

pup workflows get <workflow-id>
pup workflows run <workflow-id> --payload '{"key":"value"}'
pup workflows instances list <workflow-id>

可观测性管道

pup obs-pipelines list --limit 50
pup obs-pipelines get <pipeline-id>
pup obs-pipelines create --file pipeline.json
pup obs-pipelines update <pipeline-id> --file pipeline.json
pup obs-pipelines delete <pipeline-id>
pup obs-pipelines validate --file pipeline.json

LLM 可观测性

pup llm-obs projects list
pup llm-obs projects create --file project.json
pup llm-obs experiments list
pup llm-obs experiments list --filter-project-id <project-id>
pup llm-obs experiments list --filter-dataset-id <dataset-id>
pup llm-obs experiments create --file experiment.json
pup llm-obs experiments update <experiment-id> --file experiment.json
pup llm-obs experiments delete --file delete-request.json
pup llm-obs datasets list --project-id <project-id>
pup llm-obs datasets create --project-id <project-id> --file dataset.json
pup llm-obs spans search --ml-app <ml-app-name> --from 1h --limit 20

参考表

pup reference-tables list --limit 50
pup reference-tables get <table-id>
pup reference-tables create --file table.json
pup reference-tables batch-query --file query.json

Cost Cloud 配置

# AWS CUR configs
pup cost aws-config list
pup cost aws-config get <account-id>
pup cost aws-config create --file config.json
pup cost aws-config delete <account-id>

# Azure UC configs
pup cost azure-config list
pup cost azure-config get <account-id>
pup cost azure-config create --file config.json
pup cost azure-config delete <account-id>

# GCP usage cost configs
pup cost gcp-config list
pup cost gcp-config get <account-id>
pup cost gcp-config create --file config.json
pup cost gcp-config delete <account-id>

子命令发现

pup --version           # Confirm installed version before documenting workarounds
pup --help              # List all commands
pup <command> --help    # Command-specific help
pup dashboards get <dashboard-id> --jq '{title, layout_type}'  # Filter output before formatting

如果本地帮助信息与此技能不一致，请将 pup --version 与最新稳定版进行比较，再尝试自行变通。

错误处理

错误	原因	修复方法
401 未授权	令牌已过期	pup auth refresh
403 禁止访问	缺少权限范围	检查应用密钥权限
404 未找到	ID / 资源错误	确认资源存在
请求频率受限	请求过多	在调用之间增加延迟

安装

请参阅设置 Pup获取安装说明。

验证安装

which pup
pup --version

站点

站点	DD_SITE 值
US1（默认）	datadoghq.com
US3	us3.datadoghq.com
US5	us5.datadoghq.com
EU1	datadoghq.eu
AP1	ap1.datadoghq.com
AP2	ap2.datadoghq.com
US1-FED	ddog-gov.com