FeatureSignals

Flag Health

Flag Health monitors the lifecycle of every feature flag in your project, surfacing stale flags, flags approaching expiration, flags with no evaluations, and flags with elevated error rates — so you can keep your codebase clean and your flag debt low.

What is Flag Health?

Feature flags are meant to be temporary. Over time, flags that are never cleaned up accumulate as technical debt — cluttering your codebase, slowing down evaluation, and increasing the risk of accidental exposure. Flag Health provides automated analysis of every flag in your project to help you identify and remediate problematic flags before they become liabilities.

Health Indicators

Each flag receives health scores across several dimensions. Flags with issues are surfaced in the Flag Health dashboard with specific, actionable recommendations:

Stale Flags

Flags that haven't been evaluated in the configured time window (default: 30 days). Stale flags may indicate features that have been fully rolled out and whose flags were never removed from the code.

Recommended Actions

  • Verify the feature is fully released and stable
  • Remove the flag from your codebase
  • Archive the flag in FlagEngine

Zombie Flags

Flags that are permanently ON or OFF in all environments (100% rollout or 0%) and haven't changed state in 60+ days. These are flags that have effectively become dead code — the flag check in your code always returns the same value.

Recommended Actions

  • Remove the flag check from your code — it no longer serves a purpose
  • Delete the old code path that's no longer reachable
  • Archive the flag in FlagEngine

No Evaluations

Flags that exist in FlagEngine but have never received a single evaluation request. These may be newly created flags that haven't been deployed yet, or abandoned experiments.

Recommended Actions

  • Check if the flag is referenced in your codebase
  • If the flag is for a future feature, set an expiration date as a reminder
  • If the flag is abandoned, archive it

Approaching Expiration

Flags with an expiration date set within the next 7 days. Expiration dates are optional metadata you can set on any flag to remind your team to clean it up by a target date.

Recommended Actions

  • Review whether the feature rollout is on track
  • Extend the expiration if more time is needed
  • Begin cleanup if the feature is fully released

High Error Rate

Flags where more than 1% of evaluation requests result in errors. This may indicate a misconfigured flag, a broken SDK integration, or a flag referencing a deleted segment.

Recommended Actions

  • Check the Target Inspector to see if the flag evaluates correctly
  • Verify that referenced segments and prerequisites still exist
  • Review SDK logs for detailed error messages

Using the Flag Health Dashboard

The Flag Health dashboard is accessible from the sidebar under Health. The dashboard provides:

  • Health summary — Total counts by health category: healthy, stale, zombie, no evaluations, expiring, and error flags.
  • Flag list — Sortable, filterable list of all flags with their health status. Click any flag to see detailed health information and recommendations.
  • Trend charts — See how your flag health has changed over time. A growing number of stale flags indicates a cleanup gap.
  • Bulk actions — Archive multiple stale or zombie flags in one operation, or extend expiration dates in bulk.

Health Score

Each flag receives a composite Health Score from 0 to 100, calculated from the indicators above. The score helps you prioritize which flags to address first:

80–100Healthy
50–79Needs Attention
0–49At Risk

Best Practices for Flag Hygiene

Set expiration dates on every flag

When you create a flag, set an expiration date 30–60 days out. This creates a forcing function to either clean up the flag or consciously extend it. Flags without expiration dates tend to live forever.

Archive flags as soon as they're removed from code

The flag removal process isn't complete until the flag is archived in FlagEngine. An archived flag still appears in audit logs but is hidden from active lists and always returns its default value.

Review Flag Health weekly

Make flag health review part of your team's weekly routine. Five minutes a week prevents months of accumulated flag debt. The AI Janitor can automate this review with scheduled PRs.

Next Steps