Datadog Cli

Datadog CLI

A CLI tool for AI agents to debug and triage using Datadog logs and metrics.

Required Reading

You MUST read the relevant reference docs before using any command:

• Log Commands
• Metrics
• Query Syntax
• Workflows
• Dashboards

Setup

Environment Variables (Required)

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

Get keys from: https://app.datadoghq.com/organization-settings/api-keys

Running the CLI

npx @leoflores/datadog-cli <command>

For non-US Datadog sites, use --site flag:

npx @leoflores/datadog-cli logs search --query "*" --site datadoghq.eu

Commands Overview

Quick Examples

Search Errors

npx @leoflores/datadog-cli logs search --query "status:error" --from 1h --pretty

Tail Logs (Real-time)

npx @leoflores/datadog-cli logs tail --query "service:api status:error" --pretty

Error Summary

npx @leoflores/datadog-cli errors --from 1h --pretty

Trace Correlation

npx @leoflores/datadog-cli logs trace --id "abc123def456" --pretty

Query Metrics

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{*}" --from 1h --pretty

Compare Periods

npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty

Global Flags

Time Formats

• Relative: 30m, 1h, 6h, 24h, 7d
• ISO 8601: 2024-01-15T10:30:00Z

Incident Triage Workflow

# 1. Quick error overview
npx @leoflores/datadog-cli errors --from 1h --pretty

# 2. Is this new? Compare to previous period
npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty

# 3. Find error patterns
npx @leoflores/datadog-cli logs patterns --query "status:error" --from 1h --pretty

# 4. Narrow down by service
npx @leoflores/datadog-cli logs search --query "status:error service:api" --from 1h --pretty

# 5. Get context around a timestamp
npx @leoflores/datadog-cli logs context --timestamp "2024-01-15T10:30:00Z" --service api --pretty

# 6. Follow the distributed trace
npx @leoflores/datadog-cli logs trace --id "TRACE_ID" --pretty

See workflows.md for more debugging workflows.

datadog Plugin

A Claude Code skill for debugging and triaging with Datadog logs, metrics, and dashboards.

What it does

This skill enables Claude to use the datadog CLI for:

• Log search - Query and filter logs with Datadog syntax
• Real-time tailing - Stream logs as they arrive
• Trace analysis - Follow distributed requests across services
• Pattern detection - Group similar log messages automatically
• Metrics query - Query timeseries metrics with PromQL-style syntax
• Dashboard management - List, create, update, and delete dashboards

Prerequisites

1. Install the CLI from leonardocouy/datadog-cli

2. Set environment variables:

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

Get keys from: https://app.datadoghq.com/organization-settings/api-keys

Installation

/plugin marketplace add leonardocouy/cc-datadog
/plugin install datadog@cc-datadog

Usage

Once installed, Claude will automatically use datadog commands when you ask questions like:

• "Search for error logs in the last hour"
• "Tail logs from the payments service"
• "Trace this request ID across services"
• "Show me error patterns from today"
• "What dashboards do we have?"
• "Please explain this Datadog dashboard https://app.datadoghq.com/dashboard/xxx-xxx-xxx"
• "Create a new Datadog dashboard for the metrics cpu.usage, memory.used"

Commands Reference

See the datadog-cli repository for complete command documentation.

License

MIT

Dashboards Reference

⚠️ CRITICAL: Dashboard Update is DESTRUCTIVE

The `dashboards update` command REPLACES the entire dashboard, not just the fields you specify.

If you omit any of these fields during an update, they will be permanently deleted:

• --template-variables → Template variables will be removed
• --description → Description will be cleared
• --notify-list → Notify list will be cleared

Example of DATA LOSS:

# This will DELETE template variables and description!
npx @leoflores/datadog-cli dashboards update \
  --id "abc-def-ghi" \
  --title "My Dashboard" \
  --layout ordered \
  --widgets '[...]'  # Only widgets provided, other fields wiped!

Safe Dashboard Update Workflow

ALWAYS follow this 3-step process when updating dashboards:

⚠️ Important: Always use --output to save to a temp file instead of capturing output in a bash variable. JSON with special characters, newlines, or ANSI codes can break jq parsing when piped through echo.

Step 1: Backup the Current Dashboard to a Temp File

# Save the current dashboard state BEFORE any changes
# Using --output ensures clean JSON without encoding issues
npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --output /tmp/dashboard.json

Step 2: Modify and Preserve All Fields

# Extract existing values directly from the file (not through echo!)
TEMPLATE_VARS=$(jq -c '.dashboard.templateVariables // []' /tmp/dashboard.json)
DESCRIPTION=$(jq -r '.dashboard.description // ""' /tmp/dashboard.json)

# Modify widgets (example: change title of widget at index 1)
WIDGETS=$(jq -c '.dashboard.widgets | .[1].definition.title = "New Title"' /tmp/dashboard.json)

# Update with ALL fields preserved
npx @leoflores/datadog-cli dashboards update \
  --id "abc-def-ghi" \
  --title "My Dashboard" \
  --layout ordered \
  --widgets "$WIDGETS" \
  --description "$DESCRIPTION" \
  --template-variables "$TEMPLATE_VARS" \
  --pretty

