Claude Skill

metricsql

VictoriaMetrics MetricsQL query language as a PromQL superset: rollup extensions, behavioral differences from PromQL (rate/increase semantics, implicit conversions, auto-aligned subqueries), label manipulation, WITH templates, keep_metric_names modifier, multiple-or filters, and

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download xobotyi-cc-foundry-plugins_grafana_skills_metricsql-278c16c.zip · 19 KB

Install

skills CLI npx skills add https://github.com/xobotyi/cc-foundry/tree/master/plugins/grafana/skills/metricsql
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install xobotyi-cc-foundry@llmmart
Git git clone https://github.com/xobotyi/cc-foundry.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole xobotyi/cc-foundry collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

MetricsQL

VictoriaMetrics PromQL superset. Syntactically backwards-compatible; semantically different for a subset of queries. Lead with the diffs — that's where users get burned. PromQL fundamentals live in the sibling promql skill; this covers only what PromQL doesn't.

References

  • Behavioral diffs from PromQL — [${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md] rate/increase/delta/changes diffs, _prometheus-suffixed variants, scalar/instant-vector unification, NaN handling, name retention, implicit conversions, auto-aligned subqueries, default_rollup lookback, staleness markers.
  • MetricsQL-only extensions — [${CLAUDE_SKILL_DIR}/references/extensions.md] Rollup family, WITH templates, multiple-or filters, default/if/ifnot ops, group_left(*) prefix, keep_metric_names, [Ni] step, numeric suffixes, aggregate limit N, boundsLabel, fractional durations, Graphite, multi-line.
  • Full function catalog — [${CLAUDE_SKILL_DIR}/references/functions-catalog.md] All rollup, transform, label-manipulation, aggregate functions by category, with PromQL/MetricsQL provenance.
  • Query API enhancements — [${CLAUDE_SKILL_DIR}/references/api-enhancements.md] extra_label, extra_filters[], round_digits, limit, timestamp formats, stats response, cluster vmselect URL layout, multi-tenancy.

Read the relevant reference before proceeding.

What MetricsQL Is

  • Strict syntactic superset of PromQL — every valid PromQL parses as MetricsQL.
  • Not semantic superset — rate, increase, delta, changes differ.
  • _prometheus-suffixed variants give byte-parity: rate_prometheus, increase_prometheus, delta_prometheus, changes_prometheus.
  • Implemented by vmselect (cluster) or single-node binary; exposed via standard /api/v1/query and /api/v1/query_range.

The Five Behavioral Diffs That Bite

  1. Lookbehind anchor. rate/increase use the last sample before the window for the first delta; Prometheus doesn't. For increase(metric[$__interval]) on a slow counter, Prometheus loses one delta per window. Use rate_prometheus/increase_prometheus for parity.
  2. No extrapolation. Returns actual measured delta; Prometheus extrapolates to window edges, producing fractional results from integer counters. Affects alerts comparing increase() to integer thresholds.
  3. Scalar = instant vector without labels. Prometheus's scalar/instant-vector distinction collapses. scalar(metric) coercion rarely needed; arithmetic on aggregation results works.
  4. NaN drop. (-1)^0.5 returns empty in MetricsQL; Prometheus returns a NaN series. Grafana renders identically; programmatic consumers see different shapes.
  5. Metric names retained for safe functions. min_over_time(foo), round(foo), abs(foo) keep foo. Prometheus strips.

Full mechanics, edge cases, implicit-conversion pipeline, per-function table: [${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md].

Lookbehind Window — Auto-Selection

Omitting [d] is allowed:

  • default_rollup and rate: max(step, scrape_interval) — prevents gaps when step < scrape_interval.
  • All other rollups: step ($__interval in Grafana, 1i).
  • rate(node_network_receive_bytes_total) ≡ rate(node_network_receive_bytes_total[$__interval]).

Silent behavior change across panels with different steps. For alerting and recording rules, always specify the window explicitly.

Implicit Query Conversions

VictoriaMetrics rewrites every query before evaluation (unless -search.disableImplicitConversion):

  • Bare selectors → default_rollup: foo → default_rollup(foo).
  • Selectors inside transform/aggregate get the same wrap: abs(temperature) → abs(default_rollup(temperature)), count(up) → count(default_rollup(up)).
  • Rollups on non-selectors become subqueries: rate(sum(up)) → rate((sum(default_rollup(up)))[1i:1i]).
  • Subqueries with missing step get 1i: avg_over_time(rate(m[5m])[1h]) → avg_over_time(rate(m[5m])[1h:1i]).

When debugging, mentally apply these first — the actual computation may differ from what was typed.

Full conversion list with disable flags: [${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md].

The Rollup Family — MetricsQL-Only

  • rollup(m[d]) — min/max/avg with rollup="..." label.
  • rollup_rate(m[d]) — per-second rate min/max/avg over adjacent samples; better than irate for spike detection.
  • rollup_increase(m[d]) / rollup_delta(m[d]) / rollup_deriv(m[d]) — same pattern.
  • rollup_candlestick(m[d]) — OHLC.
  • aggr_over_time(("func1","func2",...), m[d]) — multiple rollups in one pass.

Pair with keep_metric_names to preserve the original name.

keep_metric_names

Functions and binary ops strip the metric name. This causes duplicate time series errors when distinct names collapse into the same label set. Suffix with keep_metric_names:

  • rate({__name__=~"foo|bar"}) keep_metric_names
  • ({__name__=~"foo|bar"} / 10) keep_metric_names

Available on all rollups, transforms, and binary operators.

Multiple or in Series Selectors

PromQL {env="prod",job="a"} is a single AND. MetricsQL adds top-level disjunction:

{env="prod",job="a" or env="dev",job="b"}

Each or-group is an AND of matchers. Compose with comma within a group.

Multi-constant matching: status_code == (300, 301, 304) returns series where status_code is any listed value.

WITH Templates

Reusable named subexpressions:

WITH (
  errs = rate(http_requests_total{status=~"5.."}[5m]),
  total = rate(http_requests_total[5m]),
)
sum(errs) by (job) / sum(total) by (job)

String concat: WITH (commonPrefix="my_app_") {__name__=commonPrefix+"errors_total"}. Expanded at parse time.

Binary Operators Beyond PromQL

  • q1 default q2 — fills gaps in q1 from q2.
  • q1 if q2 — keeps q1 where q2 has a value (conditional masking).
  • q1 ifnot q2 — keeps q1 where q2 has no value (inverse).

Compose with default-on-missing: (up{job="x"} default 0) == 0 reliably alerts on disappearing targets.

group_left(*) and Label Copy

kube_pod_info * on(namespace) group_left(*) prefix "ns_" kube_namespace_labels

Copies all labels from right side except those in on(...), prefixed with ns_. group_right(*) mirrors. Without prefix, collisions error.

Aggregate limit N

sum(http_requests_total) by (path) limit 10

Returns 10 paths total. Other series dropped silently. Distinct from topk(10, ...): limit N is order-arbitrary; topk keeps the top by value.

Grafana $__interval and [Ni] Syntax

  • 1i = one step (Grafana step arg).
  • [10i] = lookbehind covering ten steps.
  • offset 5i = shift back five steps.
  • Works in rollup windows, offsets, subquery step: rate(metric[10i] offset 5i).
  • Use over hard-coded durations so panels scale with the time range.

Cluster Endpoint Structure

http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query
http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query_range

<accountID> is accountID or accountID:projectID (32-bit ints). Single-node uses unprefixed /api/v1/query. /prometheus/ prefix is optional but explicit.

Full URL layout (ingestion, federation, Graphite, vmstorage admin, vmalert proxy): [${CLAUDE_SKILL_DIR}/references/api-enhancements.md].

Query API Enhancements

  • extra_label=<name>=<value> — adds {name="value"} to every selector. Repeatable. Used by auth proxies for tenant scoping.
  • extra_filters[]=<selector> — adds a full selector with regex support: extra_filters[]={env=~"prod|staging"}.
  • round_digits=N — rounds response values to N decimals.
  • limit=N on /api/v1/labels, /api/v1/label/<name>/values, /api/v1/series.

Responses include stats with executionTimeMsec and seriesFetched. seriesFetched is approximate; vmalert uses it to flag never-firing rules.

Syntax Conveniences

  • Underscore in numbers — 1_234_567_890 ≡ 1234567890
  • Numeric suffixes — 8K (8000), 1.2Mi (1.2×1024²), supports K Ki M Mi G Gi T Ti
  • Fractional durations — [1.5m], offset 0.5d
  • Optional duration suffix — [300] is seconds: rate(m[300] offset 1800) ≡ rate(m[5m]) offset 30m
  • Duration anywhere — sum_over_time(m[1h]) / 1h ≡ sum_over_time(m[1h]) / 3600
  • Trailing commas — m{foo="bar",}, f(a, b,), WITH (x=y,) x all valid. Use in multi-line queries.
  • Unicode in names — ტემპერატურა{πόλη="Київ"} is valid
  • Escape sequences — foo\-bar{baz\=aa="b"}, \xXX, \uXXXX
  • @ modifier anywhere — sum(foo) @ end(), foo @ (end() - 1h)

Histogram Extensions

histogram_quantile(phi, buckets, boundsLabel?) — optional third arg returns lower/upper bounds in boundsLabel. For plotting quantile confidence intervals.

histogram_over_time(gauge[d]) produces VictoriaMetrics-format histograms from gauge values:

histogram_quantile(0.5, sum(histogram_over_time(temperature[24h])) by (vmrange,country))

Computes quantiles over gauge distributions without re-instrumenting.

Application

When writing:

  • Omit lookbehind only when panel-wide $__interval is appropriate. Otherwise use [5m] or [Ni] explicitly.
  • For alerting/recording rules: always specify the lookbehind window. Implicit selection couples rule behavior to evaluation interval.
  • Prefer default over or vector(0) — more readable, handles labels correctly.
  • Use rollup_rate for counter spike detection over irate — min/max/avg in one query.

When migrating from Prometheus:

  • Audit alerts comparing increase() to integer thresholds — exact integers may fire differently.
  • Use *_prometheus variants only when byte-parity is required (cross-backend SLO consistency).
  • Enable -search.logImplicitConversion to see rewrites.

When reviewing:

  • Flag missing lookbehind windows in alerting/recording rules.
  • Flag rate(sum(...)) — silent subquery formation.
  • Flag bare selectors in arithmetic — silent default_rollup wrap.
  • Cite the specific diff and show the fix inline.

Integration

promql — shared fundamentals (selectors, operators, aggregations, vector matching). This skill — MetricsQL extensions and diffs.

prometheus — instrumentation; this skill — query-time behavior.

Files (cc-foundry)
  • .dev
    • reference-inventory.json 1.6 KB
      Loading…
  • references
    • api-enhancements.md 7.2 KB
      Loading…
    • behavioral-diffs.md 9.1 KB
      Loading…
    • extensions.md 7.7 KB
      Loading…
    • functions-catalog.md 12.8 KB
      Loading…
  • SKILL.md 10.9 KB
    ---
    name: metricsql
    description: >-
      VictoriaMetrics MetricsQL query language as a PromQL superset: rollup extensions, behavioral
      differences from PromQL (rate/increase semantics, implicit conversions, auto-aligned subqueries),
      label manipulation, WITH templates, keep_metric_names modifier, multiple-or filters, and query
      API enhancements. Invoke whenever task involves any interaction with MetricsQL or VictoriaMetrics
      queries — writing, debugging, optimizing, migrating PromQL to VictoriaMetrics, or reviewing.
    ---
    
    # MetricsQL
    
    VictoriaMetrics PromQL superset. Syntactically backwards-compatible; **semantically different** for a subset of queries.
    Lead with the diffs — that's where users get burned. PromQL fundamentals live in the sibling `promql` skill; this covers
    only what PromQL doesn't.
    
    ## References
    
    - **Behavioral diffs from PromQL** — [`${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md`]
      `rate`/`increase`/`delta`/`changes` diffs, `_prometheus`-suffixed variants, scalar/instant-vector unification, NaN
      handling, name retention, implicit conversions, auto-aligned subqueries, `default_rollup` lookback, staleness markers.
    - **MetricsQL-only extensions** — [`${CLAUDE_SKILL_DIR}/references/extensions.md`] Rollup family, `WITH` templates,
      multiple-`or` filters, `default`/`if`/`ifnot` ops, `group_left(*) prefix`, `keep_metric_names`, `[Ni]` step, numeric
      suffixes, aggregate `limit N`, `boundsLabel`, fractional durations, Graphite, multi-line.
    - **Full function catalog** — [`${CLAUDE_SKILL_DIR}/references/functions-catalog.md`] All rollup, transform,
      label-manipulation, aggregate functions by category, with PromQL/MetricsQL provenance.
    - **Query API enhancements** — [`${CLAUDE_SKILL_DIR}/references/api-enhancements.md`] `extra_label`, `extra_filters[]`,
      `round_digits`, `limit`, timestamp formats, `stats` response, cluster vmselect URL layout, multi-tenancy.
    
    Read the relevant reference before proceeding.
    
    ## What MetricsQL Is
    
    - **Strict syntactic superset** of PromQL — every valid PromQL parses as MetricsQL.
    - **Not** semantic superset — `rate`, `increase`, `delta`, `changes` differ.
    - `_prometheus`-suffixed variants give byte-parity: `rate_prometheus`, `increase_prometheus`, `delta_prometheus`,
      `changes_prometheus`.
    - Implemented by `vmselect` (cluster) or single-node binary; exposed via standard `/api/v1/query` and
      `/api/v1/query_range`.
    
    ## The Five Behavioral Diffs That Bite
    
    1. **Lookbehind anchor.** `rate`/`increase` use the **last sample before** the window for the first delta; Prometheus
       doesn't. For `increase(metric[$__interval])` on a slow counter, Prometheus loses one delta per window. Use
       `rate_prometheus`/`increase_prometheus` for parity.
    2. **No extrapolation.** Returns actual measured delta; Prometheus extrapolates to window edges, producing fractional
       results from integer counters. Affects alerts comparing `increase()` to integer thresholds.
    3. **Scalar = instant vector without labels.** Prometheus's scalar/instant-vector distinction collapses.
       `scalar(metric)` coercion rarely needed; arithmetic on aggregation results works.
    4. **NaN drop.** `(-1)^0.5` returns empty in MetricsQL; Prometheus returns a NaN series. Grafana renders identically;
       programmatic consumers see different shapes.
    5. **Metric names retained for safe functions.** `min_over_time(foo)`, `round(foo)`, `abs(foo)` keep `foo`. Prometheus
       strips.
    
    Full mechanics, edge cases, implicit-conversion pipeline, per-function table:
    [`${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md`].
    
    ## Lookbehind Window — Auto-Selection
    
    Omitting `[d]` is allowed:
    
    - `default_rollup` and `rate`: `max(step, scrape_interval)` — prevents gaps when `step < scrape_interval`.
    - All other rollups: `step` (`$__interval` in Grafana, `1i`).
    - `rate(node_network_receive_bytes_total)` ≡ `rate(node_network_receive_bytes_total[$__interval])`.
    
    **Silent** behavior change across panels with different steps. For alerting and recording rules, **always specify the
    window explicitly**.
    
    ## Implicit Query Conversions
    
    VictoriaMetrics rewrites every query before evaluation (unless `-search.disableImplicitConversion`):
    
    - Bare selectors → `default_rollup`: `foo` → `default_rollup(foo)`.
    - Selectors inside transform/aggregate get the same wrap: `abs(temperature)` → `abs(default_rollup(temperature))`,
      `count(up)` → `count(default_rollup(up))`.
    - Rollups on non-selectors become subqueries: `rate(sum(up))` → `rate((sum(default_rollup(up)))[1i:1i])`.
    - Subqueries with missing step get `1i`: `avg_over_time(rate(m[5m])[1h])` → `avg_over_time(rate(m[5m])[1h:1i])`.
    
    When debugging, mentally apply these first — the actual computation may differ from what was typed.
    
    Full conversion list with disable flags: [`${CLAUDE_SKILL_DIR}/references/behavioral-diffs.md`].
    
    ## The Rollup Family — MetricsQL-Only
    
    - **`rollup(m[d])`** — min/max/avg with `rollup="..."` label.
    - **`rollup_rate(m[d])`** — per-second rate min/max/avg over adjacent samples; better than `irate` for spike detection.
    - **`rollup_increase(m[d])`** / **`rollup_delta(m[d])`** / **`rollup_deriv(m[d])`** — same pattern.
    - **`rollup_candlestick(m[d])`** — OHLC.
    - **`aggr_over_time(("func1","func2",...), m[d])`** — multiple rollups in one pass.
    
    Pair with `keep_metric_names` to preserve the original name.
    
    ## keep_metric_names
    
    Functions and binary ops strip the metric name. This causes `duplicate time series` errors when distinct names collapse
    into the same label set. Suffix with `keep_metric_names`:
    
    - `rate({__name__=~"foo|bar"}) keep_metric_names`
    - `({__name__=~"foo|bar"} / 10) keep_metric_names`
    
    Available on all rollups, transforms, and binary operators.
    
    ## Multiple `or` in Series Selectors
    
    PromQL `{env="prod",job="a"}` is a single AND. MetricsQL adds top-level disjunction:
    
    ```text
    {env="prod",job="a" or env="dev",job="b"}
    ```
    
    Each `or`-group is an AND of matchers. Compose with comma within a group.
    
    Multi-constant matching: `status_code == (300, 301, 304)` returns series where `status_code` is any listed value.
    
    ## WITH Templates
    
    Reusable named subexpressions:
    
    ```text
    WITH (
      errs = rate(http_requests_total{status=~"5.."}[5m]),
      total = rate(http_requests_total[5m]),
    )
    sum(errs) by (job) / sum(total) by (job)
    ```
    
    String concat: `WITH (commonPrefix="my_app_") {__name__=commonPrefix+"errors_total"}`. Expanded at parse time.
    
    ## Binary Operators Beyond PromQL
    
    - **`q1 default q2`** — fills gaps in `q1` from `q2`.
    - **`q1 if q2`** — keeps `q1` where `q2` has a value (conditional masking).
    - **`q1 ifnot q2`** — keeps `q1` where `q2` has no value (inverse).
    
    Compose with `default`-on-missing: `(up{job="x"} default 0) == 0` reliably alerts on disappearing targets.
    
    ## group_left(\*) and Label Copy
    
    ```text
    kube_pod_info * on(namespace) group_left(*) prefix "ns_" kube_namespace_labels
    ```
    
    Copies **all** labels from right side except those in `on(...)`, prefixed with `ns_`. `group_right(*)` mirrors. Without
    `prefix`, collisions error.
    
    ## Aggregate `limit N`
    
    ```text
    sum(http_requests_total) by (path) limit 10
    ```
    
    Returns 10 paths total. Other series dropped silently. Distinct from `topk(10, ...)`: `limit N` is order-arbitrary;
    `topk` keeps the top by value.
    
    ## Grafana `$__interval` and `[Ni]` Syntax
    
    - `1i` = one step (Grafana `step` arg).
    - `[10i]` = lookbehind covering ten steps.
    - `offset 5i` = shift back five steps.
    - Works in rollup windows, offsets, subquery step: `rate(metric[10i] offset 5i)`.
    - Use over hard-coded durations so panels scale with the time range.
    
    ## Cluster Endpoint Structure
    
    ```text
    http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query
    http://<vmselect>:8481/select/<accountID>/prometheus/api/v1/query_range
    ```
    
    `<accountID>` is `accountID` or `accountID:projectID` (32-bit ints). Single-node uses unprefixed `/api/v1/query`.
    `/prometheus/` prefix is optional but explicit.
    
    Full URL layout (ingestion, federation, Graphite, vmstorage admin, vmalert proxy):
    [`${CLAUDE_SKILL_DIR}/references/api-enhancements.md`].
    
    ## Query API Enhancements
    
    - **`extra_label=<name>=<value>`** — adds `{name="value"}` to every selector. Repeatable. Used by auth proxies for
      tenant scoping.
    - **`extra_filters[]=<selector>`** — adds a full selector with regex support: `extra_filters[]={env=~"prod|staging"}`.
    - **`round_digits=N`** — rounds response values to N decimals.
    - **`limit=N`** on `/api/v1/labels`, `/api/v1/label/<name>/values`, `/api/v1/series`.
    
    Responses include `stats` with `executionTimeMsec` and `seriesFetched`. `seriesFetched` is approximate; vmalert uses it
    to flag never-firing rules.
    
    ## Syntax Conveniences
    
    - **Underscore in numbers** — `1_234_567_890` ≡ `1234567890`
    - **Numeric suffixes** — `8K` (8000), `1.2Mi` (1.2×1024²), supports `K Ki M Mi G Gi T Ti`
    - **Fractional durations** — `[1.5m]`, `offset 0.5d`
    - **Optional duration suffix** — `[300]` is seconds: `rate(m[300] offset 1800)` ≡ `rate(m[5m]) offset 30m`
    - **Duration anywhere** — `sum_over_time(m[1h]) / 1h` ≡ `sum_over_time(m[1h]) / 3600`
    - **Trailing commas** — `m{foo="bar",}`, `f(a, b,)`, `WITH (x=y,) x` all valid. Use in multi-line queries.
    - **Unicode in names** — `ტემპერატურა{πόλη="Київ"}` is valid
    - **Escape sequences** — `foo\-bar{baz\=aa="b"}`, `\xXX`, `\uXXXX`
    - **`@ modifier` anywhere** — `sum(foo) @ end()`, `foo @ (end() - 1h)`
    
    ## Histogram Extensions
    
    `histogram_quantile(phi, buckets, boundsLabel?)` — optional third arg returns `lower`/`upper` bounds in `boundsLabel`.
    For plotting quantile confidence intervals.
    
    `histogram_over_time(gauge[d])` produces VictoriaMetrics-format histograms from gauge values:
    
    ```text
    histogram_quantile(0.5, sum(histogram_over_time(temperature[24h])) by (vmrange,country))
    ```
    
    Computes quantiles over gauge distributions without re-instrumenting.
    
    ## Application
    
    When **writing**:
    
    - Omit lookbehind only when panel-wide `$__interval` is appropriate. Otherwise use `[5m]` or `[Ni]` explicitly.
    - For alerting/recording rules: **always specify the lookbehind window**. Implicit selection couples rule behavior to
      evaluation interval.
    - Prefer `default` over `or vector(0)` — more readable, handles labels correctly.
    - Use `rollup_rate` for counter spike detection over `irate` — min/max/avg in one query.
    
    When **migrating from Prometheus**:
    
    - Audit alerts comparing `increase()` to integer thresholds — exact integers may fire differently.
    - Use `*_prometheus` variants only when byte-parity is required (cross-backend SLO consistency).
    - Enable `-search.logImplicitConversion` to see rewrites.
    
    When **reviewing**:
    
    - Flag missing lookbehind windows in alerting/recording rules.
    - Flag `rate(sum(...))` — silent subquery formation.
    - Flag bare selectors in arithmetic — silent `default_rollup` wrap.
    - Cite the specific diff and show the fix inline.
    
    ## Integration
    
    **promql** — shared fundamentals (selectors, operators, aggregations, vector matching). This skill — MetricsQL
    extensions and diffs.
    
    **prometheus** — instrumentation; this skill — query-time behavior.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.