Purpose

Use this skill when you need to query Datadog for observability data: searching logs, querying time-series metrics, aggregating log statistics, listing available metrics, or inspecting metric metadata. pup is a CLI wrapper around Datadog APIs.

When to use what

Metrics

• pup metrics query : Query time-series metric data with aggregation, filtering, and grouping. Primary command for metric analysis.

• pup metrics search : Same query syntax as query but uses the simpler v1 API. Use when you don't need v2 timeseries formula semantics.

• pup metrics list : Discover available metric names. Use with --filter to narrow by pattern.

• pup metrics metadata get : Read metadata (description, unit, type) for a specific metric.

• pup metrics tags list : List available tags for a specific metric.

Logs

• pup logs query : Query logs using the v2 API (recommended). Supports timezone and flexible sorting.

• pup logs search : Search logs using the v1 API. Simpler but less capable than query .

• pup logs list : List logs with basic filtering. Lightest-weight log retrieval.

• pup logs aggregate : Statistical analysis on logs -- count, avg, percentile, cardinality, grouped by field.

Core concepts

• Output format: Use -o table for human-readable output, -o json for machine-readable. Default is json .

• Time ranges: --from and --to accept relative values (1h , 30m , 7d , 1w , 1M ) or absolute unix timestamps. --to defaults to now .

• Metric query syntax: <aggregation>:<metric_name>{<filter>} [by {<group>}]

• Aggregations: avg , sum , min , max , count

• Filters: tag key-value pairs like {env:prod} , {host:web-} , or {} for all

• Grouping: by {service} , by {host,env}

• Log query syntax: Uses Datadog search syntax

• By field: status:error , service:web-app , host:i-*

• By attribute: @http.status_code:500 , @user.id:12345

• Boolean: AND , OR , NOT , negation with -status:info

• Phrase: "exact phrase"

• Wildcard: host:i-*

Recommended workflow

Investigating a metric

• Discover metrics: pup metrics list --filter="<pattern>" to find relevant metric names.

• Inspect metadata: pup metrics metadata get <metric> to understand unit and type.

• Check tags: pup metrics tags list <metric> to see available dimensions.

• Query data: pup metrics query --query="avg:<metric>{<filter>} by {<group>}" --from="1h"

Investigating logs

• Start broad: pup logs search --query="status:error" --from="1h" --limit=10 to see recent errors.

• Narrow down: Add filters like service:X AND @http.status_code:500 .

• Aggregate for patterns: pup logs aggregate --query="status:error" --from="1h" --compute="count" --group-by="service" to find which services are failing.

• Deep dive: pup logs query --query="service:failing-svc AND status:error" --from="1h" --limit=100 for full log details.

Important tips

• Prefer -o json when processing output programmatically; use -o table when presenting to users.

• For log searches, --limit defaults to 50 (max 1000 for search, configurable for query/list).

• Metric queries return time-series arrays with timestamps -- the data points are in the series field of the JSON output.

• Log aggregate --compute supports: count , avg(@field) , sum(@field) , min(@field) , max(@field) , cardinality(@field) , percentile(@field, N) .

• Use --group-by with aggregate to break down results by any log field or attribute.

• Time ranges are relative to now: 1h means "1 hour ago to now", 7d means "7 days ago to now".