datadog-analyser

Datadog 分析

pup CLI を使用して、Datadog のオブザーバビリティデータを調査・分析します。

入力

生の引数：$ARGUMENTS

引数から次の情報を推定します。

• QUERY：分析する内容。
• SINCE：（省略可能）分析期間の開始日時を示す UTC ISO8601。指定された場合は、pup の --from フラグに渡すため、エポック秒に変換します（例：Linux では date -d "2026-03-20T02:30:00Z" +%s、macOS では date -jf "%Y-%m-%dT%H:%M:%SZ" "2026-03-20T02:30:00Z" +%s）。
• UNTIL：（省略可能）分析期間の終了日時を示す UTC ISO8601。指定された場合は、対応している箇所で --to フラグに渡すため、エポック秒に変換します。それ以外の場合は省略します（デフォルトは現在時刻です）。
• SERVICE_HINT：（省略可能）クエリで優先するサービス名です（最初にこのサービスでモニター、ログ、APM をフィルタリングします）。

システム要件

• pup CLI がインストールされていること — https://github.com/datadog-labs/pup/blob/main/README.md を参照してください
• DD_API_KEY と DD_APP_KEY の環境変数が設定されていること。重要： これらの変数を確認するときは、未設定と判断する前に少なくとも 2 回確認してください。シェルコンテキストの違いにより、環境変数が未設定のように見えることがあります。値を決して公開しないでください — 存在確認のみを行ってください（例：test -n "$DD_API_KEY"）。
• datadoghq.com を使用しない場合は DD_SITE が設定されていること（省略可能）

出力ディレクトリ

.datadog-analyser-tmp/
└── report.md    # Final analysis report

実行

1. 接続を確認する

CLI が設定され、接続されていることを確認するため、pup test を実行します。

pup test

失敗した場合は、AskUserQuestion を使用して、pup が設定されていないか、DD_API_KEY／DD_APP_KEY が設定されていないことをユーザーに伝え、セットアップガイドへのリンクを示します：https://github.com/datadog-labs/pup/blob/main/README.md

pup test が成功するまで続行しないでください。

2. 利用可能なコマンドを確認する

このセッションで利用可能なコマンドと使用パターンの全一覧を取得するため、pup agent guide を実行します。

pup agent guide

pup agent guide が利用できない場合（コマンドが見つからない場合）は、以下の既知のコマンドリファレンスを使用して続行します。

3. 分析

QUERY に基づいて、最も関連性の高い pup コマンドを判断します。すべてのコマンドで構造化出力を得るため、--output=json（デフォルト）を使用します。コマンドは順番に実行します。

時間範囲のルール — QUERY に曜日名（「today」「yesterday」）または暦上の範囲が含まれている場合は、UTC の暦日ではなく、ローカルの各日の境界を使って時間範囲を計算します。「today」と指定された場合は、現地時間の午前 0 時以降を意味します。そのため、現地時間の午前 11 時のイベントは、UTC では別の日付になっていても含まれます。

相対的な期間（「last 1h」「last 24h」）の場合は、pup の相対時間文字列をそのまま渡します：--from="1h"、--from="24h"。

曜日名の場合は、ローカルの各日の境界をエポック秒で計算し、--from／--to に渡します：

# Start of local today as epoch (Linux / macOS)
date -d "$(date +%Y-%m-%d) 00:00:00" +%s          # Linux
date -jf "%Y-%m-%d %H:%M:%S" "$(date +%Y-%m-%d) 00:00:00" +%s  # macOS
# Current time as epoch
date +%s
# Start of local yesterday
date -d "$(date -d yesterday +%Y-%m-%d) 00:00:00" +%s          # Linux
date -jf "%Y-%m-%d %H:%M:%S" "$(date -v-1d +%Y-%m-%d) 00:00:00" +%s  # macOS

SINCE と UNTIL が UTC ISO8601 形式で指定されている場合は、それぞれをエポック秒に変換し、QUERY から時間範囲を推測する代わりに、すべての --from／--to フラグに使用します。これにより、すべての Datadog クエリで他の PIR サブスキルとまったく同じ時間範囲を対象にできます：

# Linux
SINCE_EPOCH=$(date -d "2026-03-20T02:30:00Z" +%s)
UNTIL_EPOCH=$(date -d "2026-03-20T06:00:00Z" +%s)
# macOS
SINCE_EPOCH=$(date -jf "%Y-%m-%dT%H:%M:%SZ" "2026-03-20T02:30:00Z" +%s)
UNTIL_EPOCH=$(date -jf "%Y-%m-%dT%H:%M:%SZ" "2026-03-20T06:00:00Z" +%s)

SERVICE_HINT が指定されている場合は、クエリで優先します：

• モニターをフィルタリングする：pup monitors search --query="service:<SERVICE_HINT>"
• クエリ文字列に service:<SERVICE_HINT> を含めてログ検索の範囲を絞る
• まずそのサービスの APM トレースに注目する

一般的な分析パターン：

目的	コマンド
トリガーされた／アラート中のモニター	pup monitors list、pup monitors search --query="status:alert"
エラーログ	pup logs search --query="status:error" --from="1h"
メトリクスの傾向	pup metrics query --query="<metric>" --from="<window>"
アクティブなインシデント	pup incidents list
SLO の健全性	pup slos list、pup slos status <id>
APM サービスの健全性	pup apm services、pup apm dependencies
セキュリティシグナル	pup security signals list、pup security findings search
エラートラッキング	pup error-tracking issues search --query="<service>"
Synthetics の失敗	pup synthetics tests list
CI の失敗	pup cicd pipelines list、pup cicd events list

すべてのコマンドの出力形式はデフォルトで JSON です。--from、--to、--query、--tags などのフラグを使って対象範囲を絞り込みます。使用可能なフラグについては、pup <command> --help を参照してください。

4. レポート

レポート内のすべてのタイムスタンプには、UTC ではなく、現在のエージェントのローカルタイムゾーンを使用します（システムクロックから判定）。形式：2026-03-20 15:30 NZDT（タイムゾーン略称付き）。ユーザー向けのレポート欄では UTC を使用しないでください。これは API レスポンスから直接取得したタイムスタンプ（例：last_triggered、overall_state_modified、イベント時刻）も対象です。レポートに記載する前に、すべてのタイムスタンプを現地時間に変換してください。

Write ツールを使って、.datadog-analyser-tmp/report.md に構造化された分析結果を書き込みます：

1. 概要 — 全体的な健全性ステータスと主な調査結果
2. 詳細 — ドメイン別の調査結果（モニター、ログ、メトリクスなど）
3. 異常 — アラート中、劣化中、または通常と異なる状態
4. 推奨事項 — 推奨するフォローアップ対応

レポートの場所 .datadog-analyser-tmp/report.md をユーザーに伝えます。