obz-dd: Datadog Provider

Quick Reference

Field	Value
Aliases	dd, datadog
Signals	Metric, Log, Trace
Metric query	Datadog Query Language
Log query	Datadog Log Query
Auth	API key + Application key (both required)
Default endpoint	https://api.datadoghq.com

Supported Commands

Signal	Commands	Not Supported
Metric	query, list, info	labels, label-values, series
Log	search, aggregate
Trace	search, get, aggregate

Datadog's API doesn't expose label/series enumeration endpoints, so those three metric commands are unavailable.

Extension commands

obz log aggregate    # Aggregate logs (requires --query, optional --compute, --group-by, both repeatable)
obz trace aggregate  # Aggregate traces (same flags as log aggregate)

Authentication

Datadog requires two keys for every request. Configure them in config.yaml under providers.<name>.auth:

# config.yaml
providers:
  dd:
    endpoint: https://api.datadoghq.com
    auth:
      api-key: ${env:DD_API_KEY}
      app-key: ${env:DD_APP_KEY}

Then query with just -p:

obz metric query -p dd -q 'avg:system.cpu.user{*}' --from now-1h

Regional Endpoints

Datadog operates multiple regional sites. Set --endpoint to the correct one:

Region	Endpoint
US1 (default)	https://api.datadoghq.com
US3	https://api.us3.datadoghq.com
US5	https://api.us5.datadoghq.com
EU	https://api.datadoghq.eu
AP1	https://api.ap1.datadoghq.com

If --endpoint is omitted, the default US1 endpoint is used.

Config File Setup

# ~/.config/obz/config.yaml
providers:
  dd-prod:
    provider: dd
    endpoint: https://api.datadoghq.com
    auth:
      api-key: ${env:DD_API_KEY}
      app-key: ${env:DD_APP_KEY}

Then:

obz metric query -p dd-prod -q 'avg:system.cpu.user{*}' --from now-1h

Datadog Query Language (Metrics)

Datadog metric queries follow the pattern:

<aggregation>:<metric_name>{<filter>}

Aggregation Functions

avg, sum, min, max, count

Tag Filters

Tags go inside curly braces, comma-separated:

avg:system.cpu.user{host:web-01}
sum:http.requests{service:api, env:prod}
avg:system.mem.used{*}

The wildcard {*} matches all hosts/tags.

Arithmetic and Functions

avg:system.cpu.user{*} + avg:system.cpu.system{*}
avg:system.cpu.user{*}.rollup(avg, 300)
per_second(sum:http.requests{*})

Space Aggregation (by/as)

avg:system.cpu.user{*} by {host}
sum:http.requests{*} by {service, env}

Common Pitfalls

• The aggregation prefix (avg:, sum:, etc.) is required. Bare metric names like system.cpu.user{*} will fail.
• Tag values don't use quotes: {host:web-01} not {host:"web-01"}.
• Datadog queries are NOT PromQL. Don't use rate() or [5m] syntax.
• .rollup() controls time aggregation. Without it, Datadog picks automatic rollup intervals.

Datadog Log Query (Logs)

Datadog log queries filter on facets and tags.

Basic Syntax

service:web
status:error
service:web status:error

Multiple terms are AND-ed by default.

Field Queries

@http.status_code:500
@duration:>1000
host:web-01

Prefixed @ fields are log attributes. Unprefixed fields are reserved tags (service, status, host, source).

Boolean and Grouping

service:web AND (status:error OR status:warn)
service:web NOT @http.url:"/health"

Wildcards

service:web-*
@http.url:"/api/*"

Common Pitfalls

• Reserved tags (service, status, host, source) don't take the @ prefix. Custom attributes do.
• String values with special characters need quotes: @http.url:"/api/v1/users".
• The default combiner is AND. Explicit OR requires parentheses for correct grouping.

Examples

Metric query:

obz metric query -p dd -q 'avg:system.cpu.user{*}' --from now-1h

Metric query with tag filter and grouping:

obz metric query -p dd-prod \
  -q 'avg:system.cpu.user{env:prod} by {host}' --from now-6h

List available metrics:

obz metric list -p dd-prod

Get metric metadata:

obz metric info -p dd-prod system.cpu.user

Log search:

obz log search -p dd -q 'service:web status:error' --from now-1h

Log search with attribute filter (pre-configured):

obz log search -p dd-prod \
  -q 'service:api @http.status_code:500' --from now-30m

Trace search:

obz trace search -p dd-prod -q 'service:api' --from now-1h

Get a specific trace:

obz trace get -p dd-prod abc123def456

Aggregate log counts by service:

obz log aggregate -p dd -q 'status:error' --compute count --group-by service --from now-1h

Aggregate trace durations:

obz trace aggregate -p dd -q 'service:api' --compute 'avg:@duration' --group-by resource_name --from now-1h

EU region endpoint (set endpoint in config or override with --endpoint):

obz metric query -p dd --endpoint https://api.datadoghq.eu \
  -q 'avg:system.cpu.user{*}' --from now-1h