datadog-cli
用于调试和分类的 Datadog CLI。当您需要:搜索 Datadog 日志、查询指标、实时尾部日志、跟踪分布式请求、调查错误、比较时间段、查找日志模式、检查服务运行状况或导出可观测性数据时,请使用此技能。触发短语包括“搜索日志”、“尾部日志”、“查询指标”、“检查 Datadog”、“查找错误”、“跟踪请求”、“比较错误”、“存在哪些服务”、“日志模式”、“CPU 使用情况”、“服务运行状况”。
name: datadog-cli description: | Datadog CLI for debugging and triaging. Use this skill when you need to: search Datadog logs, query metrics, tail logs in real-time, trace distributed requests, investigate errors, compare time periods, find log patterns, check service health, or export observability data. Trigger phrases include "search logs", "tail logs", "query metrics", "check Datadog", "find errors", "trace request", "compare errors", "what services exist", "log patterns", "CPU usage", "service health".
Datadog CLI Reference
A CLI tool for AI agents to debug and triage using Datadog logs and metrics.
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
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
datadog 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. Get context around a specific timestamp
datadog logs context --timestamp "2024-01-15T10:30:00Z" --service api --before 5m --after 2m
# 6. Follow the distributed trace
datadog logs 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