dd-pup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

pup (Datadog CLI)

pup（Datadog CLI）

Pup CLI for Datadog API operations. Supports OAuth2 and API key auth.

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

Quick Reference

快速参考

Task	Command
Search error logs	`pup logs search --query "status:error" --duration 1h`
List monitors	`pup monitors list`
Mute a monitor	`pup monitors mute --id 123 --duration 1h`
Find slow traces	`pup apm traces list --service api --min-duration 500ms`
List active incidents	`pup incidents list --status active`
Create incident	`pup incidents create --title "Issue" --severity SEV-2`
Query metrics	`pup metrics query --query "avg:system.cpu.user{*}"`
List hosts	`pup hosts list`
Check SLOs	`pup slos list`
Who's on call	`pup on-call who --team my-team`
Security signals	`pup security signals list --severity critical`
Check auth	`pup auth status`
Refresh token	`pup auth refresh`

任务	命令
搜索错误日志	`pup logs search --query "status:error" --duration 1h`
列出监控项	`pup monitors list`
静音监控项	`pup monitors mute --id 123 --duration 1h`
查询慢链路	`pup apm traces list --service api --min-duration 500ms`
列出活跃事件	`pup incidents list --status active`
创建事件	`pup incidents create --title "Issue" --severity SEV-2`
查询指标	`pup metrics query --query "avg:system.cpu.user{*}"`
列出主机	`pup hosts list`
检查SLO	`pup slos list`
查询值班人员	`pup on-call who --team my-team`
查看安全信号	`pup security signals list --severity critical`
检查身份验证状态	`pup auth status`
刷新令牌	`pup auth refresh`

Prerequisites

前置要求

bash

undefined

bash

undefined

Install pup

go install github.com/datadog-labs/pup@latest export PATH="$HOME/go/bin:$PATH"

undefined

go install github.com/datadog-labs/pup@latest export PATH="$HOME/go/bin:$PATH"

undefined

Auth

身份验证

bash

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

⚠️ Tokens expire (~1 hour). If a command fails with 401/403 mid-conversation:

bash

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

bash

pup auth login          # OAuth2浏览器流程（推荐）
pup auth status         # 检查令牌有效性
pup auth refresh        # 刷新过期令牌（无需浏览器）
pup auth logout         # 清除凭证

⚠️ 令牌有效期约1小时。如果命令执行过程中返回401/403错误：

bash

pup auth refresh        # 先尝试刷新令牌
pup auth login          # 如果刷新失败，重新完成完整身份验证

Headless/CI (no browser)

无界面/CI场景（无浏览器）

bash

undefined

bash

undefined

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.

undefined

export DD_API_KEY=your-api-key export DD_APP_KEY=your-app-key export DD_SITE=datadoghq.com # 或 datadoghq.eu 等

undefined

Command Reference

命令参考

Monitors

监控项

bash

pup monitors list --limit 10
pup monitors list --tags "env:prod"
pup monitors get --id 12345
pup monitors mute --id 12345 --duration 1h
pup monitors unmute --id 12345
pup monitors create --name "High CPU" --type "metric alert" \
  --query "avg(last_5m):avg:system.cpu.user{*} > 80" \
  --message "CPU high @slack-ops"

bash

pup monitors list --limit 10
pup monitors list --tags "env:prod"
pup monitors get --id 12345
pup monitors mute --id 12345 --duration 1h
pup monitors unmute --id 12345
pup monitors create --name "High CPU" --type "metric alert" \
  --query "avg(last_5m):avg:system.cpu.user{*} > 80" \
  --message "CPU high @slack-ops"

Logs

日志

bash

pup logs search --query "status:error" --duration 1h
pup logs search --query "service:payment-api" --duration 1h --limit 100
pup logs search --query "@http.status_code:5*" --duration 24h
pup logs search --query "env:prod level:error" --duration 1h --json

bash

