Metrics

• You want to aggregate across hundreds or thousands of records (paginating is expensive and lossy)
• You’re looking for trends over time (error-rate spike, latency regression, traffic shift)
• You need to group by a dimension (errors by service, sessions by city, latency by span_name)
• You’re sizing the problem before drilling in with query-logs, query-traces, query-error-groups, or query-sessions

Tool guidance (query-aggregations)

The query-aggregations tool returns bucketed aggregated values, suitable for charting and analysis.

• product_type is required; one of errors, traces, logs, sessions (requests is accepted as an alias for traces).
• start_date is required; ISO format.
• end_date defaults to now.
• query is an attribute filter — e.g. error EXISTS AND service_name=foo.
• group_by is an attribute to group results by (e.g. message, service_name). Single field.

Note: across different product types, the same attribute keys work — query query-aggregations with product_type="sessions" and group_by="identifier" for session-grouping analogous to product_type="logs" with group_by="level".

Keep the bucket count small

When requesting aggregations, use coarser intervals or fewer groupings — bloated responses exceed the context window. Prefer 10–30 buckets over 1000; prefer a single group_by over multi-dimension pivots.

Typical patterns

1. Rate trends — product_type="errors", 24-hour window, group_by service_name → top offending services.
2. Unique-count queries — count unique users in a session set: query-aggregations with product_type="sessions", group_by="identifier". Don’t paginate through individual sessions.
3. Before/after comparison — run twice with adjacent time windows, compare the bucket counts to detect regressions.
4. Pre-chart sizing — before create-graph, run a query-aggregations query to verify the data shape is what you expect (non-empty, reasonable bucket distribution).

Pairing with get-keys

Before aggregating on an unfamiliar attribute, call get-keys for the product type to see which grouping keys exist. Attribute names vary — service_name vs service.name vs serviceName.

Interpreting results

• Coarse-first, then drill. A metrics bucket showing “errors up 300% in service X” is a starting point; follow with query-error-groups and query-logs to get the specific errors.
• Correlate trends with deploys, flag flips, traffic patterns. A shift that starts at a specific minute often points to an external trigger.
• Cite the metric type, grouping, and bucket range when presenting findings.

Common mistakes

• Paginating records when you should aggregate. If the goal is a count or distinct, use query-aggregations with group_by.
• Requesting too many buckets or nested groupings. Blow the context window and you lose your investigation.
• Skipping get-keys and guessing attribute names. Wrong name returns an empty metric — silently.