Skip to main content

Metrics & the Metric Catalog

Everything in Lumetry starts with a metric — a named, numeric time series such as payments.api.latency.p95 or database.sessions.active. This page explains what a metric is, how Lumetry catalogs it, who owns its collection, and the lifecycle states that decide whether a rule is allowed to evaluate it.

Metric points and metric keys​

A single observation is a metric point: a metric name, a timestamp, a numeric value, an optional namespace and source, and optional key/value labels.

metric_name = "demo.api.response.duration.ms"
timestamp   = 2026-06-02T09:00:00Z
value       = 214
labels      = { "instance": "mbl-web-07", "region": "eu" }

The metric key is the stable string identity of a series. It is the join key across the whole system: it is what the metric store records as its series name, what a metric definition is registered under, what a rule binds to, and what a topology metric-binding references. Metric keys are source-facing strings, deliberately not numeric IDs, because they have to match the names your data pipelines already emit.

The Metric Catalog​

The Metric Catalog (also called the Metric Registry in the UI) is the unified list of metric definitions — the metadata Lumetry knows about each series. A definition carries:

FieldMeaning
metricKeyStable identity, matches the stored series name.
displayName, description, unitHuman-facing metadata.
metricTypegauge, counter, or histogram.
namespaceLogical grouping for organization and filtering.
metadataFree-form JSON for custom attributes.
entityType / entityIdentifierThe kind of thing this metric describes (e.g. HOST, DATABASE, SERVICE) and which instance.
managementModeWho collects the data — see Ownership.
catalogSourceWhere the metadata came from (postgres, mssql, mysql, oracle, prometheus, thanos, manual, api, nifi, agent, …).

A definition is the catalog record for a metric. The actual values live in the metric store; the definition describes and governs them.

Why a catalog at all? In a large estate you have thousands of series with no owner, no description, and no agreed unit. The catalog is where a metric becomes a first-class, governed object you can attach rules, entities, and topology to.

Ownership: who collects the data?​

Every definition declares a managementMode that answers a single question — does Lumetry pull this data, or does something else push it?

  • LUMETRY_MANAGED — Lumetry actively collects the metric. The definition must point at a metric source and provide a sourceQuery and a polling interval. Lumetry runs the query on schedule and ingests the result.
  • EXTERNALLY_MANAGED — the data is already flowing into the metric store from some other pipeline (a Prometheus remote-write, an OTel collector, a custom agent). Lumetry never polls these; the definition stores metadata and identity only.

This distinction is deliberate: it lets Lumetry be both an active collector and a passive intelligence layer on top of telemetry you already produce, without the two models leaking into each other.

Metric sources​

A metric source is a connection to a system Lumetry can pull from. Sources have a type (POSTGRES, MSSQL, MYSQL, ORACLE, PROMETHEUS, or the Prometheus-compatible THANOS), a connection configuration, and a health status. LUMETRY_MANAGED definitions reference a source and supply the query to run against it.

Source execution is adapter-based: PostgreSQL, Microsoft SQL Server, MySQL, and Oracle adapters all expect a single-row, single-numeric-value result; Prometheus-style adapters normalize scalar/vector/matrix responses into labeled points. New adapter types can be added without changing the rest of the platform.

Source health is tracked continuously. When an enabled source stops responding, Lumetry raises a system alert so operators see the collection gap before they see missing data. Credential handling depends on the deployment: some installations resolve deployment-managed references, while others accept connection settings directly. Follow the secret-management policy supplied with your Lumetry environment.

The metric lifecycle: two independent statuses​

A definition carries two status fields that are frequently confused. They answer different questions and are owned by different parts of the system. Keeping them separate is one of Lumetry's core data-model decisions.

dataStatus — is there usable data?​

Owned by ingestion/collection. This is the one that controls evaluability.

ValueMeaning
NOT_ONBOARDEDNo local metric data has been confirmed yet.
INGESTINGOnboarding has started; data is beginning to arrive.
ACTIVELocal data is available — rules can evaluate this metric.
STALERecent data is missing (collection may have stopped).
ERRORCollection or ingestion failed.

Only dataStatus = ACTIVE metrics are evaluable by rules. A metric can exist in the catalog and still be ineligible for rule preview or creation until real data is confirmed in the metric store.

syncStatus — is the metadata fresh?​

Owned by catalog sync. It describes how current the metadata is, and says nothing about whether values are available.

ValueMeaning
NOT_SYNCED / SYNCING / SYNCED / STALE / ERRORThe freshness of the catalog metadata from its provider.

The rule of thumb: dataStatus is about values (the metric store). syncStatus is about metadata (the catalog). SYNCED does not imply data is available, and ACTIVE does not require a recent metadata sync.

Catalog hygiene: unregistered and silent metrics​

Two derived views help keep the catalog honest against reality in the metric store:

  • Unregistered metrics — metric names seen in the metric store within a lookback window that have no active definition. These are series flowing in that nobody has cataloged yet; an operator can register a definition for one directly from this view.
  • Silent metrics — active definitions whose latest stored point is missing or older than the lookback window. These are cataloged metrics that have stopped reporting — often the first visible sign of a broken collector.

Together they answer "what are we collecting that we haven't described?" and "what did we expect that stopped arriving?".

Multidimensional metrics​

A metric can be single (one series per key) or multidimensional (many series under one key, distinguished by labels — for example one http.requests.per2m series per instance in a fleet). Multidimensional metrics unlock per-dimension peer analysis; see Multidimensional (Fleet) Metrics.