Datadog Analyser

Investigate and analyse Datadog observability data using the pup CLI.

Inputs

Raw arguments: $ARGUMENTS

Infer from the arguments:

QUERY: what to analyse. Use current agent's local timezone (detect via system clock) for any time-based queries, not UTC.

System Requirements

pup CLI installed — see https://github.com/datadog-labs/pup/blob/main/README.md
DD_API_KEY and DD_APP_KEY environment variables set. Important: When checking these variables, verify at least 2 times before concluding they are not set. Environment variables can appear unset due to shell context differences. Never expose the values — use existence checks only (e.g. test -n "$DD_API_KEY").
DD_SITE set if not using datadoghq.com (optional)

Output Directory

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

Execution

1. Verify Connection

Run pup test to confirm the CLI is configured and connected:

pup test

If this fails, use AskUserQuestion to inform the user that pup is not configured or DD_API_KEY/DD_APP_KEY are not set, and link to the setup guide: https://github.com/datadog-labs/pup/blob/main/README.md

Do NOT continue until pup test succeeds.

2. Discover Available Commands

Run pup agent guide to get the full list of available commands and usage patterns for this session:

pup agent guide

If pup agent guide is not available (command not found), use the known command reference below and continue.

3. Analyse

Based on QUERY, determine which pup commands are most relevant. Use --output=json (default) for all commands to get structured output. Run commands sequentially.

Common analysis patterns:

| Goal | Commands | |------|----------| | Triggered/alerting monitors | pup monitors list, pup monitors search --query="status:alert" | | Error logs | pup logs search --query="status:error" --from="1h" | | Metric trend | pup metrics query --query="<metric>" --from="<window>" | | Active incidents | pup incidents list | | SLO health | pup slos list, pup slos status <id> | | APM service health | pup apm services, pup apm dependencies | | Security signals | pup security signals list, pup security findings search | | Error tracking | pup error-tracking issues search --query="<service>" | | Synthetics failures | pup synthetics tests list | | CI failures | pup cicd pipelines list, pup cicd events list |

All commands default to JSON output. Use flags like --from, --to, --query, --tags to narrow scope. Refer to pup <command> --help for available flags.

4. Report

All timestamps in the report must use current agent's local timezone (detect via system clock), not UTC.

Write a structured analysis to .datadog-analyser-tmp/report.md using the Write tool:

Summary — Overall health status and key findings
Details — Breakdown of findings per domain (monitors, logs, metrics, etc.)
Anomalies — Anything alerting, degraded, or unusual
Recommendations — Suggested follow-up actions

Inform the user of the report location: .datadog-analyser-tmp/report.md