Queries on materialize-monitoring Documentation

Overview

Mon, 01 Jan 0001 00:00:00 +0000

Queries as Code#

Monitoring queries are authored once as YAML under packages/queries/, validated against a project-owned JSONSchema, and rendered per backend query language. A query is written for PromQL first; the other engines are translations of the same definition, carried in the same entry.

The audience for this section is repo contributors — the people adding a panel, an alert, or a metric to the registry. The audience for the rendered queries is the operator reading a dashboard, so the descriptions attached to each query are end-user voice; see Dashboard Style Guidelines for that.

Authoring Alerts

Mon, 01 Jan 0001 00:00:00 +0000

Authoring Alerts#

An alert is written once, in the query registry, and becomes a rule through mz-monitoring-build gen-rules. An alert whose query is PromQL is installed as a PrometheusRule wherever it applies, and the Thanos ruler evaluates it. An alert whose query is LogQL is installed as a PrometheusRule labelled mzmon.materialize.cloud/flavor: logql, which the alloy-gateway writes into the Loki ruler, and the Loki ruler evaluates it. This page is the conventions a contributor follows when adding or changing an alert, and what the tooling checks on their behalf. Recording rules render through the same context and are Authoring Recording Rules. Where the alert goes once it fires is Alert Channels; why the stack is shaped this way is the alerting design doc.

Authoring Recording Rules

Mon, 01 Jan 0001 00:00:00 +0000

Authoring Recording Rules#

A recording rule is written once, in the query registry, under rules:, and becomes a rule through mz-monitoring-build gen-rules, beside the alerts. The chart installs it as a PrometheusRule, the Thanos ruler evaluates it, and its result travels back through the alloy-gateway into Thanos like any other metric. This page is the conventions a contributor follows when adding one, and what the tooling checks. The first recording rules are the normalized ext:* layer for the metadata database, and the external dependency design doc is why that layer exists. Authoring Alerts covers what the two kinds of rule share: the alerting context, its placeholders, and capability inference.

Datadog Translations

Mon, 01 Jan 0001 00:00:00 +0000

Datadog Translations#

Every query in packages/queries/ carries a datadogQuery alongside its promQL. They render side by side as tabs on Common Queries; this page is the conventions behind them, for whoever is adding or correcting one.

These are translations, not a tested dashboard set — there is no Datadog test environment in CI, so nothing here has been run against a real Datadog account. Treat them as a starting point you copy into a widget or monitor and correct, not as something that works unedited.