pup logs search --query "status:error" --duration 1h
pup logs search --query "service:payment-api" --duration 1h --limit 100
pup logs search --query "@http.status_code:5*" --duration 24h
pup logs search --query "env:prod level:error" --duration 1h --json

Metrics

指标

bash

pup metrics query --query "avg:system.cpu.user{*}" --duration 1h
pup metrics query --query "sum:trace.express.request.hits{service:api}" --duration 1h
pup metrics list --filter "system.*"

bash

pup metrics query --query "avg:system.cpu.user{*}" --duration 1h
pup metrics query --query "sum:trace.express.request.hits{service:api}" --duration 1h
pup metrics list --filter "system.*"

APM / Traces

APM / 链路追踪

bash

pup apm services list
pup apm traces list --service my-service --duration 1h
pup apm traces list --service api --min-duration 500ms --duration 1h
pup apm traces list --service api --status error --duration 1h
pup apm traces get abc123def456

bash

pup apm services list
pup apm traces list --service my-service --duration 1h
pup apm traces list --service api --min-duration 500ms --duration 1h
pup apm traces list --service api --status error --duration 1h
pup apm traces get abc123def456

Incidents

事件

bash

pup incidents list --status active
pup incidents list --status resolved --duration 7d
pup incidents create --title "API Degradation" --severity SEV-2
pup incidents update --id abc-123 --status stable
pup incidents resolve --id abc-123

bash

pup incidents list --status active
pup incidents list --status resolved --duration 7d
pup incidents create --title "API Degradation" --severity SEV-2
pup incidents update --id abc-123 --status stable
pup incidents resolve --id abc-123

Dashboards

仪表盘

bash

pup dashboards list
pup dashboards list --tags "team:platform"
pup dashboards get --id abc-123
pup dashboards create --title "My Dashboard" --description "..." --widgets '[...]'

bash

pup dashboards list
pup dashboards list --tags "team:platform"
pup dashboards get --id abc-123
pup dashboards create --title "My Dashboard" --description "..." --widgets '[...]'

SLOs

SLO

bash

pup slos list
pup slos get --id slo-123
pup slos history --id slo-123 --duration 30d

bash

pup slos list
pup slos get --id slo-123
pup slos history --id slo-123 --duration 30d

Synthetics

合成监控

bash

pup synthetics list
pup synthetics results --test-id abc-123
pup synthetics trigger --test-id abc-123

bash

pup synthetics list
pup synthetics results --test-id abc-123
pup synthetics trigger --test-id abc-123

On-Call

值班

bash

pup on-call teams list
pup on-call schedules list
pup on-call who --team platform-team

bash

pup on-call teams list
pup on-call schedules list
pup on-call who --team platform-team

Hosts / Infrastructure

主机 / 基础设施

bash

pup hosts list --limit 50
pup hosts list --filter "env:prod"
pup hosts mute --hostname web-01 --duration 1h
pup hosts get --hostname web-01

bash

pup hosts list --limit 50
pup hosts list --filter "env:prod"
pup hosts mute --hostname web-01 --duration 1h
pup hosts get --hostname web-01

Events

事件

bash

pup events list --duration 24h
pup events list --tags "source:deploy"
pup events post --title "Deploy started" --text "v1.2.3" --tags "env:prod"

bash

pup events list --duration 24h
pup events list --tags "source:deploy"
pup events post --title "Deploy started" --text "v1.2.3" --tags "env:prod"

Downtimes

计划维护

bash

pup downtime list
pup downtime create --scope "env:staging" --duration 2h --message "Maintenance"
pup downtime cancel --id 12345

bash

pup downtime list
pup downtime create --scope "env:staging" --duration 2h --message "Maintenance"
pup downtime cancel --id 12345

Users / Teams

用户 / 团队

bash

pup users list
pup teams list

bash

pup users list
pup teams list

Security

安全

bash

pup security signals list --duration 24h
pup security signals list --severity critical

bash

pup security signals list --duration 24h
pup security signals list --severity critical

Service Catalog

服务目录

bash

pup services list
pup services get --name payment-api

bash

