1. LandOffer
  2. Blog
  3. All articles
  4. Roll Out a Feature Flag with Targeting, Metrics, and a Stop Condition

Engineering Practice

Roll Out a Feature Flag with Targeting, Metrics, and a Stop Condition

Define feature eligibility, stable workspace assignment, exposure metrics and stop authority before increasing a percentage. Use a complete fictional rollout packet and an explicit failed-guardrail record, with actual local model checks and recovery limits.

9 min readLandOffer team

Roll out a feature flag by defining who is eligible, how assignment stays stable, what evidence permits expansion and who can stop exposure. Deploying code and enabling its behavior are separate changes. A small percentage helps only when the application evaluates the intended rule and the team can inspect actual exposure. Write the off-path and stop procedure before opening the first stage.

This LandOffer.ai guide builds an original fictional workspace-targeted rollout and a completed stop record. Primary documentation was checked October 27, 2026. All product traffic, people and decisions are invented. We executed a pure Python targeting and arithmetic model with synthetic contexts; no flag provider, SDK, customer application, telemetry system or production rollout was operated.

Two adults adjust a hinged decorated screen while a third reads an open folio in a museum gallery.

Define the behavior and preserve the off-path

The fictional product Waymark displays project lists. Flag grouped-project-list exposes a new read-only layout that groups existing projects under category headings. The old flat list remains supported in the same deployed application. The flag does not change project membership, authorization, stored categories or schema, and it is not a permission mechanism.

Engineer Leif owns implementation and configuration; product owner Saskia authorizes stage expansion. On-call owner Eamon may stop new exposure without waiting for a meeting. Analyst Bina defines event completeness and denominators. Those assignments are part of this teaching case; actual owners must accept the work and have the required access.

The team must verify both layouts before exposure, including keyboard navigation and projects without categories. It must also verify that disabling the flag selects the old path for new evaluations. Existing browser state, cached decisions and in-flight requests may behave differently. Writing a kill-switch procedure is not evidence that propagation or recovery works.

The change is deliberately read-only. Turning off another flag cannot undo a sent notification, a payment or a destructive migration. If a feature produces durable effects, its recovery design must account for those effects separately from flag evaluation.

Decide the assignment unit before choosing a percentage

LaunchDarkly's percentage-rollout documentation describes context-based assignment and the importance of the context kind and attribute. The configured fraction concerns those contexts, not necessarily people, sessions or requests. It also documents behavior for mismatched context kinds that may differ from an assumed default.

Waymark chooses stable workspace identity so eligible colleagues in one workspace receive the same layout. Per-request assignment would let the interface change during routine use. Per-user assignment would split collaborators inside one workspace. Neither is inherently wrong, but both would answer a different product question.

Eligibility is evaluated before the percentage split: production environment, supported client version 4.2.0 or later, a nonempty workspace identity, the fictional pilot region north and the user's existing right to view that workspace. Unsupported or missing context selects the old layout. The authorized server-side source supplies the region and workspace; arbitrary browser attributes cannot grant access.

Unleash's activation-strategy documentation distinguishes constraints within a strategy from multiple strategies: all constraints must match within one strategy, while another enabled strategy can independently activate the flag. That provider-specific rule illustrates why a broad internal-user override can accidentally bypass a carefully constrained audience. Inspect the actual rule combination rather than assuming every visible condition is mandatory.

Before exposure, Leif writes concrete rule checks: an eligible workspace retains its result for two colleagues; an unsupported client or missing workspace remains on the old path; and emergency off defeats every allowed audience. Record the exact configuration and SDK version for real checks. A later rule change can alter the assignment even when the displayed percentage stays the same, so preserve the old rule and review the membership difference rather than describing that change as a routine percentage increase.

Worked asset: the complete stage and measurement packet

The following packet is a fictional configuration proposal, not an exported provider setting. Its numerical gates are authored operational choices, not recommended universal thresholds. No automated time-based expansion is enabled.

Field Completed agreement for Waymark
Flag and default grouped-project-list; off selects the existing flat layout. Emergency off takes precedence over every targeting route
Eligibility and assignment Required environment, supported client, workspace, region and access constraints; stable workspace bucket with unchanged salt and identity
Preparation stage Nonproduction checks using five internal fixture workspaces; no customer-traffic inference from that sample
First exposure stage Ten percent of eligible workspace buckets in one approved region; stage review requires complete coverage and an owner decision
Proposed next stage Twenty-five percent of the same eligible buckets, retaining prior assignments where the monotonic rule applies. Not authorized automatically
Observation opportunity A complete 30-minute review window with at least 100 new-layout view attempts, including at least ten empty-category attempts. Empty-category attempts are a subset
Error stop New-layout view failures greater than two percent in a complete window with at least 50 new-layout attempts; no wait for the advancement sample once this stop rule applies
Immediate stop Any confirmed project omission, unauthorized content exposure or comparably serious correctness issue invokes Eamon's stop route immediately
Missing evidence Telemetry more than five minutes stale, missing variation labels or absent required-path coverage prohibits advancement; owner assesses whether exposure should continue
Ownership Bina checks evidence; Saskia authorizes expansion; Eamon may stop; Leif investigates targeting and layout behavior
Recovery boundary Select old layout for new evaluations through the approved off procedure; independently inspect propagation, existing sessions and user impact

