Metric rollups and resolution

Resolution controls how metric data is grouped over time. It affects metric detail charts, dashboard charts, alarms, and API queries.

Use this guide when a chart looks too detailed, too smooth, or when count, avg, max, percentile, or trimmed mean values do not match what you expected.

What resolution means

Resolution is the bucket size in seconds.

When you query a metric at 60 second resolution, each returned point represents one one-minute bucket. When you query at 300 second resolution, each returned point represents one five-minute bucket.

Smaller resolutions show more detail. Larger resolutions summarize more data into fewer points, which makes long time ranges easier to read.

Resolution when sending metrics

Each metric entry can include a resolution.

If resolution is omitted, the API stores the point at one-second resolution. If you send resolution: 60, the point represents a one-minute bucket.

Choose a send resolution that matches how often the data was measured or flushed:

• use 1 for high-frequency raw samples;
• use 60 for values emitted once per minute;
• use a larger value when a job already summarizes a longer interval.

When querying later, choose the resolution that matches the question you are asking. It does not have to match the resolution used when the metric was sent.

See Send your first metric for request examples.

Single values

A single value represents one observation at one timestamp.

The API stores that observation with a sample count of 1. If the value is queried alone:

• min, max, and avg return the value;
• count returns 1;
• sum returns the value.

When several single values fall into the same query bucket, the selected aggregation is calculated across those values.

Statistic sets

A statisticSet represents several observations that were already summarized before sending.

It includes:

• min: the smallest observed value;
• max: the largest observed value;
• avg: the average value;
• sampleCount: how many observations the set represents.

Use statistic sets when a client, agent, or batch job buffers observations and flushes them later. This keeps payloads smaller while preserving the data needed for rollups.

count uses sampleCount. If a query bucket contains multiple statistic sets, count returns the sum of their sampleCount values.

How rollups affect aggregations

When the query resolution is larger than the stored resolution, multiple source buckets are rolled up into one returned bucket.

The returned aggregation is calculated from the data represented by the source buckets:

• min returns the smallest value in the returned bucket;
• max returns the largest value in the returned bucket;
• avg returns the weighted average using sample counts;
• count returns the total sample count;
• sum returns the summed values represented by the bucket;
• percentile(95) returns the requested percentile for the bucket;
• trimmed_mean(10;10) returns the average after trimming the lower and upper percentages from the bucket.

percentile(...) and trimmed_mean(...) are accurate for data sent as individual value entries. For statisticSet sources only the per-set average is available, so those distribution aggregations approximate toward the mean.

For example, if six one-minute buckets are queried at 300 second resolution, the chart returns one point for each five-minute group. The one-minute detail is summarized into that larger point.

Choosing resolution in the UI

The time range picker controls the query window and resolution for metric detail pages, dashboards, and alarm previews.

Use short ranges with smaller resolutions when investigating a recent spike. Use longer ranges with larger resolutions when looking for trends.

Practical starting points:

• last hour: 1m often gives enough detail;
• last day: 5m or 15m is easier to scan;
• last week: larger buckets are usually better for trends.

If a chart looks noisy, increase the resolution. If a spike disappears, lower the resolution or narrow the time range.

Resolution in alarms

Alarm resolution controls the buckets used during evaluation.

Match alarm resolution to the reporting frequency of the metric. A metric reported once per minute usually works well with 1m. A metric reported every few seconds may need a shorter resolution. A batch metric that reports every five minutes should not use a one-minute alarm resolution.

Use Datapoints to Alarm together with resolution to control sensitivity. For example, requiring several breaching buckets avoids alerting on a single short spike.

See Create an alarm for the alarm setup flow.

Common surprises

count is sample count, not number of API requests. A single API request can send many entries, and one statistic set can represent many samples.

avg across statistic sets is weighted by sampleCount. A statistic set with sampleCount: 100 has more weight than one with sampleCount: 1.

Large resolutions can hide short spikes because several smaller buckets are summarized into one point.

The query resolution is a viewing choice. Change it freely to trade detail for readability.