Skip to main content

How to declare a required metric series

When you'd do this: when a metric series must exist (and optionally meet a value target or cover a named population) before a particular change — a release, a configuration change, anything you choose to name — is allowed to proceed.

A declaration names a metric series and the change it blocks until that series has a qualifying observation. One declaration record can carry up to four kinds of obligation together, which is why there's one shared screen for all of them rather than four separate ones:

  • Existence (FR-25.5) — the series must have at least one observation before a named capture-start point, or the named change is refused.
  • Comparability (FR-25.7) — observations must carry a declared set of dimensions, so a later comparison can't silently mix incompatible configurations.
  • Value Target (FR-25.9) — the most recent qualifying observation must satisfy an operator/ target pair (e.g. >= 0.90), which can only tighten over time via a reviewed "ratchet advance", never loosen except through a deliberately recorded rollback.
  • Coverage (FR-25.10) — every member of a named population (read from a second, "denominator" series) must have its own qualifying observation.
note

There is no menu link to this page yet — go to /declarationsList directly. Viewing is open to any org member; creating or modifying a declaration is System Administrator only — the "New Declaration" button and the waiver form are hidden (and separately refused server-side) for anyone else.

Step 1 — View existing declarations​

Go to /declarationsList. Optionally filter by Application. Each row shows the series name, which of the four types apply to it (tagged), its capture-start event, the change it blocks, and whether it's been waived.

Step 2 — Create a declaration​

Click New Declaration (/declarationCreate) — System Administrator only.

  1. Pick a Declaration Type: Existence Check, Value Target, Coverage Condition, or Comparability Dimensions. The form shows only the fields that type needs.
  2. Enter the Series Name. If a declaration already exists for that series (same application), your new condition is added to it rather than creating a second record — this is deliberate: existence, value-target, and coverage conditions on the same series are always the same declaration.
  3. For a new series, fill in:
    • Capture Start Event — what this obligation is tied to (documentary text)
    • Blocks Change — the name of the change this declaration gates. This is a free-text label, not a REQQA workflow stage — you choose the name, and whatever process checks check_blocking for that exact label is what actually enforces it.
    • Optionally: acceptable Metric Keys, Required Dimensions, a Producer, and a Monitoring Interval (days, after which a series with no new observations is reported as lapsed — informational only, it doesn't block by itself).
  4. Depending on the type you picked, also fill in:
    • Value Target: an operator (<=, <, >=, >, =), a numeric target, and an optional metric key to evaluate against a keyed observation rather than the series aggregate.
    • Coverage Condition: the Denominator Series — a second series whose most recent observation carries the population's member list.
    • Comparability Dimensions: a comma-separated list, which must include build_method.
  5. Click Save.

Step 3 — Check a declaration's status​

Click View on any row (/declarationView/<id>) to see:

  • Overall status: Satisfied, Blocked, or Waived, plus a Lapsed tag if the monitoring interval has elapsed with no recent observation
  • Each value condition's operator, target, observed value, and pass/fail (or Deferred if no qualifying observation exists yet — a deferred condition doesn't count as a failure)
  • Each coverage condition's status, coverage percentage, and missing members

Step 4 — Grant a waiver​

From the same view, if the declaration isn't already waived, fill in a Reason and click Grant Waiver. The waiver is recorded against your own account. A waived declaration reports as Waived everywhere, instead of Satisfied or Blocked — including in this view, in the "what gates a change" query, and in any export.

Result​

A single place where an analyst states, per series, what must be true before a named change can proceed — existence, configuration consistency, a value threshold, and population coverage — with status, waiver, and lapse all visible together.