Metric Stability & Deprecation Policy¶

This page is the compatibility contract for the metrics this exporter exposes on /metrics. It states which metrics you can safely build dashboards and alerts against, what the 1.0 release promises (and deliberately does not promise), and how metric names, labels, and units will change after 1.0.

If you only read one thing: Stable metrics keep their names, labels, and base units across 1.x. Experimental metrics may change at any time. Everything else below is detail.

Stability tiers¶

Every metric family belongs to one of two tiers. A "family" is the group of metrics sharing a name prefix (e.g. meraki_ms_*). The authoritative, per-metric list lives in the generated Complete Metrics Reference; this page assigns each family a tier.

Stable¶

Stable families are covered by the 1.0 compatibility promise below. They are exercised against live hardware (MT, MR, MS) or are hardware-independent infrastructure/organization metrics with a settled contract.

Experimental¶

Experimental families are explicitly excluded from the 1.0 promise. Their names, labels, units, and existence may change in any release, minor or patch, without a deprecation window. Build production alerts against them at your own risk.

What 1.0 promises¶

For Stable metrics, within the 1.x series the exporter promises:

• Names are stable. A Stable metric will not be renamed within 1.x except through the deprecation process below (dual-publish, then removal in a later minor).
• Labels are stable and additive. Existing label keys on a Stable metric will not be removed or repurposed. New label keys may be added (see Labels are additive).
• Units are base-SI and stable. Values are exposed in Prometheus base units - bytes, seconds, joules, ratios 0-1 where applicable - and the unit of a Stable metric will not change under a fixed name. The deliberate, documented exceptions carry their unit in the name and are themselves stable: device memory in KiB (binary ×1024), link speed as _mbps, and the domain-native _mhz / _dbm radio units. Base-unit conventions and the _count / bare-plural / _total suffix meanings are defined in the Metrics Overview.
• Metric type is stable. A gauge stays a gauge, a counter stays a counter. _total suffixes denote genuine monotonic counters only.

What 1.0 does NOT promise¶

Even for Stable metrics, the following are explicitly not part of the contract and may change in any release:

• HELP / description text. The human-readable # HELP wording may be reworded, clarified, or corrected at any time. Do not parse or assert on HELP strings.
• Exact cardinality. The number of series a metric produces depends on your inventory (orgs, networks, devices, ports, SSIDs) and on cardinality-management behaviour, both of which may change. Do not assume a fixed series count.
• Experimental metrics. Everything in the Experimental tier above - names, labels, units, and existence.
• Label values. The set of possible values for a label (e.g. new product_type, status, or model strings) tracks the Meraki API and grows or changes as Meraki does.
• Presence of optional subsystems. Metrics that only appear when an opt-in feature is enabled (clients, webhooks) are present only under that configuration.

Labels are additive¶

New labels may appear on an existing Stable metric in a future release. This is a compatible change and is explicitly permitted by this policy:

• The meaning of an existing label will never silently change. If network_id means the network ID today, it will always mean the network ID.
• New label keys may be added to an existing metric to expose additional dimensions.

Name labels are not part of numeric series¶

Decision (settled contract). Mutable, human-readable name labels - org_name, network_name, device name, port_name, description, hostname, and similar - are dropped from numeric metric series and instead exposed on an id-keyed *_info join metric.

Why. A name is mutable: an operator renaming an organization, network, or port would otherwise change the label set of every affected series. In Prometheus that starts a new time series and orphans the old one, breaking rate() / increase() continuity and littering the TSDB with dead series on every rename. Keying numeric series by the stable ID and carrying the mutable name on a separate _info metric decouples "the measurement" from "the current display name", so a rename touches exactly one info series instead of the whole fleet.

How to get names back in a query. Join the numeric series to the info metric on the ID and pull the name across with group_left:

meraki_device_up
  * on (serial) group_left (name)
  meraki_device_status_info

The same pattern applies to organizations (on (org_id) group_left (org_name) meraki_org_info) and to clients, whose numeric series are ID-only and join to meraki_client_info. This mirrors the established info-join used for organization/device identity; the network-filter observability gauges in services/inventory.py already follow it (they deliberately omit network_name from their labels to avoid orphan series on rename).

Post-1.0 rename & deprecation process¶

After 1.0, a Stable metric is only renamed (or has a label renamed, or a unit corrected via a new name) through a dual-publish deprecation window:

1. Add the new name. The new metric is emitted alongside the old one. Both carry identical values.
2. Mark the old name deprecated. The old metric's # HELP text is prefixed with a DEPRECATED: note that names the replacement and the earliest release in which the old metric may be removed.
3. Dual-publish for at least one minor release. Both names are emitted together for a minimum of one full minor release (1.n → 1.n+1), giving consumers time to migrate dashboards and alerts.
4. Remove the old name in a later minor. Removal happens no earlier than the release named in the deprecation note, and never in a patch release.

Deprecations and removals are called out in the Changelog. Breaking metric changes that cannot follow this process are reserved for a future 2.0.

One-time pre-1.0 sweep¶

The metric surface underwent a single, deliberate, breaking rename-and-unit sweep immediately before 1.0 to establish clean, consistent, base-unit names before the compatibility promise takes effect. This sweep:

• corrected _total suffixes so they denote only true monotonic counters (windowed and snapshot gauges were renamed to _count / bare-plural forms, with any measurement window documented in HELP);
• converted non-base units to base-SI (bytes, seconds, joules), keeping only the documented exceptions (memory KiB ×1024, link-speed _mbps, radio _mhz / _dbm);
• standardised _percent and other unit suffixes; and
• moved mutable name labels off numeric series onto _info join metrics (above), and reduced client series to ID-only.