Cloud Monitoring ListTimeSeries Basic Aggregations Reference
This document maps Cloud Monitoring Aligner and Reducer concepts to structured
ListTimeSeries (list_timeseries) REST request fields. Use this matrix and
default rules to determine the correct aggregation query parameters
(aggregation.perSeriesAligner, aggregation.crossSeriesReducer, and
aggregation.groupByFields) based on Cloud Monitoring metric properties
(metricKind and valueType) and desired calculation goals.
Table of Contents
- Translation Matrix (~Line 26)
- Default Aggregations and Visualization Rules
(~Line 74)
- 1. CPU and Memory Utilization (Ratios / Percentages) (~Line 80)
- 2. Rate of Events / Throughput (Counters) (~Line 99)
- 3. Distribution Metrics (Quantiles / Latency) (~Line 114)
- 4. Boolean & Status Metrics (BOOL Value Type) (~Line 132)
- 5. Backlog Age & Processing Lag (ALIGN_MAX / REDUCE_MAX) (~Line 143)
Translation Matrix
To use this matrix:
- Inputs: Identify the metric's
metricKindandvalueTypefrom itsMetricDescriptor, then infer the target calculation goal from the user's prompt (e.g., Mean, Sum, 95th Percentile) under Aggregation Intent to select the matchingperSeriesAlignerandcrossSeriesReducer. - Output Aggregation Fields (MANDATORY): Extract BOTH
perSeriesAlignerANDcrossSeriesReducervalues from the table below to populate theaggregationquery parameters (aggregation.perSeriesAlignerandaggregation.crossSeriesReducer) in yourListTimeSeriesREST request. Every request MUST specify bothperSeriesAlignerandcrossSeriesReducer.
| Metric Kind | Value Type | Aggregation Intent | perSeriesAligner |
crossSeriesReducer |
|---|---|---|---|---|
GAUGE |
NUMERIC (INT64 / DOUBLE) |
None / Raw Points | ALIGN_MEAN |
REDUCE_NONE |
GAUGE |
NUMERIC |
Mean | ALIGN_MEAN |
REDUCE_MEAN |
GAUGE |
NUMERIC |
Min | ALIGN_MIN |
REDUCE_MIN |
GAUGE |
NUMERIC |
Max | ALIGN_MAX |
REDUCE_MAX |
GAUGE |
NUMERIC |
Sum (default) | ALIGN_MEAN |
REDUCE_SUM |
GAUGE |
NUMERIC |
Count time series | ALIGN_MEAN |
REDUCE_COUNT |
GAUGE |
NUMERIC |
99th percentile | ALIGN_MEAN |
REDUCE_PERCENTILE_99 |
GAUGE |
NUMERIC |
95th percentile | ALIGN_MEAN |
REDUCE_PERCENTILE_95 |
GAUGE |
NUMERIC |
50th percentile | ALIGN_MEAN |
REDUCE_PERCENTILE_50 |
GAUGE |
NUMERIC |
5th percentile | ALIGN_MEAN |
REDUCE_PERCENTILE_05 |
GAUGE |
DISTRIBUTION |
Distribution (default) | ALIGN_SUM |
REDUCE_SUM |
GAUGE |
DISTRIBUTION |
Mean | ALIGN_SUM |
REDUCE_MEAN |
GAUGE |
DISTRIBUTION |
99th percentile | ALIGN_PERCENTILE_99 |
REDUCE_NONE / REDUCE_PERCENTILE_99 |
GAUGE |
DISTRIBUTION |
95th percentile | ALIGN_PERCENTILE_95 |
REDUCE_NONE / REDUCE_PERCENTILE_95 |
GAUGE |
DISTRIBUTION |
50th percentile | ALIGN_PERCENTILE_50 |
REDUCE_NONE / REDUCE_PERCENTILE_50 |
GAUGE |
BOOL |
None / Raw Points | ALIGN_FRACTION_TRUE |
REDUCE_NONE |
GAUGE |
BOOL |
Fraction true (default) | ALIGN_FRACTION_TRUE |
REDUCE_MEAN |
GAUGE |
BOOL |
Count true | ALIGN_FRACTION_TRUE |
REDUCE_SUM |
DELTA / CUMULATIVE |
NUMERIC (INT64 / DOUBLE) |
None / Raw Points | ALIGN_RATE |
REDUCE_NONE |
DELTA / CUMULATIVE |
NUMERIC |
Sum (default) | ALIGN_RATE |
REDUCE_SUM |
DELTA / CUMULATIVE |
NUMERIC |
Mean | ALIGN_RATE |
REDUCE_MEAN |
DELTA / CUMULATIVE |
NUMERIC |
Min | ALIGN_RATE |
REDUCE_MIN |
DELTA / CUMULATIVE |
NUMERIC |
Max | ALIGN_RATE |
REDUCE_MAX |
DELTA / CUMULATIVE |
NUMERIC |
99th percentile | ALIGN_RATE |
REDUCE_PERCENTILE_99 |
DELTA / CUMULATIVE |
NUMERIC |
95th percentile | ALIGN_RATE |
REDUCE_PERCENTILE_95 |
DELTA / CUMULATIVE |
NUMERIC |
50th percentile | ALIGN_RATE |
REDUCE_PERCENTILE_50 |
DELTA / CUMULATIVE |
DISTRIBUTION |
Distribution (default) | ALIGN_DELTA |
REDUCE_SUM |
DELTA / CUMULATIVE |
DISTRIBUTION |
Mean | ALIGN_DELTA |
REDUCE_MEAN |
DELTA / CUMULATIVE |
DISTRIBUTION |
99th percentile | ALIGN_PERCENTILE_99 |
REDUCE_NONE / REDUCE_PERCENTILE_99 |
DELTA / CUMULATIVE |
DISTRIBUTION |
95th percentile | ALIGN_PERCENTILE_95 |
REDUCE_NONE / REDUCE_PERCENTILE_95 |
DELTA / CUMULATIVE |
DISTRIBUTION |
50th percentile | ALIGN_PERCENTILE_50 |
REDUCE_NONE / REDUCE_PERCENTILE_50 |
Default Aggregations and Visualization Rules
Apply these standard defaults when constructing ListTimeSeries REST query
specifications for charts, dashboards, or when the user's aggregation preference
is underspecified:
1. CPU and Memory Utilization (Ratios / Percentages)
- Use when: Querying CPU or memory utilization metrics (ratios or
percentages) for any service or agent (e.g.,
compute.googleapis.com/instance/cpu/utilizationoragent.googleapis.com/memory/percent_used). - Default Aggregation Directive: For CPU and memory utilization metrics,
default to
perSeriesAligner = ALIGN_MEANandcrossSeriesReducer = REDUCE_NONE. If needed, group specifically by instance, such asgroupByFields = ["resource.labels.instance_id"]. - Aggregation Constraints:
- No Cross-Series Summing: Do NOT use
crossSeriesReducer = REDUCE_SUM. Utilization metrics represent ratios or percentages; summing them across instances yields invalid percentages over 100%. - No Cross-Series Averaging for Resource Limits: Averaging utilization
across instances (
crossSeriesReducer = REDUCE_MEAN) masks severe outliers. For example, one instance crashing at 100% while others sit idle at 0%.
- No Cross-Series Summing: Do NOT use
2. Rate of Events / Throughput (Counters)
- Use when: Querying
DELTAorCUMULATIVEevent counter metrics. - Throughput Rule: You MUST convert
DELTAorCUMULATIVEmetrics representing event counts (INT64/DOUBLE) to a rate by settingperSeriesAligner = ALIGN_RATE. - Cross-Series Reducer: Use
crossSeriesReducer = REDUCE_SUMwhen combining throughput across instances (e.g., total read bytes per second across all VMs in a zone).- Example:
perSeriesAligner = ALIGN_RATE,crossSeriesReducer = REDUCE_SUM,alignmentPeriod = "300s".
- Example:
- Removal of Transform Functions: Do NOT apply multi-layer transform
aligners. Apply
perSeriesAligner = ALIGN_RATEandcrossSeriesReducer = REDUCE_SUMcleanly in a single primary aggregation query.
3. Distribution Metrics (Quantiles / Latency)
- Use when: Querying
DISTRIBUTIONmetrics (such as request latencies). - Rule: For
DISTRIBUTIONmetrics, such as Cloud Run request latencies (run.googleapis.com/request_latency/e2e_latencies) or Pub/Sub ack latencies (pubsub.googleapis.com/subscription/ack_latencies):- To retrieve raw histogram bucket distributions across instances, use
perSeriesAligner = ALIGN_DELTA(forDELTA/CUMULATIVE) orperSeriesAligner = ALIGN_SUM(forGAUGE) withcrossSeriesReducer = REDUCE_SUM. - To extract specific percentile latency gauges directly via the API, use
percentile aligners:
perSeriesAligner = ALIGN_PERCENTILE_99,perSeriesAligner = ALIGN_PERCENTILE_95,perSeriesAligner = ALIGN_PERCENTILE_50, orperSeriesAligner = ALIGN_PERCENTILE_05. When reduction across instances is requested, combine with the matching reducer (e.g.,perSeriesAligner = ALIGN_PERCENTILE_95,crossSeriesReducer = REDUCE_PERCENTILE_95).
- To retrieve raw histogram bucket distributions across instances, use
4. Boolean & Status Metrics (BOOL Value Type)
- Use when: Querying
BOOLvalue type metrics. - Default Aggregations:
- Fraction True / Availability:
perSeriesAligner = ALIGN_FRACTION_TRUE,crossSeriesReducer = REDUCE_MEANreturns the fraction of healthy instances in[0.0, 1.0]. - Count True:
perSeriesAligner = ALIGN_FRACTION_TRUE,crossSeriesReducer = REDUCE_SUMreturns the total count of healthy instances (INT64).
- Fraction True / Availability:
5. Backlog Age & Processing Lag (ALIGN_MAX / REDUCE_MAX)
- Use when: Querying metrics tracking maximum age, lag, or oldest unacknowledged items.
- Rule: For metrics tracking the maximum age, lag, or oldest
unacknowledged item across services or workers (e.g.,
pubsub.googleapis.com/subscription/oldest_unacked_message_ageordataflow.googleapis.com/job/system_lag), always default toperSeriesAligner = ALIGN_MAXandcrossSeriesReducer = REDUCE_MAXto surface peak delays across instances.