Concepts
Flag Lifecycle and Status
Understand how Zenmanage derives each flag's status, what archiving actually does, and how staleness detection decides which flags are cleanup candidates.
Status is derived, not stored
There is no status field you set on a flag. Zenmanage computes each flag's status from things that are already true about it: whether it has been archived, whether a partial rollout is running in the environment you're looking at, and whether the flag is marked permanent. That means status can never drift out of sync with reality — it is reality, summarized.
Archived
The flag has been archived. This takes priority over everything else.
Partial rollout
A published target in this environment has an active or paused rollout below 100%.
Permanent
The flag is marked permanent — a long-lived control that is meant to stay in your code.
Temporary
The default. A release flag that should eventually be cleaned up once its feature is fully shipped.
The rules resolve in priority order — the first one that matches wins:
| Priority | Status | When it applies |
|---|---|---|
| 1 | archived | The flag has been archived, regardless of any other state. |
| 2 | partial_rollout | A published target in the environment carries an active or paused rollout under 100%. The in-flight rollout is the more operationally relevant signal, so it outranks the flag's own permanent or temporary attribute. |
| 3 | permanent | The flag's permanent attribute is set. |
| 4 | temporary | Everything else. Most flags spend most of their life here. |
Because the partial rollout check looks at published targets in a specific environment, status is resolved per environment. The same flag can be partial_rollout in production while showing temporary in staging, where the rollout already completed — or never started. When a rollout finishes or is completed at 100%, the flag drops back to permanent or temporary on its own. You can see the full picture for any environment in the Flag Status Overview report.
Archiving is a soft delete
Archiving a flag doesn't destroy anything. The flag record, its values, its targets, and its audit history all stay in place — the flag is simply marked as deleted and stops being part of the working set. It disappears from flag listings and from the environment payloads your SDKs download, so applications that still reference it in code fall back to the default value defined at the call site.
Archived isn't a separate lifecycle field you toggle through — it's the soft-deleted state itself, surfaced as a status. That's also why it's reversible in principle: the underlying record is still there, history intact.
Safe removal order
Archive first, remove code later. Once a flag is archived, every SDK evaluation of it serves the code-level default — so you can confirm production behaves correctly on defaults before you delete the flag references from your codebase. If something looks wrong, the flag can be brought back; a deleted code path can't.
The permanent attribute is an opt-out from staleness
Most flags are temporary by design: they exist to de-risk one release, and once the feature is fully shipped the flag should be cleaned up. Stale-flag detection is built around that assumption — which makes it wrong for flags that are supposed to live forever. Kill switches, operational load-shedding toggles, and plan-based entitlements may go months without changing and that's exactly what you want.
Marking a flag permanent is how you tell Zenmanage this on purpose. Permanent flags are excluded from the Stale Flags report and from stale-flag alert counts entirely — they will never be nominated for cleanup. The attribute does nothing else: evaluation, targeting, and rollouts all work identically. It is purely a lifecycle declaration.
Be deliberate about it
Only mark a flag permanent when its whole point is to stay. A release flag marked permanent to quiet an alert will sit in your codebase unnoticed indefinitely — the exact failure mode staleness detection exists to prevent.
How staleness is measured
Zenmanage tracks two different freshness signals for every flag, per environment, and the difference between them is the whole idea:
Retrieved
An SDK downloaded the environment payload containing this flag. This happens for every flag in the environment on every fetch — it proves an application is connected, not that the flag matters.
Used
Your code actually evaluated the flag. SDKs report this back automatically when a flag is checked; applications calling the API directly can report it through the usage endpoint. This is the signal that the flag still has a live call site.
A dead flag keeps being retrieved forever — it rides along in the payload as long as the environment has traffic. What stops is use. So staleness keys off the usage signal: a flag is stale when no evaluation has been reported in the window, even though it's still being retrieved constantly. Flags that have never been evaluated count as stale too, and sort to the top of the report — they're the strongest cleanup candidates of all.
The Stale Flags report lets you set the window to 30, 60, or 90 days (30 is the default). Each flag's detail view also shows the raw signals side by side — Last Retrieved, Last Used, and Last Updated — so you can judge an individual flag without waiting for a report to flag it.
Stale-flag alert emails
You don't have to remember to check the report. Each environment can opt into stale-flag alerts with its own threshold: when the number of stale flags in that environment meets the threshold, Zenmanage emails the account's owners and admins. Alerts are configured per environment on purpose — production traffic is the signal that matters, and a staging environment that only sees occasional traffic would otherwise cry wolf.
The alert uses the default 30-day window and, like the report, never counts permanent flags.
Where to go next
Flag types and default values are covered in Flags and Values, and the publishing states a target moves through are covered in Targets and Publishing States. For watching evaluation activity live while you debug, see the Debugging and Observability guide. To make flag cleanup a routine instead of a project, start from the Governance Checklist.