pup

What this skill does

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

1. Discover metrics: `pup metrics list --filter="<pattern>"` to find relevant metric names.
2. Inspect metadata: `pup metrics metadata get <metric>` to understand unit and type.
3. Check tags: `pup metrics tags list <metric>` to see available dimensions.
4. Query data: `pup metrics query --query="avg:<metric>{<filter>} by {<group>}" --from="1h"`

### Investigating logs

1. Start broad: `pup logs search --query="status:error" --from="1h" --limit=10` to see recent errors.
2. Narrow down: Add filters like `service:X AND @http.status_code:500`.
3. Aggregate for patterns: `pup logs aggregate --query="status:error" --from="1h" --compute="count" --group-by="service"` to find which services are failing.
4. 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".