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
サービスの最近の遅いトレースを検索する（過去 1 時間）	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
未解決の重大なセキュリティシグナルをトリアージする（過去 1 時間）	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 のセットアップ手順に従って 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

シンセティックス

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

オンコール

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