The stage duration is a review opportunity, not an automatic pass after half an hour. An empty-category case may reveal behavior ordinary lists never exercise. Good aggregate numbers with no relevant examples do not satisfy that coverage requirement.

The percentage also does not guarantee an exact number of workspaces. Our original offline example hashes 200 synthetic workspace identities into 10,000 buckets using a documented SHA-256-based rule. The ten-percent threshold selects 19 workspaces, or 9.5 percent of that finite fixture; the 25-percent threshold selects 50. All 19 remain in the larger set when identity and salt stay unchanged.

That local rule is a teaching implementation, not the hashing algorithm of LaunchDarkly or Unleash. Its selected counts do not predict a real provider's assignment. The check establishes repeatability and nested membership only for this fixture and rule; it does not establish statistical representativeness or a universal exact-percentage property.

Measure actual exposure instead of flag evaluations alone

An evaluation event says a flag decision was requested. It does not establish that the user saw the new layout, loaded projects successfully or completed their work. Record the actual rendered variation and the operation outcome with an agreed event identity. Deduplicate repeated delivery of one event while retaining genuinely separate retry attempts under the chosen definition.

Here, a view attempt means one request to render the project list. A failure is an attempt that cannot render that list under a fixed error classification. Retrying creates another attempt. Bina records the flag configuration version, application version, workspace bucket, actual variation, request identity, outcome and event timestamp. Collection must follow the organization's approved privacy and retention rules.

Workspace assignment and attempt counts have different denominators. A few active workspaces can produce much more traffic than many quiet ones; keep workspace coverage and attempt volume visible together. A ten-percent workspace allocation therefore does not require exactly ten percent of view attempts in the new layout. Nevertheless, unexpected distributions deserve investigation for identity loss, targeting mistakes or instrumentation problems.

Compare the old and new paths during the same period where practical, retaining relevant workload context. Such a comparison can suggest a regression worth investigating. It does not by itself establish that the flag caused it. This packet uses a conservative absolute stop rule; it is not an A/B experiment or a statistically calibrated causal analysis.

One adult holds a hinged green nature display panel while another reads an open notebook beside museum cases.

Worked asset: a signal triggers a completed stop record

In the entirely fictional November 23, 2026 review window, 10:00–10:30 UTC, configuration v3 exposes the new layout to the planned bucket audience. The following counts are authored inputs, not observed application traffic or measurements produced by our local model.

Evidence field New grouped layout Existing flat layout
Distinct view attempts 100 900
Failed attempts 4 9
Failure rate 4.00% 1.00%
Empty-category attempts within total 12 110
Missing variation labels 0 0
Most recent telemetry age at review 1 minute 1 minute

The new path's failure rate is 4/100 = 4 percent, which exceeds the packet's two-percent limit. Its rate is three percentage points above the old path, but that difference is descriptive rather than a significance test. The new path has enough attempts for both the 50-attempt stop gate and the 100-attempt review requirement; its twelve empty-category attempts meet the separate ten-attempt coverage requirement.

Adequate coverage does not cancel a failed guardrail. Eamon records at 10:32 UTC: “Stop new grouped-layout exposure under the approved off procedure. The completed window meets the error-stop condition. Hold the proposed 25-percent stage. Leif owns investigation; Bina retains v3's labeled events. Empty-category handling is a hypothesis, not an established cause.”

Within the authored case, configuration v4 sets emergency off. The follow-up packet records twenty sampled new evaluations selecting the old layout. That is an invented illustration of the evidence an operator would collect, not a test performed here or proof that every client switched. Existing-session refresh and in-flight behavior remain unverified; the stop record does not say the incident is resolved.

Saskia retains the expansion hold. Leif accepts two hours of investigation, replacing a planned cosmetic-filter task, and Bina accepts one hour to reconcile the failed attempts and variation labels. A new candidate needs a new reviewed packet. Neither a fix, a return to ten percent nor the 25-percent stage is approved by this record.

Keep missing data and provider automation explicit

The local check also evaluates a separate hypothetical information failure: telemetry age six minutes, with otherwise favorable counts. It returns Hold, not Advance. This is a different scenario from the four-failure stop record. A missing measurement is not a zero-error observation, and an old healthy window cannot establish current health.

LaunchDarkly's guarded-rollout guidance documents monitoring and rollback behavior for that separate product capability, including specific handling of insufficient samples and sample-ratio mismatch. Those documented controls are not implied by an ordinary percentage rule. Waymark's packet uses named manual decisions, not an assumed automatic rollback subscription or a claimed account test.

Even an automated stop requires usable signals and a configured recovery action. Confirm who receives alerts, who can override a hold and where the reason is retained. An emergency off must win over broad allowlists, and the application must still enforce authorization independently of flag selection. A missing SDK context or configuration-fetch failure needs a reviewed fallback, not an accidental new-layout default.

For your next rollout, assemble the eligibility rule, stable assignment unit, labeled exposure evidence and stop authority before changing the percentage. More engineering guides are available from LandOffer.ai. Verify the real off-path and propagation before exposure. After a stop, attach the new-evaluation and existing-session findings separately before asking to resume or expand. Stopping further exposure and proving user recovery remain separate responsibilities.

Sources and Further Reading