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