Query metrics using Builder

This page explains how to use the visual query builder to query OpenTelemetry metrics.

Query and analyze your OpenTelemetry metrics data using Builder, a visual interface in Axiom Console. This page shows you how to extract insights from your metrics through filtering, aggregation, and transformation operations.

For more information on working with metrics at Axiom, see Metrics overview.

To write queries directly using a text-based language, use MPL (Metrics Processing Language).

To migrate existing PromQL queries to Axiom, see Migrate PromQL queries to Axiom.

Concepts

• Dataset: A group of related metrics.
• Metric: A measurement that tracks a specific aspect of your system over time.
• Tag: A key-value pair identifying a series.
• Series: A unique combination of a metric and tag set.

Build metrics query

To build a typical metrics query:

1. Click the Query tab.
2. Click Builder in the top left.
3. In Dataset, define the source of your query. Select an OTel metrics dataset, and then select the metric you want to query.
4. In Where, filter the results. Restrict the query to a set of series whose tag values match the conditions you specify.
5. In Transformations, select the transformations you want to apply to the data.
6. Click Run.

The metric selector only shows metrics that were active during the selected time range. Expand the time range to see more metrics in the dropdown.

Example query

This example queries the axiom-dev.metrics dataset’s alertmanager_alerts metric one hour before the current time. It filters results to events where k8s.namespace.name is monitoring and aggregates events over 30-second time windows into their average value.

Elements of queries

The following explains each element of a metrics query.

Source

Specify the dataset and the metric in the Dataset field. The dataset and metric names are separated by a colon in the Builder interface.

For example, axiom-dev.metrics:alertmanager_alerts.

Filter

Use the Where section to filter series based on tag values.

1. Click + in the Where section.
2. Select the tag where you want to filter for values.
3. Select the logical operator of the filter. Available operators are:
   • Equality: ==, !=
   • Comparisons: <, <=, >, >=
4. Specify the value for which you want to filter.
5. Click + to add another filter and join them with the logical and operator.

For example, the following joins three filters: project == /.*metrics.*/ and code >= 200 and code < 300.

Transformations

Use the Transformations section to transform individual values or series.

1. Click + in the Transformations section.
2. Select the transformation you want to apply to the data. Available transformations are:
   • map: Map the data to a new value using the expression you specify.
   • align: Aggregate data using the function and the time window you specify.
   • group: Group the data by a set of tags using the aggregation function you specify.
   • bucket Aggregate the data by time and tag dimensions simultaneously.

Map

Use map to transform individual values.

Available mapping functions:

Function	Description
rate	Computes the per-second rate of change for a metric. Handles counter resets by treating negative deltas as resets and only computing the rate from the increase after the reset.
abs	Returns the absolute value of each data point.
interpolate::linear	Linear interpolation of missing values.
fill::prev	Fills missing values using the previous non-null value.

For example, to calculate rate per second for the metric, use map rate. To fill empty values with the latest value, use map fill::prev.

Handle cumulative counter resets

Cumulative counters are metrics that only increase over time, such as total requests served or total errors counted. These counters can reset to zero when the source restarts (for example, due to a deployment, power cycle, or crash).

When calculating rates or aggregating cumulative counters, use map rate or align ... using prom::rate to correctly handle these resets:

• map rate computes the per-second rate of change and treats any negative delta (where the new value is lower than the previous value) as a counter reset. It discards the data point spanning the reset and computes the rate from subsequent increases.
• align ... using prom::rate provides PromQL-style rate calculation over a specified time window with the same counter-reset handling.

To display the total value of a cumulative counter over a time window despite resets, combine map rate with align ... using sum to sum the per-second rates back into totals over each interval.

Align

Use align to aggregate over time windows. You can specify the time window and the aggregation function to apply.

Available aggregation functions:

Function	Description
avg	Averages values in each interval.
count	Counts non-null values per interval.
max	Takes the maximum value per interval.
min	Takes the minimum value per interval.
prom::rate	PromQL-style rate calculation.
sum	Sums values in each interval.
last	Takes the last value in each interval.

For example, to calculate the average over 5-minute time windows, use align to 5m using avg. To count the data points in the last hour, use align to 1h using count.

When metrics emit data at regular intervals but with different offsets across time series, align maps your data to a fixed set of time intervals. This makes it easier to visualize data from different sources on a single chart. If the alignment interval is shorter than the emission interval, some intervals can have null values. Select how to handle null values in the chart options.

Group

Use group to combine series by tags. You can specify the tags to group by and the aggregation function to apply. If you don’t specify tags, Axiom aggregates all series into one group.

Available aggregation functions:

Function	Description
avg	Averages values in each group.
count	Counts non-null values per group.
max	Takes the maximum value per group.
min	Takes the minimum value per group.
sum	Sums values in each group.

For example:

• To calculate the number of series, use group using count.
• To sum the values of all series, use group using sum.
• To group data by the project and namespace tags using the sum aggregation, use group by project, namespace using sum.

Bucket

Use bucket to aggregate over time and tag dimensions simultaneously.

Available aggregation functions:

Function	Description
avg	Averages values in each group and time inverval.
count	Counts non-null values per group and time inverval.
max	Takes the maximum value per group and time inverval.
min	Takes the minimum value per group and time inverval.
sum	Sums values in each group and time inverval.
quantile	Computes the specified quantile per group and time inverval. Specify the quantile as a value between 0 and 1. For example, specifying 0.99 corresponds to the 99th percentile.

For example:

• To calculate the average value per group and time interval, use bucket using histogram(avg).
• To also count the number of data points per group and time interval, use bucket using histogram(count, avg).

To show the results of multiple aggregations in a single chart, use multiple functions.

If you don’t specify tags with bucket, Axiom applies the specified aggregations to all tags.

When the underlying metric is a histogram, Axiom computes bucket aggregations using the interpolate_cumulative_histogram and interpolate_delta_histogram functions depending on the temporality used. For quantile aggregations, this estimates the quantile using the underlying histogram data.