# Metricsql

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-xobotyi-cc-foundry-metricsql`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [xobotyi](https://agentstack.voostack.com/s/xobotyi)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [xobotyi](https://github.com/xobotyi)
- **Source:** https://github.com/xobotyi/cc-foundry/tree/master/plugins/grafana/skills/metricsql

## Install

```sh
agentstack add skill-xobotyi-cc-foundry-metricsql
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 :8481/select//prometheus/api/v1/query
http://:8481/select//prometheus/api/v1/query_range
```

`` 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==`** — adds `{name="value"}` to every selector. Repeatable. Used by auth proxies for
  tenant scoping.
- **`extra_filters[]=`** — 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//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.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xobotyi](https://github.com/xobotyi)
- **Source:** [xobotyi/cc-foundry](https://github.com/xobotyi/cc-foundry)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-xobotyi-cc-foundry-metricsql
- Seller: https://agentstack.voostack.com/s/xobotyi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.