1. Compatibility #
Your PromQL queries work.
Useful differences #
MetricsQL accepts existing PromQL queries, with a few behavioral differences designed to be more intuitive:
| Point | PromQL | MetricsQL |
|---|---|---|
rate window | Mandatory: rate(x[5m]) | Optional: rate(x) picks the window based on the graph step |
increase extrapolation | Fractional results for integer counters | No extrapolation: integer values as expected |
| Metric name after a function | Dropped | Can be kept with keep_metric_names |
| Missing value | Series absent | default 0 to fill in |
2. Extra functions #
A selection.
Examples #
# Modèles WITH : factoriser une requête complexe
WITH (
errs = sum(rate(http_requests_total{code=~"5.."})) by (service),
total = sum(rate(http_requests_total)) by (service),
)
errs / total
# Top 5 des séries selon leur moyenne sur la période affichée
topk_avg(5, rate(node_network_receive_bytes_total))
# Plusieurs agrégats d'une fenêtre en une passe (min, max, avg)
rollup(node_load1[1h])
# Combler les trous et garder le nom
rate(http_requests_total) keep_metric_names default 0
# Manipulation de labels
label_set(up, "equipe", "plateforme")
label_map(up, "job", "node", "système", "api", "applicatif")
# Médiane de chaque série sur la plage affichée
range_median(node_load1)Common mistake: If you use MetricsQL functions in dashboards, they will no longer work on a regular Prometheus. Stick to standard PromQL for dashboards shared across several stores.
3. Exploring with vmui #
Queries, query traces and cardinality.
vmui tools #
| Tab | Usage |
|---|---|
| Query | Queries with graph, table, JSON and execution trace |
| Cardinality explorer | Metrics, labels and values creating the most series |
| Top queries | Most frequent and slowest queries |
| Active queries | Queries in progress |
| Relabeling debug | Test a relabeling rule |
Good practice: The cardinality explorer is the first tool to open when memory grows: it shows the responsible metric or label in one click.