Step 3: Verify the Update

# Confirm all fields are intact
npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --pretty

Recovery from Accidental Data Loss

# If you have a backup file, restore from it
WIDGETS=$(jq -c '.dashboard.widgets' /tmp/dashboard.json)
TEMPLATE_VARS=$(jq -c '.dashboard.templateVariables // []' /tmp/dashboard.json)
DESCRIPTION=$(jq -r '.dashboard.description // ""' /tmp/dashboard.json)
TITLE=$(jq -r '.dashboard.title' /tmp/dashboard.json)
LAYOUT=$(jq -r '.dashboard.layoutType' /tmp/dashboard.json)

npx @leoflores/datadog-cli dashboards update \
  --id "abc-def-ghi" \
  --title "$TITLE" \
  --layout "$LAYOUT" \
  --widgets "$WIDGETS" \
  --description "$DESCRIPTION" \
  --template-variables "$TEMPLATE_VARS" \
  --pretty

Why Use Files Instead of Variables?

❌ Don't do this - prone to parsing errors:

DASHBOARD_JSON=$(npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi")
WIDGETS=$(echo "$DASHBOARD_JSON" | jq -c '.dashboard.widgets')  # May fail!

✅ Do this - reliable with any JSON content:

npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --output /tmp/dashboard.json
WIDGETS=$(jq -c '.dashboard.widgets' /tmp/dashboard.json)  # Always works

Commands Overview

Dashboard Flags

Examples

List & Get

npx @leoflores/datadog-cli dashboards list --pretty
npx @leoflores/datadog-cli dashboards get --id "abc-def-ghi" --pretty

Create Dashboard

npx @leoflores/datadog-cli dashboards create \
  --title "API Monitoring" \
  --layout ordered \
  --widgets '[{"definition":{"type":"timeseries","requests":[{"q":"avg:system.cpu.user{*}"}]}}]' \
  --pretty

With Template Variables

npx @leoflores/datadog-cli dashboards create \
  --title "Service Dashboard" \
  --layout ordered \
  --template-variables '[{"name":"env","prefix":"env","default":"prod"},{"name":"service","prefix":"service","default":"*"}]' \
  --widgets '[{"definition":{"type":"timeseries","requests":[{"q":"avg:system.cpu.user{$env,$service}"}]}}]' \
  --pretty

Using Stdin

cat widgets.json | npx @leoflores/datadog-cli dashboards create --title "My Dashboard" --layout ordered --pretty

Template Variables

{"name": "env", "prefix": "env", "default": "prod"}

Use in queries: avg:system.cpu.user{$env,$service}

Widget Types

Timeseries

{"definition": {"type": "timeseries", "title": "CPU", "requests": [{"q": "avg:system.cpu.user{*}"}]}}

Query Value

{"definition": {"type": "query_value", "title": "Errors", "requests": [{"q": "sum:errors{*}.as_count()"}]}}

Top List

{"definition": {"type": "toplist", "title": "Top Services", "requests": [{"q": "top(sum:errors{*} by {service}, 10, 'sum', 'desc')"}]}}

Layout Types

• ordered: Auto-arranged responsive grid
• free: Manual positioning with x, y, width, height

Dashboard Lists

# List all
npx @leoflores/datadog-cli dashboard-lists list --pretty

# Add dashboards to list
npx @leoflores/datadog-cli dashboard-lists add-items --id 123 \
  --dashboards '[{"type":"custom_timeboard","id":"abc-def-ghi"}]' --pretty

Log Commands Reference

logs search

Search logs with filters.

npx @leoflores/datadog-cli logs search --query "<query>" [--from <time>] [--to <time>] [--limit <n>] [--sort <order>]

npx @leoflores/datadog-cli logs search --query "service:api status:error" --from 1h --pretty

logs tail

Stream logs in real-time. Press Ctrl+C to stop.

npx @leoflores/datadog-cli logs tail --query "<query>" [--interval <seconds>]

npx @leoflores/datadog-cli logs tail --query "status:error" --pretty

logs trace

Find all logs for a distributed trace across services.

npx @leoflores/datadog-cli logs trace --id "<trace-id>" [--from <time>] [--to <time>]

Searches both @trace_id and @dd.trace_id attributes.

npx @leoflores/datadog-cli logs trace --id "abc123def456" --from 24h --pretty

logs context

Get logs before and after a specific timestamp.

npx @leoflores/datadog-cli logs context --timestamp "<iso-timestamp>" [--before <time>] [--after <time>] [--service <svc>]

npx @leoflores/datadog-cli logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 5m --after 2m --pretty

logs patterns

Group similar log messages to find patterns. Replaces UUIDs, numbers, IPs, etc.

npx @leoflores/datadog-cli logs patterns --query "<query>" [--from <time>] [--limit <n>]

Returns top 50 patterns with counts and sample messages.

npx @leoflores/datadog-cli logs patterns --query "status:error" --from 1h --pretty

logs compare

Compare log counts between current period and previous period.

npx @leoflores/datadog-cli logs compare --query "<query>" --period <time>

Shows absolute and percentage change with directional arrows.

npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty

logs multi

Run multiple queries in parallel.

npx @leoflores/datadog-cli logs multi --queries "name1:query1,name2:query2" [--from <time>]

npx @leoflores/datadog-cli logs multi --queries "errors:status:error,warnings:status:warn" --from 1h --pretty

logs agg

Aggregate logs by facet.

npx @leoflores/datadog-cli logs agg --query "<query>" --facet <facet> [--from <time>]

Common facets: status, service, host, @http.status_code, @error.kind

npx @leoflores/datadog-cli logs agg --query "*" --facet status --from 1h --pretty

Metrics Reference

metrics query

Query timeseries metrics from Datadog.

npx @leoflores/datadog-cli metrics query --query "<metrics-query>" [--from <time>] [--to <time>]

Query Format

<aggregation>:<metric>{<tags>}

Aggregations: avg, sum, min, max, count

Examples

System Metrics

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{*}" --from 1h --pretty
npx @leoflores/datadog-cli metrics query --query "avg:system.mem.used{*}" --from 1h --pretty

Service-Specific

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{service:api}" --from 1h --pretty

APM Metrics

npx @leoflores/datadog-cli metrics query --query "sum:trace.http.request.errors{service:api}.as_count()" --from 1h --pretty
npx @leoflores/datadog-cli metrics query --query "p99:trace.http.request.duration{service:api}" --from 1h --pretty

With Tags

npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{env:prod,service:api}" --from 1h --pretty

Output

Returns series with:

• Metric name and scope
• Point list (timestamp/value pairs)
• Tags
• Latest value + min/max/avg stats

Datadog Query Syntax

Operators

Common Attributes

Time Formats

Relative

• 1m - 1 minute
• 30m - 30 minutes
• 1h - 1 hour
• 6h - 6 hours
• 24h - 24 hours
• 7d - 7 days

Absolute

• ISO 8601: 2024-01-15T10:30:00Z

Example Queries

# All errors
status:error

# Errors in specific service
service:api status:error

# 5xx HTTP errors
@http.status_code:>=500

# Exclude info logs
-status:info

# Multiple services
service:api OR service:payment

# Timeout errors
error:timeout OR @error.kind:TimeoutError

# Slow requests (>1s)
@duration:>=1000

Common Workflows

Incident Triage

Step-by-step workflow for investigating production issues.

# 1. Quick error overview
npx @leoflores/datadog-cli errors --from 1h --pretty

# 2. Is this new? Compare to previous period
npx @leoflores/datadog-cli logs compare --query "status:error" --period 1h --pretty

# 3. Find error patterns
npx @leoflores/datadog-cli logs patterns --query "status:error" --from 1h --pretty

# 4. Narrow down by service
npx @leoflores/datadog-cli logs search --query "status:error service:payment-api" --from 1h --pretty

# 5. Get context around a specific timestamp
npx @leoflores/datadog-cli logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 5m --after 2m --pretty

# 6. Follow the distributed trace
npx @leoflores/datadog-cli logs trace --id "TRACE_ID" --pretty

Real-time Debugging

Monitor logs as they arrive.

# Stream all errors
npx @leoflores/datadog-cli logs tail --query "status:error" --pretty

# Watch specific service
npx @leoflores/datadog-cli logs tail --query "service:api status:error" --pretty

# Monitor deployments
npx @leoflores/datadog-cli logs tail --query "service:deploy" --pretty

Service Health Check

Assess overall service health.

# List all services
npx @leoflores/datadog-cli services --from 24h --pretty

# Check error distribution for a service
npx @leoflores/datadog-cli logs agg --query "service:api" --facet status --from 1h --pretty

# Check CPU/memory usage
npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{service:api}" --from 1h --pretty
npx @leoflores/datadog-cli metrics query --query "avg:system.mem.used{service:api}" --from 1h --pretty

# Error summary for service
npx @leoflores/datadog-cli errors --service api --from 24h --pretty

Export for Sharing

Save results to files for reports or sharing.

# Save search results
npx @leoflores/datadog-cli logs search --query "status:error" --from 1h --output errors.json --pretty

# Save error summary
npx @leoflores/datadog-cli errors --from 24h --output error-report.json --pretty

# Save metrics data
npx @leoflores/datadog-cli metrics query --query "avg:system.cpu.user{*}" --from 24h --output cpu-metrics.json --pretty

Multi-Query Investigation

Run parallel queries for comprehensive view.

# Compare error types across services
npx @leoflores/datadog-cli logs multi \
  --queries "api-errors:service:api status:error,payment-errors:service:payment status:error,auth-errors:service:auth status:error" \
  --from 1h --pretty

⚠️ Safe Dashboard Update

CRITICAL: Dashboard updates are destructive and replace the entire dashboard.

Follow the Safe Dashboard Update Workflow in dashboards.md to avoid data loss.