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-datadog

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ctdio/datadog-cli.

Contents

Discovered from source

Skills 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

FlagDescription
--prettyHuman-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

OperatorExampleDescription
ANDservice:api status:errorBoth conditions
ORstatus:error OR status:warnEither condition
--status:infoExclude
*service:api-*Wildcard
>= <=@http.status_code:>=400Numeric comparison
[TO]@duration:[1000 TO 5000]Range

Common Attributes

  • service - Service name
  • status - 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_KEY and DD_APP_KEY environment variables

Commands Overview

CommandPurpose
logs searchSearch and filter logs
logs aggAggregate logs by facet
logs tailStream logs in real-time
logs traceFind logs for a trace ID
logs contextGet logs around a timestamp
logs patternsGroup similar log messages
logs compareCompare current vs previous period
logs multiRun multiple queries in parallel
metrics queryQuery timeseries metrics
errorsQuick error summary
servicesList 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

OperatorExampleDescription
implicit ANDservice:api status:errorBoth conditions
ORstatus:error OR status:warnEither condition
- (NOT)-service:healthcheckExclude matches
* wildcardservice:api-*Prefix/suffix match
>= <= > <@http.status_code:>=400Numeric comparison
[TO] range@duration:[1000 TO 5000]Numeric range
"" exact"connection refused"Exact phrase

Common Log Attributes

AttributeDescription
statusLog level: error, warn, info, debug
serviceService name
hostHostname
@http.status_codeHTTP response code
@http.methodGET, POST, PUT, DELETE, etc.
@http.urlRequest URL
@error.kindError type/class
@error.messageError message
@trace_idDistributed trace ID
@durationRequest duration (nanoseconds)

Time Formats

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

Global Flags

FlagDescription
--prettyHuman-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