Skip to main content

Deep dive into consistent hashing, percentage rollouts, variant distribution, and evaluation internals

Last updated November 14, 2026

Advanced Evaluation

This guide covers the internals of Flaggr's evaluation engine — how consistent hashing works, how variants are distributed, and how to design robust rollout strategies.

Evaluation Pipeline

Every flag evaluation follows this sequence:

1

Disabled Check

If the flag is disabled, return defaultValue with reason DISABLED. No further evaluation occurs.

2

Identity Overrides

If an override lists the context's targetingKey, return the override's value with reason OVERRIDE. Overrides are checked from the highest priority down.

3

Prerequisites, Mutual Exclusion and Experiments

On flaggr.dev only. A prerequisite flag that doesn't return its expected value gives defaultValue with reason PREREQUISITE_FAILED. A flag blocked by its mutual exclusion group gives defaultValue with reason MUTUAL_EXCLUSION. A running experiment on the flag assigns its variant (reason EXPERIMENT) when the context has a targetingKey. The data plane at api.flaggr.dev skips this step.

4

Targeting Rules

Rules are evaluated top-to-bottom. The first rule whose conditions match wins. It returns the rule's value (the flag's defaultValue when the rule has none), labelled with the rule's variant if it names one, with reason TARGETING_MATCH.

5

Rollout Check

