datadog-cli

datadog-cli skill の概要

datadog-cli skill は、Datadog をコマンドラインから使って実務的なオブザーバビリティ対応を進めるためのスキルです。ログ検索、リクエストトレース、メトリクス照会、サービス一覧の確認、ダッシュボード管理までを CLI ベースで進められるため、Datadog にすでにアクセスできるエンジニア、SRE、プラットフォームチーム、AI 支援でインシデント対応を行う担当者に向いています。UI を手でたどるよりも、再現性のある手順で素早く切り分けたい場面で特に有効です。

datadog-cli が向いている用途

datadog-cli を使うべきなのは、「Datadog を要約してほしい」ではなく、「本番で起きている症状を、再利用できるコマンドで調査したい」というケースです。特に強いのは次のような場面です。

• サービス名、エラー種別、時間帯でインシデントを絞り込みたい
• ログからトレース文脈へすばやく移りたい
• スパイクが新規の異常なのか、平常の範囲なのかを確認したい
• サービスや環境に対するメトリクスを素早く引きたい
• ダッシュボードを CLI 主導のフローで確認・更新したい

向いているユーザー

この datadog-cli skill は、次のようなユーザーに適しています。

• Datadog をログ、メトリクス、トレース、ダッシュボード用途で日常的に使っている
• あいまいな検索提案ではなく、正しいコマンドをエージェントに生成してほしい
• 一般論のオブザーバビリティ解説ではなく、インシデント切り分けの実務フローが必要
• サービス名、時間範囲、trace ID、dashboard ID などを提示できる

Datadog のキーをまだ持っていない場合や、サービス名・タグ命名のルールを把握していない場合は、スキルそのものよりもセットアップとプロンプト品質のほうが結果に大きく影響します。

汎用プロンプトよりこの skill のほうが実用的な理由

普通のプロンプトだと「Datadog のログを見て」で終わりがちです。これに対してこのスキルは、logs search、logs tail、logs trace、logs context、logs patterns、logs compare、metrics query、errors、services、ダッシュボード操作といった、実行可能なコマンド単位の導線をエージェントに与えます。さらに、正しく動かすうえで重要な参照先、特にクエリ構文やダッシュボード更新時の注意点まで案内されているのが違いです。

先に知っておきたい主な導入障壁

つまずきやすいのは概念面より運用面です。

• DD_API_KEY と DD_APP_KEY が必須
• US 以外の Datadog アカウントでは datadoghq.eu のような --site 指定が必要なことがある
• 結果の良し悪しは Datadog のクエリ構文を正しく書けるかに強く依存する
• ダッシュボード更新は、フィールドを省くと破壊的な変更になりうる

datadog-cli usage の質を判断する前に、まずここを確認するのが先です。

datadog-cli skill の使い方

インストールと実行時コンテキスト

スキル自体は softaworks/agent-toolkit にありますが、実際にエージェントが実行する CLI は次です。

npx @leoflores/datadog-cli <command>

まず認証情報を設定します。

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

US 以外の 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

この順で押さえると、初回で起きがちな失敗、たとえばフィルタの書き方が甘い、時間範囲が弱い、ダッシュボード編集が危険、といった問題をかなり減らせます。

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 か
• デフォルトの US 以外なら Datadog site

弱い入力: 「Datadog を確認して」
強い入力: 「過去 1 時間の prod で発生している payment-api の 5xx errors を調査し、前の 1 時間と比較したうえで、関連 trace と CPU metrics も見て」

大まかな目的を実用的なプロンプトに変える

よい datadog-cli guide プロンプトは、目的だけでなく、どう絞り込むかまでエージェントに渡します。

次の型が使いやすいです。

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 tag が含まれている
• 広すぎる検索に流れにくい

よくある作業で最初に打つべきコマンド

インシデント切り分けでは、まず広く見てから絞るのが基本です。

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

想像以上に重要なクエリ構文

弱い datadog-cli usage の多くは、実はスキルの問題ではなくクエリ品質の問題です。この skill は Datadog の検索構文に強く依存します。たとえば次のような書き方です。

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

フィールド名が分かっているなら、必ず明示的に入れてください。分からないなら、最初は広めの discovery query をエージェントに作らせ、返ってきた属性を見てから絞り込むほうが失敗しにくいです。

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 でリソースやスループットのシグナルを裏取りする

ただ「もっとログを見て」と繰り返すより、この流れのほうがはるかに有効です。各コマンドが別々の診断質問に答えるからです。

ダッシュボード操作は特に注意が必要

この repo で最重要の安全上の注意は、dashboards update が差分更新ではなく、ダッシュボード全体を置き換える点です。template variables、description、notify list などのフィールドを省略すると、そのまま消える可能性があります。

更新前の安全な手順は次のとおりです。

1. --output でダッシュボードを一度 temp file に取得する
2. 既存フィールドを保持する
3. 保持した完全な構造のまま更新する

このため、datadog-cli skill をダッシュボード作業に使うなら、バックアップ運用と完全状態での更新を徹底できることが前提になります。

出力品質を変える実践的なコツ

エージェントからよりよい回答を引き出すには、次を意識してください。

• discovery が欲しいのか、説明が欲しいのか、正確なコマンドが欲しいのかを明示する
• 可能なら service tag と env tag をセットで入れる
• まずは時間範囲を狭く切る。必要なときだけ広げる
• リグレッション確認では前期間との比較を依頼する
• すでにあるなら trace ID や timestamp を渡す
• 人が確認する前提なら --pretty を指定する

たいてい最も効く改善は、説明を長く求めることではなく、クエリ対象を具体的にすることです。

