agent-datadog

Token-efficient Datadog CLI for AI agents. Single Rust binary, ~3 MB, zero runtime dependencies.

Guiding principles:

• token-efficient output by default — dense one-line-per-record format so LLMs can consume results cheaply
• just paste the URL — hand the CLI any Datadog link (logs, monitors, traces, dashboards) and it does the right thing
• zero config beyond credentials — three env vars and you're running

Getting started

npm install -g agent-datadog

Or use directly with npx:

npx agent-datadog log search --query "status:error" --from now-15m

curl -fsSL https://raw.githubusercontent.com/indent-com/agent-clis/main/scripts/install.sh | bash

Or a specific version:

curl -fsSL https://raw.githubusercontent.com/indent-com/agent-clis/main/scripts/install.sh | bash -s v0.1.0

git clone https://github.com/indent-com/agent-clis
cd agent-clis
cargo install --path agent-datadog

At a glance

• URL — paste any Datadog link and get the data behind it
• Logs — search logs, fetch full log details by ID, aggregate with analytics
• Spans — search spans or fetch an entire trace
• Monitors — list, inspect, mute, unmute
• Dashboards — list and inspect dashboard definitions
• Metrics — query time-series with summary stats, file export, graph snapshots, search names, inspect metadata

Authentication

Three environment variables, all required. Both DD_* and DATADOG_* prefixes are accepted (DD_* takes precedence):

export DD_API_KEY="..."        # or DATADOG_API_KEY
export DD_APP_KEY="..."        # or DATADOG_APP_KEY
export DD_SITE="us5.datadoghq.com"   # or DATADOG_SITE

Command map

agent-datadog
├── url <URL>                                  # investigate any Datadog link
├── log
│   ├── search --query <query>                  # search logs (--from, --to, --limit, --sort, --page-cursor)
│   ├── get    <id>                            # full log detail by ID (no truncation)
│   └── stats  --query <query> --compute <agg>  # aggregate logs (--group-by, --from, --to)
├── span
│   ├── search --query <query>                  # search spans (--from, --to, --limit, --page-cursor)
│   └── trace  <id>                            # all spans for a trace (--from, --to, --limit)
├── monitor
│   ├── list                                   # list monitors (--state, --tag)
│   ├── get    <id>                            # monitor detail + group states
│   ├── mute   <id>                            # mute (--end <epoch>)
│   └── unmute <id>                            # unmute
├── dashboard
│   ├── list                                   # list dashboards
│   └── get    <id>                            # dashboard detail
└── metric
    ├── query    --query <query>                # query metrics (--from, --to, --output)
    ├── snapshot --query <query>                # graph snapshot PNG (--from, --to, --viz, --output)
    ├── search   --prefix <prefix>               # search metric names
    └── get      <metric>                      # metadata, type, unit, tags, percentiles

Quick start

# Paste a Datadog URL — logs, monitors, traces, or dashboards
agent-datadog url "https://us5.datadoghq.com/logs?query=status%3Aerror&from_ts=...&to_ts=..."

# Search logs
agent-datadog log search --query "status:error service:api" --limit 20

# Fetch full details for a specific log (no truncation)
agent-datadog log get "AwAAAZyMZ_T8..."

# Aggregate logs — count errors by service
agent-datadog log stats --query "status:error" --compute count --group-by service

# Aggregate logs — average duration by resource
agent-datadog log stats --query "*" --compute "avg:@duration" --group-by resource_name

# Search spans
agent-datadog span search --query "env:prod service:api" --from now-2h --limit 10

# Fetch a full trace
agent-datadog span trace "TRACE_ID" --from now-6h

# List alerting monitors
agent-datadog monitor list --state Alert

# Query metrics (summary)
agent-datadog metric query --query "avg:system.cpu.user{*}"

# Save timeseries data to CSV for analysis
agent-datadog metric query --query "avg:system.cpu.user{*}" --from now-4h --output /tmp/cpu.csv

# Save timeseries data to JSON
agent-datadog metric query --query "avg:system.cpu.user{*}" --from now-4h --output /tmp/cpu.json

# Stream timeseries CSV to stdout
agent-datadog metric query --query "avg:system.cpu.user{*}" --from now-4h --output -

# Generate a graph snapshot (timeseries PNG)
agent-datadog metric snapshot --query "avg:system.cpu.user{*}" --from now-4h

# Generate a heatmap snapshot
agent-datadog metric snapshot --query "avg:system.cpu.user{*}" --from now-4h --viz heatmap --output /tmp/heatmap.png

# Search for metric names
agent-datadog metric search --prefix "system.cpu"

# Get metric details (type, unit, percentile config, tags)
agent-datadog metric get "system.cpu.user"

Investigating a Datadog URL

The fastest way to investigate a Datadog link. Supports logs, monitors, traces, and dashboards:

agent-datadog url "https://us5.datadoghq.com/logs?query=status%3Aerror&from_ts=...&to_ts=..."
agent-datadog url "https://us5.datadoghq.com/monitors/17029590?group=..."
agent-datadog url "https://us5.datadoghq.com/apm/traces/TRACE_ID"
agent-datadog url "https://us5.datadoghq.com/dashboard/DASH_ID/title"

For monitor URLs, the CLI automatically:

1. Fetches the monitor details
2. Extracts the log query from the monitor's query field
3. Combines it with the group filter from the URL
4. Searches matching logs in the time window

Output formats

Every command supports a global --format (-f) flag:

| Format | Flag | Description | |--------|------|-------------| | Text | -f text (default) | Dense one-line-per-record, optimized for token efficiency | | JSON | -f json | Machine-readable, pipeable to jq |

agent-datadog -f json log search --query "status:error" | jq '.logs[].message'

Errors are always rendered to stderr as YAML with error and hint fields, regardless of output format.

Time formats

All --from and --to flags accept:

| Format | Example | |--------|---------| | Relative | now, now-15m, now-1h, now-2d, now-30s | | ISO 8601 | 2026-01-15T00:00:00Z |

Architecture

See ARCHITECTURE.md for the full module layout, data flow, testing strategy, and conventions.