If a matching rule has rolloutPercentage (a whole number from 0 to 100), the user's hash determines inclusion. If excluded, evaluation continues to the next rule. A rule without one, or with null (how the data plane writes an unset percentage in /api/flags/export and its streams), serves every user it matches. The @flaggr/sdk 0.4.0 script-tag bundle evaluating locally skips a rule whose percentage is null instead, which it meets only in a bootstrap built from the data plane's flags (it can't stream from api.flaggr.dev); 0.5.0 serves it.

6

Variant Selection

If the flag has variants with weights, consistent hashing selects one. Returns with reason VARIANT.

7

Default Value

If nothing matched, return defaultValue with reason DEFAULT.

Consistent Hashing

Flaggr buckets users with a 32-bit string hash of the targetingKey. flaggr.dev, the data plane at api.flaggr.dev and @flaggr/evaluator from 0.3.0 use the same hash, so the same user always gets the same result for the same flag. @flaggr/evaluator 0.2.0 hashes differently and ignores rollout percentages and identity overrides, so evaluating locally with it can give a user a different result.

How It Works

// A targeting rule's rollout percentage
bucket = hash(flagKey + ":rollout:" + targetingKey) % 100   // 0-99
included = bucket < rolloutPercentage

// Variant weights
bucket = hash(flagKey + targetingKey) % 100                // 0-99

The hash multiplies by 31 and adds each Unicode code point (((h << 5) - h) + c), wrapping to 32 bits, and takes the absolute value:

function hashString(str: string): number {
  let hash = 0
  for (const c of str) {
    hash = (hash * 31 + c.codePointAt(0)!) | 0 // wrap to a 32-bit integer
  }
  return Math.abs(hash)
}

Properties

  • Deterministic: Same input always produces the same output
  • Uniform: Buckets 0-99 are evenly distributed across users
  • Stable: Changing the rollout percentage from 10% to 20% includes the original 10% plus 10% more — no users are removed
  • Independent: Each flag has its own hash space (different flags, different assignments), and a rule's rollout bucket is hashed apart from the variant bucket
Always Include targetingKey

Without targetingKey in the evaluation context, a rule with a rollout percentage below 100 never includes the user, and weighted variants, identity overrides and experiments don't apply. The @flaggr/sdk 0.4.0 script-tag bundle evaluating locally is the exception for rollouts: it puts every context without a targetingKey in the same bucket, so such a rule includes all of them or none (0.5.0 leaves them out). Rules without a rollout percentage still match on their conditions; otherwise the user gets the flag's default value.

Percentage Rollouts

Basic Rollout

A 25% rollout to all users:

{
  "targeting": [
    {
      "id": "gradual",
      "conditions": [
        { "property": "targetingKey", "operator": "not_equals", "value": "__flaggr_rollout_match_all__" }
      ],
      "rolloutPercentage": 25,
      "value": true
    }
  ]
}

The condition above matches every user, with or without a targetingKey: it's the console's Everyone, which rollout plans use too. A rule with no conditions matches everyone as well on flaggr.dev and in @flaggr/sdk local evaluation from 0.5.0, but a data plane from before Flaggr 0.5.0 and local evaluation before 0.5.0 match it to nobody, so the condition is the form that works on every version.

Targeted Rollout

25% of enterprise users only:

{
  "targeting": [
    {
      "id": "enterprise-canary",
      "conditions": [
        { "property": "plan", "operator": "equals", "value": "enterprise" }
      ],
      "rolloutPercentage": 25,
      "value": true
    }
  ]
}

Progressive Rollout Strategy

1

Internal Dogfood (1%)

Deploy to internal team members first. Use a targeting rule matching @yourcompany.com emails.

2

Canary (5%)

Expand to a small percentage of real users. Monitor error rates and latency.

3

Early Access (25%)

Increase the rollout percentage. Check business metrics and user feedback.

4

General Availability (100%)

Remove the rollout percentage to serve all users. Clean up the feature flag once stable.

Variant Distribution

For A/B testing and multi-way experiments, use variants with weights:

{
  "variants": [
    { "name": "control", "value": "classic-checkout", "weight": 50 },
    { "name": "treatment-a", "value": "new-checkout", "weight": 30 },
    { "name": "treatment-b", "value": "express-checkout", "weight": 20 }
  ]
}

Selection Algorithm

bucket = hash(flagKey + targetingKey) % 100   // e.g., 73

Variant ranges:
  control:     0-49  (50%)
  treatment-a: 50-79 (30%)
  treatment-b: 80-99 (20%)

73 falls in treatment-a → user gets "new-checkout"

Weights are cumulative. The algorithm iterates through variants, accumulating weights until the hash bucket is covered.

Weight Sum

Variant weights are whole numbers from 0 to 100 (the API refuses others with 400) and should sum to 100. If they sum to less, users whose bucket is past the last weight get the first variant. If they sum to more, the variants at the end of the list get less than their weight, or none.

Combining Variants with Targeting

Force specific users into specific variants:

{
  "targeting": [
    {
      "id": "force-enterprise-control",
      "conditions": [
        { "property": "plan", "operator": "equals", "value": "enterprise" }
      ],
      "value": "classic",
      "variant": "control"
    }
  ],
  "variants": [
    { "name": "control", "value": "classic", "weight": 50 },
    { "name": "treatment", "value": "new", "weight": 50 }
  ]
}

Enterprise users always get classic, reported as variant control. Everyone else is split 50/50. A rule serves its value (or the flag's default value without one); variant only names the result, so give the rule the variant's value too. The console's Return Variant and MCP add_targeting_rule with variant do that for you.

Evaluation Reasons

Every evaluation returns a reason field explaining how the value was determined:

ReasonDescriptionTypical Cause
DISABLEDFlag is disabledenabled: false
OVERRIDEAn identity override appliedThe targetingKey is listed in an override
PREREQUISITE_FAILEDA prerequisite flag didn't return its expected value (flaggr.dev only)Prerequisite disabled or targeted differently
MUTUAL_EXCLUSIONBlocked by its mutual exclusion group (flaggr.dev only)Another flag in the group is on
EXPERIMENTA running experiment assigned the variant (flaggr.dev only)Experiment running on the flag
TARGETING_MATCHA targeting rule matchedConditions satisfied (and inside the rule's rollout percentage)
VARIANTSelected via variant weightsHash-based assignment
DEFAULTNo match, default value usedNo rules matched
NOT_FOUNDFlag doesn't exist (FLAG_NOT_FOUND on api.flaggr.dev)Typo in flag key, wrong service
ERROREvaluation errorInvalid context, storage failure
CACHEDServed from cacheCache TTL still valid
STATICStatic/hardcoded valueFile provider or bootstrap

Debug Information

The evaluation API returns timing data in the _debug field:

{
  "flagKey": "checkout-v2",
  "value": true,
  "reason": "TARGETING_MATCH",
  "_debug": {
    "timings": {
      "rateLimit": 2,
      "validation": 1,
      "cacheGet": 0.5,
      "evaluate": 3,
      "total": 12
    },
    "cacheHit": false,
    "totalMs": 12
  }
}

Use this to diagnose slow evaluations. Typical healthy values:

  • Cache hit: total under 5ms
  • Cache miss: total under 50ms

Type Safety

Flaggr enforces type matching between flags and evaluations:

Flag TypeAllowed Default ValuesExample
booleantrue, falseuseBooleanFlag('dark-mode', false)
stringAny stringuseStringFlag('theme', 'light')
numberAny numberuseNumberFlag('max-items', 10)
objectJSON objectuseObjectFlag('config', {})

If the evaluated value doesn't match the expected type, the SDK returns the default value with reason ERROR.