logs・metrics・dashboards の使い分け

具体的なイベント、エラー、リクエスト詳細が欲しいなら logs を使います。
傾向、リソース使用量、レートやレイテンシのシグナルを見るなら metrics が向いています。
既存の運用ビューを活用したい、あるいはチーム向けの見せ方を整えたいなら dashboards が適しています。

3 つすべてを同時にエージェントへ頼む場合は、判断目的も添えてください。たとえば root cause、blast radius、regression check、dashboard creation といった形です。

datadog-cli skill の FAQ

datadog-cli は初心者にも向いていますか？

はい。ただし、Datadog へのアクセスがあり、services、tags、time windows といった基本概念が分かっているなら、という条件付きです。逆に、logs・traces・metrics の意味自体をまだ学習中なら向きません。この skill はコマンドの当て推量を減らしてくれますが、環境名やオブザーバビリティ上の命名規約まで代わりに理解してくれるわけではありません。

Datadog UI を直接使うのと何が違いますか？

datadog-cli が強いのは、再現可能で、スクリプト化できて、エージェントが調査手順を組み立てられる点です。特に、迅速なトリアージ、プロンプト駆動のデバッグ、正確なコマンド共有に向いています。一方で、深い可視化や、その場での探索的な閲覧は UI のほうが依然として得意です。

datadog-cli が向いていないのはどんなときですか？

次のような場合、この skill は適しません。

• 組織の方針で Datadog API key の利用がブロックされている
• CLI ワークフローに出ていない UI 専用機能が必要
• Datadog 固有の実行手順ではなく、広い意味での observability 理論を知りたい
• エージェントが有効な query を組めるだけの文脈を渡せない

skill 以外に何かインストールは必要ですか？

はい。実行時に重要なのは、次の Datadog CLI です。

npx @leoflores/datadog-cli <command>

加えて DD_API_KEY と DD_APP_KEY が必要です。アカウントによっては --site も必須です。

datadog-cli は Observability の参照専用ですか？ 変更操作もできますか？

基本は確認と調査のためのものですが、ダッシュボード系コマンドは状態変更を伴います。最も慎重に扱うべきなのはそこです。更新フローを許可する前に、必ず references/dashboards.md を読んでください。

エージェントに「ログを見て」と頼むより本当に良いですか？

はい。この skill はエージェントに、具体的なコマンド群と参照ドキュメントを与えます。その結果、通常の自由入力プロンプトよりも、絞り込みが速く、壊れた query が減り、インシデント対応の流れとしても実用的になりやすいです。

datadog-cli skill を改善するには

まず運用上の制約をプロンプトに入れる

datadog-cli の出力を最も手早く改善する方法は、CLI が実際に必要とする制約条件を最初から含めることです。

• Datadog site
• environment
• service names
• time range
• trace ID や dashboard ID のような識別子
• read-only タスクなのか、dashboards の変更を許可するのか

これがないと、エージェントは広く浅い、シグナルの弱いコマンドに寄りがちです。

単発コマンドではなくワークフローを要求する

よくある失敗は、問題が連続した調査を必要としているのに、単発の lookup だけを依頼してしまうことです。たとえば次のように依頼します。

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.

この形のほうがよい調査になりやすいのは、repo にある workflow リファレンスにそのまま対応しているからです。

より強いクエリ材料を渡す

よい入力には、実際の Datadog フィールドが含まれます。

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

「API が遅い」のような自然文だけだと、エージェントは field 名や filter を推測するしかありません。フィールド単位の入力が強いほど、datadog-cli usage の品質も上がります。

ダッシュボード編集は安全優先のプロンプトにする

タスクが dashboard に触れるなら、バックアップ優先の流れを明示してください。

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 における最大の破壊的リスクを大きく減らせます。

最初の出力後は、闇雲に広げず絞り込んでいく

最初のコマンドセットを見た後は、次の方向で改善すると効果的です。

• 全エラーから 1 つの service へ絞る
• 24h から正確な failure window へ絞る
• 汎用的な logs から pattern grouping へ進める
• 症状レベルから trace-level evidence へ進める
• logs から metrics に切り替えて裏を取る

「もっと詳しく」とだけ頼むより、こうして絞っていくほうがノイズが増えにくいです。

避けたい典型的なミス

導入時・出力時によくある問題は次のとおりです。

• DD_API_KEY または DD_APP_KEY が不足している
• US 以外の Datadog なのに --site を付け忘れる
• query syntax が弱い、または無効
• 最初から時間範囲を広く取りすぎる
• dashboard update を patch 的な更新だと誤解し、完全置換であることを見落とす
• 影響を受けている service や env を示さずに observability 支援を求める

datadog-cli の結果が弱いときに repo のどこを見るべきか

エージェントの出力が総花的に見えるなら、次を見直してください。

• references/query-syntax.md で filter の精度を上げる
• references/logs-commands.md でコマンド選択を改善する
• references/workflows.md で調査順序を確認する
• references/dashboards.md で安全な変更パターンを把握する

リクエスト全体を書き直すより、この順で読み返したほうが、悪いプロンプトを早く立て直せることが多いです。

インストール後に datadog-cli を評価する最善の方法

datadog-cli install の実用的な受け入れテストは次の流れです。

1. 既知の logs search を実行する
2. スコープを絞った metrics query を実行する
3. errors か logs patterns のような workflow command を 1 つ試す
4. US 以外なら --site の挙動を確認する
5. dashboard への書き込みは、バックアップ手順が検証できるまで避ける

ここまで問題なく通るなら、datadog-cli skill は実際のインシデント対応や observability 作業に投入できる状態にかなり近いはずです。