{"canonical_url":"https://engineer.company/glossary/feature-flag/","content_markdown":"# Feature flag\n\n## What it is\n\nA feature flag is a decision point in the code that reads a setting the team can\nchange without building the application again. Behind the flag sits a new code\npath that is already in production but stays dormant until the setting turns it\non, for everyone or for a chosen group of users. Pete Hodgson described the\ntechnique at length on Martin Fowler's site, in instalments from January 2016,\nwith a revision in October 2017. He calls them feature toggles and lists feature\nflags, feature bits and feature flippers as other names for the same thing.\n\nHodgson splits a flag into parts. The toggle point is the place in the code that\nasks whether the new path is on. The toggle router answers that question from\nthe toggle configuration and, when the answer depends on who is asking, from a\ntoggle context: usually the current user, or a special cookie or HTTP header\nthat stands in for one. He warns against coupling the two. The code at the\ntoggle point should ask a narrow question, such as whether this order\nconfirmation includes the new cancellation link, while the rule that decides it\nlives in one place behind the router, so it can change without touching every\ncall site.\n\nFlags differ in how long they live and how often their answer changes, and\nHodgson sorts them into four kinds. Release toggles let unfinished, untested\ncode ship to production as latent code; he says they \"should generally not stick\naround much longer than a week or two\". Experiment toggles split users into\ngroups for an A/B test, with each user placed in the same group every time. Ops\ntoggles let operators change how the system behaves in production. Many of them\nare short-lived, but a few long-lived kill switches let operators scale back\nfunctionality the system can do without when load is unusually high, such as a\nrecommendations panel that is expensive to generate; Hodgson likens these to a\nmanually managed circuit breaker. Permissioning toggles decide which features a\ngiven user sees, such as premium features for paying customers or alpha features\nfor the company's own staff, and they can stay for years.\n\nA feature flag is not a canary release, though the two often work together. A\ncanary runs two versions of a service side by side and routes a share of the\ntraffic to the new one; a flag ships one version that contains both paths and\npicks between them on each request. A long-lived branch in version control also\nkeeps new work apart, but the code then reaches production only when the branch\nis merged, all at once.\n\n## Why it matters\n\nThe main reason to use flags is to separate deployment from release. Hodgson\ndescribes release toggles as the most common way to put a Continuous Delivery\nprinciple into practice: the release of a feature is a separate step from the\ndeployment of its code. Code can go to production every day from a single main\nbranch while a month-long feature stays dark until it is ready, which is what\nmakes trunk-based development workable.\n\nBecause a flag can give different answers to different users, a release can be\nwidened in steps. Hodgson describes turning new features on first for internal\nusers, which he calls a Champagne Brunch, since the company gets to drink its\nown champagne first. A canary cohort comes next: his example is a random 1 per\ncent of users, chosen with a modulo of the user ID so that the same people stay\nin the group, while the other 99 per cent keep the old behaviour. If that cohort\nreports problems, the flag goes off and nobody has to roll back a deployment.\n\nAll of this has a price. Every flag adds a branch to the code and a combination\nto test, and the configuration behind it becomes a part of production that can\nchange without a build. Hodgson's advice is to keep toggle configuration in\nsource control and change it through re-deployments wherever the flag allows it,\nso that the configuration moves through the same pipeline as the code and\nchanges to it are reviewed and recorded. Flags that must change within minutes,\nsuch as ops toggles, are where runtime configuration earns its keep.\n\n## What it looks like in practice\n\nflagd is an open-source flag evaluation engine that follows the OpenFeature\nspecification. It has no user interface and stores nothing of its own; it reads\nflag definitions from a JSON file or another source and answers requests, either\nas a sidecar, inside the application process or as a central service. A flag\nthat sends about one user in twenty to a new checkout looks like this:\n\n```json\n{\n  \"$schema\": \"https://flagd.dev/schema/v0/flags.json\",\n  \"flags\": {\n    \"new-checkout\": {\n      \"state\": \"ENABLED\",\n      \"variants\": {\n        \"on\": true,\n        \"off\": false\n      },\n      \"defaultVariant\": \"off\",\n      \"targeting\": {\n        \"fractional\": [\n          [\"on\", 5],\n          [\"off\", 95]\n        ]\n      },\n      \"metadata\": {\n        \"owner\": \"checkout\",\n        \"expires\": \"2027-01-31\"\n      }\n    }\n  }\n}\n```\n\nEach flag has a state and a set of variants that must all be of one type; the\ndefault variant is optional. The `fractional` rule splits users into buckets by relative\nweight, so 5 and 95 put about one user in twenty on `on`. By default the bucket\nis computed from the flag key and the `targetingKey` in the evaluation context,\nwhich means the same user always gets the same answer, and that renaming the\nflag reshuffles everyone. `metadata` holds whatever the team wants to attach to\nthe flag, here an owner and the date by which it should be gone. Setting `state`\nto `DISABLED` makes flagd answer with no value at all, and the caller falls back\nto its own default.\n\nRunning flagd against the file and asking it for an answer over HTTP:\n\n```sh\nflagd start --uri file:./flags.json\ncurl -X POST \"localhost:8013/flagd.evaluation.v1.Service/ResolveBoolean\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"flagKey\":\"new-checkout\",\"context\":{\"targetingKey\":\"user-4711\"}}'\n```\n\nThe reply carries the value, the variant and the reason `TARGETING_MATCH`. In\nthe application, the call goes through an OpenFeature client with the flag key,\na default value of `false` and the evaluation context, and the toggle point sees\nnothing more than true or false. Raising the share from 5 to 20 per cent is an\nedit to the flag file, not to the application build.\n\nThe\n[hiring and seafarer career workspaces](/portfolio/built-the-hiring-and-seafarer-career-workspaces/),\nfrom 2025, show a release flag in the recorded implementation snapshot: it\ndescribes the hiring side as live and the career workspace as feature-flagged\nand incompletely released. That is a historical snapshot, not a declaration of\nthe present deployment state. The\n[operator back-office](/portfolio/built-the-operator-back-office-for-the-platform/)\nfrom the same year is where flags like that get changed. Operators flip flags\nand turn a feature on for only some users from a screen, instead of an engineer\nediting the production database by hand, and each change is authorized and\nrecorded like any other action there.\n\n## Where it goes wrong\n\n**Flags that never leave.** A release flag that has done its job is pure cost: a\nbranch nobody needs, a path nobody tests and a setting someone may flip by\nmistake. Hodgson suggests treating flags as inventory that carries a cost, and\nkeeping that inventory small. His remedies include a removal task on the backlog\nthe moment a release flag is introduced, an expiry date, a time bomb that fails\na test or stops the application from starting once a flag outlives its date, and\na fixed limit on the number of flags, so that adding one means removing another.\nRemoving a flag means deleting the losing code path as well as the check.\n\n**An old flag given a new meaning.** On 1 August 2012, Knight Capital's\nautomated order router, SMARS, sent millions of orders into the market over 45\nminutes, and the firm lost more than $460 million. The SEC's order sets out how.\nNew code for the New York Stock Exchange's Retail Liquidity Program reused a\nflag, carried on incoming orders, that had once switched on Power Peg, a\nfunction Knight had stopped using in 2003 but never removed. The deployment\nmissed one server out of eight, so on that server the reused flag woke the old\nfunction. When staff then removed the new code from the other seven, the flag\nactivated Power Peg there too. Never give a retired flag a new meaning, delete\ndead code together with the flag that guarded it, and check that every server\nruns the same build before a flag goes on.\n\n**Combinations nobody tested.** Two flags give four combinations and ten give\nover a thousand; Hodgson calls it a combinatoric explosion. Testing all of them\nis rarely possible, so test the ones that can reach production: the current\nproduction configuration with the flags about to be released turned on, the\nfallback with those flags off, and, as many teams also do, everything on. A\nfixed convention helps: off always means the existing behaviour and on means the\nnew one.\n\n**A default nobody chose.** The OpenFeature specification says flag evaluation\nmust not throw. When something goes wrong, the call returns the default the\ncaller passed, the detailed form of the result carries an error code, and the\nclient should not write to the log either, because an application deployed\nbefore its flag is defined would otherwise flood the log with `FLAG_NOT_FOUND`.\nThat keeps the application running, but it also means a typo in a flag key\nsilently becomes the default for every user. Pass the old, safe behaviour as the\ndefault, and attach a hook, which is where the specification puts logging, to\ncount evaluations that end in an error and raise an alert when they appear.\n\n**Overrides anyone can set.** It is convenient to let testers force a flag on\nwith a special cookie, a parameter in the URL or an HTTP header. Hodgson points\nout that curious or malicious users can set the same override and change the\nstate of a flag for themselves. Honour overrides only on internal traffic, or\nsign them cryptographically, which eases the concern but, as Hodgson notes, adds\ncomplexity and attack surface of its own.\n\n## Further reading\n\n- [Feature Toggles (aka Feature Flags)](https://martinfowler.com/articles/feature-toggles.html)\n  — Pete Hodgson's article on Martin Fowler's site: the parts of a toggle, the\n  four categories, testing and keeping the inventory small.\n- [Flag Evaluation API](https://openfeature.dev/specification/sections/flag-evaluation/)\n  — the OpenFeature specification for evaluating a flag, including defaults,\n  error codes and why evaluation never throws.\n- [flagd: Flag Definitions](https://flagd.dev/reference/flag-definitions/) — the\n  JSON format flagd reads: state, variants, default variant, targeting and\n  metadata.\n- [flagd: Fractional Operation](https://flagd.dev/reference/custom-operations/fractional-operation/)\n  — deterministic percentage splits and what decides which bucket a user lands\n  in.\n- [In the Matter of Knight Capital Americas LLC](https://www.sec.gov/files/litigation/admin/2013/34-70694.pdf)\n  — the SEC's 2013 order on the August 2012 trading loss, including the reused\n  flag.\n\n\u003chttps://engineer.company/glossary/feature-flag/\u003e\n","date_modified":"2026-11-09T21:50:25Z","description":"A runtime switch that separates shipping code from releasing it: the kinds of flag, how one is evaluated, and the debt that flags build up.","formats":{"gemtext":"https://engineer.company/glossary/feature-flag/index.gmi","gopher":"https://engineer.company/glossary/feature-flag/gophermap","html":"https://engineer.company/glossary/feature-flag/","json":"https://engineer.company/glossary/feature-flag/index.json","markdown":"https://engineer.company/glossary/feature-flag/index.md","pdf":"https://engineer.company/glossary/feature-flag/index.pdf"},"kind":"page","language":"en","title":"What is a feature flag?","url":"https://engineer.company/glossary/feature-flag/","version":1}