LogicMonitor Query Language (LMQL) Reference for Advanced Metrics Widget

LogicMonitor Query Language (LMQL) extends the platform by giving you greater control and flexibility in how you query, filter, and visualize your data. LMQL uses a query-based approach, enabling you to analyze large data sets, customize visualizations, and extract meaningful insights.

The Advanced Metric widget leverages LogicMonitor’s LMQL to query for the data you want to visually represent in the widget. For more information, see Advanced Metrics Widget.

When you build the query, you start with an instant vector query, and use a combination of filters to narrow down the data and functions to perform operations or calculations for the data you need. 

Instant Vector Queries

Instant vector queries are used to refine instant queries so they return only the most relevant datapoints. Instant queries themselves retrieve the latest single value of a specified datapoint (for example, cpuUsage) across all instances where that datapoint exists.

Instant vector queries are paired with filters to limit the scope—for example, restricting results to certain resources, groups, or instances—making the output more targeted and efficient. Without filtering, these queries can generate very large result sets, since they pull one value per instance.

Filters for Instant Vector Queries

A filter is a mechanism for narrowing down which instances or datapoints are included in query results. Filters use property values, datasource names, instance names, or datapoints to select only the relevant time series data.

Each filter consists of the following:

• Filter name—Filter names can be the name of the property you want to use to limit the scope of the instant vector query. 
• Filter operator—Operators are what you want to use to match the filter name to a value.
• Value—A value is appended after the operator and what you want the filter name matched to.

Multiple filters can be combined within {} using commas, and an instance must satisfy all filter conditions to be included in the result set. This enables precise, flexible data retrieval tailored to specific use cases.

The following table describes the various filters you can use to further target your data with LMQL:

You can combine multiple filters for granularity. For example, the following query retrieve both CPU and disk usage datapoints, limits results to resources that belong to the Product group, and filters results to only those instances whose names start with “cpu core”:

{datapoint =~ "cpuUsage|diskUsage", system.groups = "Production", instance =~ "cpu core.*"}

Resource Aggregation Functions for Instant Vector Queries

Resource aggregation functions summarize values across multiple time series at a single point in time. The result is displayed as a single data point on the graph because the resource aggregation function returns a single value.

If you display the data as a graph, resource aggregation return one time series, with values for each time stamps. Displaying the data as big number or pie chart visuals—where only one value can be displayed—returns aggregated last sample value for end timestamp.

You can use the following basic syntax to build a query that contains an time series aggregation function:

function_name(<instant_query>)

LMQL supports the following resource aggregations:

For example, the following query returns the maximum CPU usage across all resource in pod p02.us-west-2.prod:

max(cpuUsage{lm_pod_name="p02.us-west-2.prod"})

Group By with Resource Aggregation Query for Instant Vector Queries

Resource aggregation normally collapses multiple series into a single result (for example, max CPU usage across all hosts in a region), but you may need aggregated values per group rather than a single rollup. For that, LMQL supports by() grouping modifiers with resource aggregation functions.

With by(), you can group data byhost properties (such as pod name, application, or region). The function then applies separately within each group, returning one result per group. If multiple properties are specified, LMQL creates groups based on the unique combinations of those property values.

You can use the following basic syntax to build a query that contains a group by function:

function_name by(property_key [, property_key2, ...]) (instant_query)

For example, the following query returns the maximum CPU usage reported for each pod in that region:

max by(lm_pod_name) (cpuUsage{auto.aws.region="us-west-2"})

Nested Grouping

You can compose multiple resource aggregations so that an aggregation does a detailed breakdown within another aggregation that rolls the results up further. The aggregation doing the detailed breakdown is the inner aggregation, and the aggregation doing the rollup is the outer aggregation.

For example, the following query returns the average CPU per pod, after first averaging per (pod, application), restricted to us-west-2:

avg by(lm_pod_name) ( avg by(lm_pod_name, application) (cpuUsage) )

The following is how the previous example queries data:

• The inner aggregation, avg by(lm _pod_name, application), computes per-application averages within each pod.
• The outer aggregation, avg by(lm_pod_name) rolls those application-level averages up to a pod-level average.

Arithmetic Expressions for Instant Vector Queries

LMQL supports binary arithmetic on instant vectors only. This lets you derive new, point-in-time values from existing datapoints (for example, compute free space, ratios, or percentages). You can also combine arithmetic with filters to keep results tight and relevant.

LMQL support the following expressions:

For example, the following query returns data on free disk space:

StorageSize - StorageUsed

Range Vector Queries

A range vector query extends the concept of an instant vector query. Instead of returning just the most recent sample for each metric, it retrieves a range of samples over a specified duration back from the current timestamp. The duration is expressed in square brackets ([]) after the query. Where a filter defines which data to query, a range vector query defines how much historical data to retrieve for each data.

For example, the following range vector query retrieves CPU usage samples from the last five minutes:

cpuUsage[5m]

Range queries override the global time window if a duration is explicitly specified. The boundaries are inclusive, so samples at the start and end of the range are included.

The following time units are supported with range vector queries:

The LMQL range vector query returns up to 1,000 data samples per time series. If more are available, LMQL consolidates them into 1,000 points using the average (avg) function, similar to custom graph widgets.

Time Series Aggregation Function for Range Queries

Time-series aggregation functions take a range vector and collapse all samples in that window into one value per series. This helps to consolidate data samples for large duration of queries. The result is displayed as a single data point on the graph for each selected time series since the time series aggregation function returns a single value per time series.

You can use the basic syntax to build a query that contains an time series aggregation function:

function_name( <range-query> )

LMQL supports the following time series aggregations:

For example, the following query retrieves time series data for a specified time range:

sum_over_time( cpuUsage{system.displayname = "collector_1"} [4w] )

Offset Modifiers

By default, LMQL queries evaluate data from the current time. The offset modifier shifts the evaluation time backwards by a specified duration, enabling retrieval of historical data. It can be applied to instant or range vector queries. You can use the basic syntax to build a query that contains an offset modifier:

<instant_query | range_query> offset <duration>

The following describes how you can leverage the offset modifier in various scenarios:

Advanced Queries and Compositions

You can use advanced queries and composition in LMQL when you need control, accuracy, and complexity in retrieving information.

The following describes common types of advanced queries along with the use case where the query is helpful: 

Literal Queries

LMQL can evaluate pure literals or mix constants with vectors when you need exactness over flexibility. This enables you to ensure LogicMonitor matches only what you type, exactly as you type it. Literal queries are helpful if you need to perform quick math, apply scaling factors or offsets to entire metrics, and mix constants with metric vectors for normalization, thresholds, or alerting logic.

The following describes literal queries that LMQL can perform with examples and outputs:

Comparisons, Parenthesis, and Logical (Set) Operators

LMQL supports comparisons and logical (set) operations on metrics, literals, and expressions. These extend LMQL beyond raw values, enabling you to build conditional expressions, filters, and alert-like queries.

The following describes the types of operations you can leverage in LMQL: