Skip to content
RouteSpear
Start free
Documentation
Documentation menu

Query language

Learn MetricQL, from a first metric query to source pipelines, joins, counters, and alert conditions.

MetricQL is shared by Metrics Explorer, dashboard query series, saved queries, and health-rule conditions. Start with one metric, then add filters and grouping as your question becomes more specific.

Your first query

http_check_total_ms | avg by (target)

This draws average HTTP duration for each target. Run it in Metrics Explorer and choose a time range with measurements. No returned series means no matching data, not zero latency. Press Ctrl+Space for IntelliSense and Ctrl+Enter to run (Cmd+Enter on macOS).

To select several measurements and organize them by test and agent, use their full metric names with from tests:

from tests
| where test_type = "http_check" and test.name =~ "API.*"
| summarize avg(http_check_passed) as pass_rate,
            p95(http_check_total_ms) as latency
  by test_type, test_id, test.name, agent_id, agent.name
| order by agent.name asc

IntelliSense shows names alongside IDs and inserts the value appropriate to the filter. Grouping by IDs as well as names keeps duplicate names distinct. Names are current metadata, including when querying older measurements.

Choose a topic

  • Query basics: choose selectors or source pipelines, use IntelliSense, and learn filtering, aggregation, and grouping.
  • Source pipelines: select several measurements, name their outputs, use agent/test metadata, and rank entities.
  • Joins and calculations: combine metrics and sources, choose matching keys, and handle units and missing values.
  • Counters and baselines: calculate rates and increases, reduce or rank groups, and compare with learned history.
  • Examples and troubleshooting: follow worked investigations, inspect host processes, and resolve errors and query limits.

For the available filter and grouping keys, see Dimensions. To turn a query into an alert, use Health rules for scope, thresholds, timing, and no-data behavior.

Where a query can run

The same language is available in four places:

  • the Metrics Explorer, where results are scored against their own baseline;
  • a saved query, which stores the text verbatim and re-parses it on every run;
  • a dashboard panel’s Query language series, where each by (...) group becomes one chart line;
  • a health rule condition, where the by (...) becomes the set of entities the rule judges, one query result per tick rather than one point per chart bucket.

Health-rule source conditions must end in pick, omit ordering and limits, and group by the rule’s scope (or omit grouping for a scalar broadcast). Calculations use each input’s aggregate over the evaluation window. Learned baseline conditions support selectors and source queries that pick one measured output (avg, min, max, or percentile), using stable IDs and recorded labels. Joins, calculations, totals, counts, counter conversions, and current-metadata relationships cannot define learned history. Baseline/deviation stages in query text remain selector syntax; choose baseline judging separately in a health rule. See Advanced health-rule recipes for examples.

Next

Older section links

Screenshot