- Axiom Processing Language (APL) lets you query datasets with events, OTel logs, and OTel traces. For more information, see Introduction to APL.
- AxQL lets you query OTel metrics. This page explains how to use AxQL.
Support for OTel metrics is currently in public preview. For more information, see Feature states.
Limitations
The current implementation of AxQL comes with the following limitations:- You can only query one dataset in a query.
Concepts
- Dataset: A group of related metrics.
- Metric: One-dimensional time series data.
- Tag: Key-value pair identifying a series.
- Series: A unique combination of a metric and tag set.
Query structure
A typical AxQL query contains the following:- Source: Defines dataset, metric, and optional time range
- Filter: Applies conditions to series via tags
- Transformation can be the following:
- Mapping: Maps the data to a new value.
- Aggregation: Aggregates the data over a given time to a single value.
- Grouping: Groups the data by a set of tags, combining overlapping values.
- Bucketing: A two-dimensional transformation that combines the time and tag dimension.
k8s
dataset’s cpu_usage
metric one hour before the current time. It filters results to events where namespace
is prod
and aggregates events over 5-minute time windows into their average value.
Elements of queries
The following explains each element of an AxQL query. To learn more about the language features of AxQL, see Language features.Source
Specify the dataset, the metric, and optional time bounds. Syntax:- dataset: Name of the dataset.
- metric: Name of the metric.
- time range: Optional: The time range of the query. For more information, see Time ranges.
- alias: Optional: Renames the metric for later use.
Filter
Usewhere
or filter
to filter series based on tag values. where
and filter
are identical.
Syntax:
- Equality:
==
,!=
- Comparisons:
<
,<=
,>
,>=
Mapping
Transform individual values or series. Available functions:Function | Description |
---|---|
rate | Computes the per-second rate of change for a metric. |
min(arg) | Returns the minimum between the argument and the value. |
max(arg) | Returns the maximum between the argument and the value. |
abs | Returns the absolute value of each data point. |
fill::prev | Fills missing values using the previous non-null value. |
fill::const(arg) | Fills missing values with a constant. |
interpolate::linear | Linear interpolation of missing values. |
+ , - , * , / | Performs the respective mathematical calculation on each value. |
> , < , >= , <= | Sets the value to 1.0 if the condition is true, 0 otherwise. |
Aggregation
Usealign
to aggregate over time windows.
Syntax:
Function | Description |
---|---|
avg | Averages values in each interval. |
sum | Sums values in each interval. |
min | Takes the minimum value per interval. |
max | Takes the maximum value per interval. |
count | Counts non-null values per interval. |
prom::rate | Prometheus style rate |
Grouping
Usegroup by
to combine series by tags.
Syntax:
Function | Description |
---|---|
avg | Averages values in each interval. |
sum | Sums values in each interval. |
min | Takes the minimum value per interval. |
max | Takes the maximum value per interval. |
count | Counts non-null values per interval. |
Bucketing
Bucketing is a special case of grouping that combines the time and tag dimensions. Syntax:Function | Description |
---|---|
histogram | Calculates a histogram over all values in the bucket. |
interpolate_histogram | Interpolates a histogram from a histogram-type set of series. |
Other operations
Compute
Combine multiple metrics in one query block. Syntax:Operator | Description |
---|---|
+ | Adds subquery results. |
- | Subtracts one subquery from another. |
* | Multiplies subquery results. |
/ | Divides one subquery by another. |
min | Minimum across result series. |
max | Maximum across result series. |
avg | Average across result series. |
Language features
Data types
- Strings:
"string"
- Integers:
42
- Floats:
3.14
- Booleans:
true
,false
- Regex:
/.*metrics.*/
Identifier naming rules
Valid identifier names in AxQL follow these rules:- Between 1 and 1024 characters long.
- Allowed characters:
- Alphanumeric characters (letters and digits)
- Underscore (
_
) - Dot (
.
)
Quote identifiers
Quote an identifier in your AxQL query if any of the following is true:- The identifier name contains an unsupported character.
- The identifier name is identical to one of the reserved keywords of the APL query language. For example,
by
orwhere
.
my-field
.
If none of the above is true, you don’t need to quote the identifier in your AxQL query. For example, myfield
. In this case, quoting the identifier name is optional.
Time ranges
Syntax:- Start time:: Inclusive beginning of the time range.
- End time: Optional, exclusive end of the time range. If you don’t specify the end time, Axiom uses the current time.
..
.
Time can be defined in one of the following ways:
- Relative time. The time unit can be one of the following:
ms
for milliseconds (will be rounded to seconds)s
for secondsm
for minutesh
for hoursd
for daysw
for weeksM
for monthsy
for years Examples:-1h
,+5m
- Unix epoch timestamp in seconds. For example:
1723982394
- An RFC3339 timestamp. For example:
2025-03-01T13:00:00Z