pup services list
pup services get --name payment-api

Notebooks

笔记本

bash

pup notebooks list
pup notebooks get --id 12345

bash

pup notebooks list
pup notebooks get --id 12345

Workflows

工作流

bash

pup workflows list
pup workflows trigger --id workflow-123 --input '{"key": "value"}'

bash

pup workflows list
pup workflows trigger --id workflow-123 --input '{"key": "value"}'

Subcommand Discovery

子命令查询

bash

pup --help              # List all commands
pup <command> --help    # Command-specific help

bash

pup --help              # 列出所有命令
pup <command> --help    # 查看特定命令的帮助信息

Error Handling

错误处理

Error	Cause	Fix
401 Unauthorized	Token expired	`pup auth refresh`
403 Forbidden	Missing scope	Check app key permissions
404 Not Found	Wrong ID/resource	Verify resource exists
Rate limited	Too many requests	Add delays between calls

错误	原因	解决方案
401 Unauthorized	令牌过期	`pup auth refresh`
403 Forbidden	缺少权限范围	检查应用密钥权限
404 Not Found	ID/资源错误	确认资源存在
Rate limited	请求过多	在请求之间添加延迟

Install

安装

bash

go install github.com/DataDog/pup@latest

bash

go install github.com/DataDog/pup@latest

Verify Installation

验证安装

bash

undefined

bash

undefined

Check if pup is in PATH

which pup

If not found, check if it was installed

ls ~/go/bin/pup

undefined

ls ~/go/bin/pup

undefined

PATH Troubleshooting

PATH问题排查

pup

is installed but

which pup

returns nothing, Go's bin directory isn't in your PATH.

Check where pup is:

bash

ls ~/go/bin/pup           # Standard location
ls $GOPATH/bin/pup        # If GOPATH is set
ls $GOBIN/pup             # If GOBIN is set

Add to PATH (pick your shell):

For zsh (macOS default):

bash

undefined

如果

pup

已安装但

which pup

无返回，说明Go的bin目录不在你的PATH中。

检查pup的安装位置：

bash

ls ~/go/bin/pup           # 标准位置
ls $GOPATH/bin/pup        # 如果设置了GOPATH
ls $GOBIN/pup             # 如果设置了GOBIN

添加到PATH（选择对应的shell）：

对于zsh（macOS默认shell）：

bash

undefined

Add this line to ~/.zshrc

export PATH="$HOME/go/bin:$PATH"

Then reload

source ~/.zshrc


For **bash**:
```bash

source ~/.zshrc


对于**bash**：
```bash

Add this line to ~/.bashrc or ~/.bash_profile

export PATH="$HOME/go/bin:$PATH"

Then reload

source ~/.bashrc


For **fish**:
```fish

source ~/.bashrc


对于**fish**：
```fish

Add this line to ~/.config/fish/config.fish

fish_add_path $HOME/go/bin

Or set permanently

set -Ux fish_user_paths $HOME/go/bin $fish_user_paths

Then reload

source ~/.config/fish/config.fish


**Verify:**
```bash
which pup        # Should show path
pup --version    # Should show version

source ~/.config/fish/config.fish


**验证：**
```bash
which pup        # 应返回pup的路径
pup --version    # 应返回版本号

Alternative: Full Path

替代方案：使用完整路径

If you don't want to modify PATH, use the full path:

bash

~/go/bin/pup auth login
~/go/bin/pup monitors list

Or create an alias:

bash

alias pup="$HOME/go/bin/pup"

如果你不想修改PATH，可以直接使用完整路径：

bash

~/go/bin/pup auth login
~/go/bin/pup monitors list

或者创建别名：

bash

alias pup="$HOME/go/bin/pup"

Sites

站点

Site	`DD_SITE` value
US1 (default)	`datadoghq.com`
US3	`us3.datadoghq.com`
US5	`us5.datadoghq.com`
EU1	`datadoghq.eu`
AP1	`ap1.datadoghq.com`
US1-FED	`ddog-gov.com`

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