
datadog-cli
Datadog CLI for debugging and triaging - search logs and APM traces, tail in real-time, trace requests, analyze patterns, compare periods, query metrics, and find slow spans
- version
- 0.2.0
- GitHub stars
- 5
Install
/plugin install datadog-cli@ctdio-datadogRun it inside Claude Code after adding the marketplace with /plugin marketplace add ctdio/datadog-cli.
Contents
Discovered from sourceSkills 1
Datadog CLI Reference
A CLI tool for AI agents to debug and triage using Datadog logs, metrics, and APM traces.
Setup
Running the CLI
# Via npx (no install needed)
npx @ctdio/datadog-cli <command>
# Via bunx
bunx @ctdio/datadog-cli <command>
# Or create an alias for convenience
alias datadog="npx @ctdio/datadog-cli"
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
For Non-US Datadog Sites
Use --site flag:
npx @ctdio/datadog-cli logs search --query "*" --site datadoghq.eu
Commands
Log Search
datadog logs search --query "<query>" [--from <time>] [--to <time>] [--limit <n>] [--sort <order>]
Examples:
datadog logs search --query "status:error" --from 1h
datadog logs search --query "service:api status:error @http.status_code:500" --from 1h
Live Tail (Real-time Streaming)
Stream logs as they arrive. Press Ctrl+C to stop.
datadog logs tail --query "<query>" [--interval <seconds>]
Examples:
datadog logs tail --query "status:error"
datadog logs tail --query "service:api" --interval 5
Trace Correlation
Find all logs for a distributed trace across services.
datadog logs trace --id "<trace-id>" [--from <time>] [--to <time>]
Example:
datadog logs trace --id "abc123def456" --from 24h
Log Context
Get logs before and after a specific timestamp to understand what happened.
datadog logs context --timestamp "<iso-timestamp>" [--before <time>] [--after <time>] [--service <svc>]
Examples:
datadog logs context --timestamp "2024-01-15T10:30:00Z" --before 5m --after 2m
datadog logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 10m
Error Summary
Quick breakdown of errors by service, type, and message.
datadog errors [--from <time>] [--to <time>] [--service <svc>]
Examples:
datadog errors --from 1h
datadog errors --service payment-api --from 24h
Period Comparison
Compare log counts between current period and previous period.
datadog logs compare --query "<query>" --period <time>
Examples:
datadog logs compare --query "status:error" --period 1h
datadog logs compare --query "service:api status:error" --period 6h
Log Patterns
Group similar log messages to find patterns (replaces UUIDs, numbers, etc.).
datadog logs patterns --query "<query>" [--from <time>] [--limit <n>]
Examples:
datadog logs patterns --query "status:error" --from 1h
datadog logs patterns --query "service:api" --from 6h --limit 1000
Service Discovery
List all services with recent log activity.
datadog services [--from <time>] [--to <time>]
Example:
datadog services --from 24h
Log Aggregation
datadog logs agg --query "<query>" --facet <facet> [--from <time>]
Common facets: status, service, host, @http.status_code, @error.kind
Examples:
datadog logs agg --query "*" --facet status --from 1h
datadog logs agg --query "status:error" --facet service --from 24h
Multiple Queries
Run multiple queries in parallel.
datadog logs multi --queries "name1:query1,name2:query2" [--from <time>]
Example:
datadog logs multi --queries "errors:status:error,warnings:status:warn" --from 1h
Metrics Query
datadog metrics query --query "<metrics-query>" [--from <time>] [--to <time>]
Query format: <aggregation>:<metric>{<tags>}
Examples:
datadog metrics query --query "avg:system.cpu.user{*}" --from 1h
datadog metrics query --query "avg:system.cpu.user{service:api}" --from 1h
datadog metrics query --query "sum:trace.http.request.errors{service:api}.as_count()" --from 1h
APM Traces & Spans
Span Search
Search APM spans/traces with query filters.
datadog spans search --query "<query>" [--from <time>] [--to <time>] [--limit <n>] [--min-duration <duration>]
Examples:
datadog spans search --query "env:prod service:api" --from 1h
datadog spans search --query "service:api" --min-duration 1s --from 1h # Slow requests
datadog spans search --query "resource_name:POST" --from 1h
Span Aggregation
Aggregate spans by facet.
datadog spans agg --query "<query>" --facet <facet> [--from <time>]
Common facets: service, resource_name, status, env, operation_name
Examples:
datadog spans agg --query "env:prod" --facet service --from 24h
datadog spans agg --query "service:api" --facet resource_name --from 1h
Trace Hierarchy View
View all spans in a trace with parent-child relationships.
datadog spans trace --id "<trace-id>" [--from <time>]
Example:
datadog spans trace --id "abc123def456" --from 24h
Span Error Summary
Get breakdown of span errors by service and resource.
datadog spans errors [--from <time>] [--service <svc>]
Examples:
datadog spans errors --from 1h
datadog spans errors --service api --from 24h
APM Service Discovery
List all services with APM trace activity.
datadog spans services [--from <time>]
Example:
datadog spans services --from 24h
Global Flags
| Flag | Description |
|---|---|
--pretty | Human-readable output with colors |
--output <file> | Export results to JSON file |
--site <site> | Datadog site (e.g., datadoghq.eu) |
Time Formats
- Relative:
30m,1h,6h,24h,7d - ISO 8601:
2024-01-15T10:30:00Z
Common Workflows
Incident Triage
# 1. Quick error overview (logs and spans)
datadog errors --from 1h
datadog spans errors --from 1h
# 2. Is this new? Compare to previous period
datadog logs compare --query "status:error" --period 1h
# 3. What patterns are we seeing?
datadog logs patterns --query "status:error" --from 1h
# 4. Narrow down by service
datadog logs search --query "status:error service:payment-api" --from 1h
# 5. Find slow requests
datadog spans search --query "service:api" --min-duration 1s --from 1h
# 6. Get context around a specific timestamp
datadog logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 5m --after 2m
# 7. Follow the distributed trace (logs and spans)
datadog logs trace --id "TRACE_ID"
datadog spans trace --id "TRACE_ID"
Real-time Debugging
# Stream errors as they happen
datadog logs tail --query "status:error"
# Watch specific service
datadog logs tail --query "service:api status:error"
Service Health Check
# List services
datadog services --from 24h
# Check error distribution
datadog logs agg --query "service:api" --facet status --from 1h
# Check CPU/memory
datadog metrics query --query "avg:system.cpu.user{service:api}" --from 1h
Export for Sharing
# Save search results
datadog logs search --query "status:error" --from 1h --output errors.json
# Save error summary
datadog errors --from 24h --output error-report.json
Datadog Query Syntax
| Operator | Example | Description |
|---|---|---|
AND | service:api status:error | Both conditions |
OR | status:error OR status:warn | Either condition |
- | -status:info | Exclude |
* | service:api-* | Wildcard |
>= <= | @http.status_code:>=400 | Numeric comparison |
[TO] | @duration:[1000 TO 5000] | Range |
Common Attributes
service- Service namestatus- Log level (error, warn, info, debug)host- Hostname@http.status_code- HTTP status code@error.kind- Error type@trace_id/@dd.trace_id- Trace ID
Commands 1
Datadog CLI Quick Reference
Requires
DD_API_KEYandDD_APP_KEYenvironment variables
Commands Overview
| Command | Purpose |
|---|---|
logs search | Search and filter logs |
logs agg | Aggregate logs by facet |
logs tail | Stream logs in real-time |
logs trace | Find logs for a trace ID |
logs context | Get logs around a timestamp |
logs patterns | Group similar log messages |
logs compare | Compare current vs previous period |
logs multi | Run multiple queries in parallel |
metrics query | Query timeseries metrics |
errors | Quick error summary |
services | List services with log activity |
Log Search
datadog logs search --query "<query>" --from <time> [--limit <n>] [--pretty]
Examples:
# All errors in last hour
datadog logs search --query "status:error" --from 1h --pretty
# Errors for a specific service
datadog logs search --query "service:api status:error" --from 1h --pretty
# HTTP 500 errors
datadog logs search --query "@http.status_code:500" --from 30m --pretty
# Errors containing specific text
datadog logs search --query "status:error connection refused" --from 1h --pretty
# Exclude certain services
datadog logs search --query "status:error -service:healthcheck" --from 1h --pretty
Log Aggregation
datadog logs agg --query "<query>" --facet <facet> --from <time> [--pretty]
Common facets: status, service, host, @http.status_code, @error.kind, @http.method
Examples:
# Count logs by status level
datadog logs agg --query "*" --facet status --from 1h --pretty
# Errors by service
datadog logs agg --query "status:error" --facet service --from 24h --pretty
# Requests by HTTP status code
datadog logs agg --query "service:api" --facet @http.status_code --from 1h --pretty
# Errors by error type
datadog logs agg --query "status:error" --facet @error.kind --from 6h --pretty
Live Tail (Real-time)
datadog logs tail --query "<query>" [--interval <seconds>] [--pretty]
Examples:
# Stream all errors
datadog logs tail --query "status:error" --pretty
# Watch specific service
datadog logs tail --query "service:payment-api" --pretty
# Watch with custom poll interval
datadog logs tail --query "status:error" --interval 5 --pretty
Trace Correlation
datadog logs trace --id "<trace-id>" [--from <time>] [--pretty]
Example:
datadog logs trace --id "abc123def456789" --from 24h --pretty
Log Context
Get logs before/after a specific timestamp to understand what happened.
datadog logs context --timestamp "<iso-timestamp>" [--service <svc>] [--before <time>] [--after <time>] [--pretty]
Examples:
# 5 minutes before/after a timestamp
datadog logs context --timestamp "2024-01-15T10:30:00Z" --pretty
# Focused on one service
datadog logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 10m --after 5m --pretty
Error Summary
datadog errors [--from <time>] [--service <svc>] [--pretty]
Examples:
# All errors in last hour
datadog errors --from 1h --pretty
# Errors for specific service
datadog errors --service payment-api --from 24h --pretty
Log Patterns
Group similar messages (replaces UUIDs, numbers, IPs with placeholders).
datadog logs patterns --query "<query>" --from <time> [--limit <n>] [--pretty]
Examples:
# Find error patterns
datadog logs patterns --query "status:error" --from 1h --pretty
# Patterns for a service
datadog logs patterns --query "service:api" --from 6h --limit 500 --pretty
Period Comparison
Compare log counts: current period vs previous period.
datadog logs compare --query "<query>" --period <time> [--pretty]
Examples:
# Are errors increasing? Compare last hour to hour before
datadog logs compare --query "status:error" --period 1h --pretty
# Compare 500 errors over 6 hour periods
datadog logs compare --query "@http.status_code:500" --period 6h --pretty
Multiple Queries
Run several queries in parallel.
datadog logs multi --queries "name1:query1,name2:query2" --from <time> [--pretty]
Examples:
# Errors vs warnings
datadog logs multi --queries "errors:status:error,warnings:status:warn" --from 1h --pretty
# Multiple services
datadog logs multi --queries "api:service:api,db:service:database,cache:service:redis" --from 1h --pretty
Service Discovery
datadog services --from <time> [--pretty]
Example:
datadog services --from 24h --pretty
Metrics Query
datadog metrics query --query "<aggregation>:<metric>{<tags>}" --from <time> [--pretty]
Aggregations: avg, sum, min, max, count
Examples:
# CPU usage across all hosts
datadog metrics query --query "avg:system.cpu.user{*}" --from 1h --pretty
# CPU for specific service
datadog metrics query --query "avg:system.cpu.user{service:api}" --from 1h --pretty
# Memory usage
datadog metrics query --query "avg:system.mem.used{*}" --from 1h --pretty
# Request count
datadog metrics query --query "sum:trace.http.request.hits{service:api}.as_count()" --from 1h --pretty
# Error rate
datadog metrics query --query "sum:trace.http.request.errors{service:api}.as_count()" --from 1h --pretty
Query Syntax
| Operator | Example | Description |
|---|---|---|
| implicit AND | service:api status:error | Both conditions |
OR | status:error OR status:warn | Either condition |
- (NOT) | -service:healthcheck | Exclude matches |
* wildcard | service:api-* | Prefix/suffix match |
>= <= > < | @http.status_code:>=400 | Numeric comparison |
[TO] range | @duration:[1000 TO 5000] | Numeric range |
"" exact | "connection refused" | Exact phrase |
Common Log Attributes
| Attribute | Description |
|---|---|
status | Log level: error, warn, info, debug |
service | Service name |
host | Hostname |
@http.status_code | HTTP response code |
@http.method | GET, POST, PUT, DELETE, etc. |
@http.url | Request URL |
@error.kind | Error type/class |
@error.message | Error message |
@trace_id | Distributed trace ID |
@duration | Request duration (nanoseconds) |
Time Formats
- Relative:
30m,1h,6h,24h,7d - ISO 8601:
2024-01-15T10:30:00Z
Global Flags
| Flag | Description |
|---|---|
--pretty | Human-readable colored output |
--output <file> | Export results to JSON file |
--site <site> | Datadog site (e.g., datadoghq.eu, us5.datadoghq.com) |
Common Workflows
Incident Triage
datadog errors --from 1h --pretty # Overview
datadog logs compare --query "status:error" --period 1h --pretty # Is this new?
datadog logs patterns --query "status:error" --from 1h --pretty # What patterns?
datadog logs search --query "status:error service:api" --from 1h --pretty # Drill down
datadog logs trace --id "TRACE_ID" --pretty # Follow trace
Real-time Monitoring
datadog logs tail --query "status:error" --pretty
Export for Analysis
datadog logs search --query "status:error" --from 24h --limit 1000 --output errors.json
Sponsors
Details
- Marketplace
- ctdio/datadog-cli
- Category
- Community