A flag that treats everyone alike is useful. A flag that treats the right people differently is far more powerful.

The limit of a simple switch

A basic feature flag has two answers: on for everybody or off for everybody. That is fine for a quick experiment or an emergency stop. But real products have many kinds of users. Some pay and some do not. Some live in India and some in Brazil. Some use the newest app and some use a version from two years ago. Some are employees testing, and some are customers paying their bills.

If every one of those groups must see the same thing, the team is forced into awkward choices. Either they delay a feature until it is ready for everyone, or they release it to everyone and hope. Neither is comfortable.

What teams really want

Teams want to say things like these, in plain language:

• “Show the new dashboard only to our own staff for now.”
• “Give premium customers a higher upload limit.”
• “Turn off the new payment screen for people on app versions older than 5.0.”
• “Release the feature in Canada first, because the support team there is ready.”
• “Let customers who signed up this month try the beta.”

Each sentence mentions a fact about the user: staff or not, plan, app version, country, signup date. Those facts are exactly what traits store.

Benefits in one glance

Before we add traits, we need to know the parts of Flagsmith that traits attach to.

Organisations, projects and environments

Flagsmith organises everything in three layers. An organisation is usually a company or a team. Inside it live projects, each normally one product. Inside each project are environments, such as Development, Staging and Production. A feature is a named switch defined once per project. What the switch does, whether it is on and what value it carries, is stored separately in each environment.

Remote configuration

A flag can also carry a value, such as a number or a piece of text. This is often called remote configuration. For example, a feature called “upload_limit_mb” might hold the number 25 for ordinary users and 100 for premium users. Segments can change that value for different groups.

What is an identity?

An identity in Flagsmith is a record that stands for one user of your product. It has an identifier, which is a string your system chooses, such as a customer number or a hashed email. Flagsmith uses the identifier to remember that user and give consistent answers across visits.

Identities belong to one environment. The same person has separate identity records in Development and in Production, because the environments are separate rooms.

flowchart TD
    ORG["Organisation"] --> PRJ["Project: Shopping App"]
    PRJ --> FEAT["Features: named switches"]
    PRJ --> SEG["Segments: reusable rules"]
    PRJ --> ENV["Environment: Production"]
    ENV --> FS["Feature states per environment"]
    ENV --> SO["Segment overrides per environment"]
    ENV --> ID["Identities"]
    ID --> TR["Traits: facts about each identity"]
    ID --> IO["Identity overrides"]

A map of ownership

A trait is the smallest and most important building block of targeting. Let us look at it closely.

A plain definition

A trait is a single named fact about an identity, written as a pair: a name and a value. For example: “plan” with the value “premium”, “country” with the value “IN”, “app_version” with the value “5.2.1”, “is_staff” with the value true, or “orders_count” with the value 14.

Parts of a trait

• Key. The name of the fact, such as “plan”. Keys should be consistent and clear.
• Value. The fact itself. It can be text, a whole number, a decimal number or a true-or-false value.
• Owner. The identity the fact belongs to.

Traits versus feature values

New learners sometimes confuse traits with flag values. The difference is simple. A trait describes the user and flows from your application to Flagsmith. A flag value describes what the feature should do and flows from Flagsmith to your application. One is the question’s input. The other is the answer’s output.

Examples of useful traits

A segment turns facts into groups. It is the reusable “rule of belonging”.

A plain definition

A segment is a named group of users defined by one or more rules. The rules look at traits and decide whether a user belongs to the group. If the facts match, the user is inside the segment. If not, the user is outside. Nobody puts users into a segment by hand. Membership is worked out automatically, every time it is needed.

Examples

• Premium Users: the trait “plan” is equal to “premium”.
• India Beta: the trait “country” is “IN” and the trait “beta” is true.
• Old App Versions: the trait “app_version” is lower than “5.0.0”.
• Heavy Shoppers: the trait “orders_count” is greater than 10.
• Staff: the trait “is_staff” is true.

Why segments are separate from flags

You define a segment once and reuse it across many features. If “Premium Users” appears in twenty flags, and one day the definition changes to include a new plan name, you edit one place. This is the same reason a company keeps one list of departments instead of copying it into every document.

Segments and environments

A segment definition belongs to the project, so every environment sees the same rules. But a segment override is stored per environment. It says: “In this environment, for users in this segment, give this feature this setting.” You can therefore have a segment override for Premium Users in production and none in development.

Traits supply the facts. Segments supply the rules. Flags supply the behaviour. Here is how the three fit.

The simple formula

Think of the whole system as three steps, repeated whenever an app asks for flags:

A tiny example

flowchart LR
    APP["App sends identity and traits"] --> FS["Flagsmith"]
    FS --> EVAL["Compare traits with segment rules"]
    EVAL --> IN{"Inside a segment?"}
    IN -- "Yes" --> OV["Use the segment override"]
    IN -- "No" --> DEF["Use the default feature state"]
    OV --> OUT["Personalised flags returned"]
    DEF --> OUT
    OUT --> APP2["App shows the right behaviour"]

Why this is better than hard-coding

Without this system, a developer would write rules like “if plan is premium and country is India then show the feature” inside the application. Each change would need a new release, and rules would be scattered across many files. With trait-based segmentation, the code only asks, “Is this feature on for this user?” and all the thinking lives in Flagsmith, where non-developers can adjust it safely.

A segment is only as good as the traits behind it. Let us look at all the ways traits reach Flagsmith.

Source 1: The application, through an SDK

An SDK, short for software development kit, is a small helper library that lets your app talk to Flagsmith. When the app asks for flags for a user, it can include traits in the same request. This is the most common route. It is quick and keeps traits fresh, because the app usually knows the latest facts, such as the app version or the language setting.

Source 2: Your backend

Many facts live in your servers and databases: plan, billing status, account age. A backend service can send these to Flagsmith, either when it asks for flags on behalf of a user or whenever a fact changes, for example when a customer upgrades.

Source 3: The dashboard

People can open an identity in the Flagsmith dashboard and add or edit traits by hand. This is useful for testing and for one-off cases. It is not a sensible way to maintain thousands of values.

Source 4: The API and bulk loads

Flagsmith exposes an API for creating identities and setting traits. Teams use it for bulk loads, nightly synchronisation from a customer database, or changes made by scripts.

Source 5: Computed on the spot

Some traits are not stored for long. The app may work them out at the moment of the request, such as the current time of day or the device type, and send them with that one request. Newer versions of Flagsmith support sending such values without saving them, sometimes called transient traits or transient identities. Check your version for how this works.

Choose one source of truth

For every trait, decide which system is the boss. If the billing system says a customer is premium, then every other system should copy that fact, never invent it. Two sources of truth for one trait produce two answers, and users see odd behaviour.

Small details about how a trait is typed and named decide whether a rule works or silently fails.

The common types

• Text. Words and codes, such as “premium” or “IN”.
• Whole numbers. Counts, such as 14 orders.
• Decimal numbers. Amounts or scores, such as 4.5.
• True or false. Yes-or-no facts, such as whether someone is staff.

Why types matter

Imagine a rule says “orders_count is greater than 10”. If one app sends 14 as a number and another sends “14” as text, comparisons may behave differently. Text is compared letter by letter, so the text “9” is larger than the text “10”, because the character 9 comes after the character 1. Flagsmith tries to interpret values sensibly, but you should not rely on that. Pick one type per trait, and always send that type.

Naming rules that save pain

Case and spelling traps

A trait named “Plan” and a trait named “plan” are different traits. A value of “Premium” and a value of “premium” may be different values, depending on the operator used. Pick one style, write it down, and make every app follow it.

Rules are where traits become decisions. Let us learn how to read and write them.

Anatomy of a rule

A segment is made of rules, and each rule contains conditions. A condition has three parts: a property, which is the trait name; an operator, which is the comparison; and a value, which is what to compare against. For example: property “plan”, operator “is equal to”, value “premium”.

Combining conditions

Rules can combine conditions in three ways:

You can also nest rules inside rules, so that “ALL of these, and ANY of those” can be expressed. A segment contains one or more top-level rules, and every top-level rule must be satisfied for the user to belong.

Common operators

Three small examples in words

A few kinds of rules behave differently from the plain comparisons. Knowing them avoids surprises.

Percentage splits

A percentage split rule picks a share of users, such as ten percent, without looking at any particular trait. It is the tool for gradual rollouts: ten percent today, thirty tomorrow, everybody next week. Flagsmith decides membership by turning the user’s identifier into a stable number, so the same user lands on the same side every time. Users do not flicker in and out of the group between visits.

Raising a percentage safely

Because the share is stable, raising it from ten to thirty keeps the original ten inside, and adds twenty more. This is what makes staged rollouts predictable. Lowering it removes users from the top of the range, which may suddenly take a feature away from some people, so plan communication for that.

Percentage splits combined with traits

A percentage rule can sit next to trait rules in an ALL group. For example, “country equals IN, and ten percent of users”. The result is ten percent of Indian users. This is the standard way to roll out regionally and gradually at once.

Versions

App versions look like numbers but are not: 5.10.0 is newer than 5.9.0, though as text “5.9.0” sorts after “5.10.0”. Comparing versions as plain text goes wrong. Newer Flagsmith versions offer a way to mark a comparison as a version comparison, often by adding a short marker to the value, so that version numbers are ordered correctly. If your version supports it, use it for every rule about app or software versions.

When a trait is missing

What if a user has no value for a trait, such as a brand-new user without a “plan” yet? Most comparison operators treat a missing trait as not matching. A rule “plan equals premium” will not match. A rule using “is not set” will match. A NONE group may match, because none of its conditions are true. Always ask: “What happens to someone who has no value here?” and test that case on purpose.

Unknown users

Users who have not signed in have no stable identity. You can still serve them flags through the environment’s general settings, or give them a temporary anonymous identifier. Be careful: if the anonymous identifier changes at every visit, percentage rollouts will give them a different answer each time.

To trust a system, it helps to know what it is made of. Here are the moving parts behind trait-based segmentation.

The building blocks

flowchart LR
    U["User"] --> APP["App with SDK"]
    BILL["Billing and Account Systems"] --> BE["Backend Service"]
    APP --> API["Flagsmith API"]
    BE --> API
    API --> ENG["Evaluation Engine"]
    ENG --> DB[("Database: features, segments, identities, traits")]
    ENG --> CACHE["Read Cache or Edge Layer"]
    CACHE --> APP
    ADMIN["Team in Dashboard"] --> API

Two kinds of traffic

Flagsmith handles two very different kinds of work. The first is flag reading: apps asking for flags, constantly, from many users. The second is management: people creating segments, editing rules and changing flags. Management happens a few times an hour. Flag reading may happen millions of times a minute. The two paths are designed to stay apart, so a busy dashboard never slows customers.

Where traits are stored

When an app sends traits with an identity, Flagsmith usually saves them against that identity in its database, so that the next visit starts with the same facts. This is called persisted traits. Server programs that use local evaluation may instead keep identities and traits in their own memory. We discuss that choice in a later chapter.

Let us follow a single request from an app, all the way to the personalised answer.

Step by step

sequenceDiagram
    participant U as User
    participant A as App with SDK
    participant F as Flagsmith API
    participant E as Evaluation Engine
    participant D as Database
    U->>A: Opens the app
    A->>F: Identify user with traits
    F->>D: Load identity and stored traits
    D-->>F: Identity and traits
    F->>E: Merge traits and evaluate segments
    E-->>F: Segments matched and winning overrides
    F->>D: Save updated traits
    F-->>A: Personalised flags
    A-->>U: Shows the right behaviour

The order of authority

When several settings could apply to the same feature, Flagsmith picks one using a fixed order. First, an identity override, a special setting for one named user. Second, the highest-priority segment override whose segment matches. Third, the environment default. Understanding this order explains most “why did I get this value?” questions.

Evaluation is repeated, not remembered

Segment membership is worked out every time flags are requested, from the latest traits. It is not stored as a list. This means that when a trait changes, say a customer upgrades to premium, the next request already reflects the new membership. No one needs to move the user between groups.

A segment on its own does nothing. It needs to be attached to a feature through an override.

What an override says

A segment override reads like a sentence: “For this feature, in this environment, for users in this segment, use this state and this value.” You can attach many overrides to one feature, each with its own segment.

Priority

One user can belong to several segments at once. A Premium user in India may match both “Premium Users” and “India Users”. If both have overrides for the same feature, Flagsmith needs a tie-breaker. Overrides are ranked, and the highest-ranked matching one wins. You can reorder the ranking in the dashboard.

flowchart TD
    START["Feature requested for a user"] --> Q1{"Identity override exists?"}
    Q1 -- "Yes" --> R1["Use the identity override"]
    Q1 -- "No" --> Q2{"Matches the top segment override?"}
    Q2 -- "Yes" --> R2["Use that segment override"]
    Q2 -- "No" --> Q3{"Matches the next segment override?"}
    Q3 -- "Yes" --> R3["Use that segment override"]
    Q3 -- "No" --> R4["Use the environment default"]

A worked example

A premium customer in India matches Premium Users and India Users. Premium has higher priority, so they receive 100. A staff member who is also premium receives 500. A free user in India receives 40. A free user elsewhere receives 25.

Identity overrides

Sometimes you want a special setting for exactly one person: a customer who is part of a pilot, or an executive who wants an early preview. An identity override gives that one identity its own setting for a feature, and it beats every segment. Use it sparingly, since individual exceptions are hard to track and easy to forget.

Order matters, so review it

Here is the usual path in the dashboard. Labels may vary a little between versions.

Before you begin

• Decide which fact you will use, and make sure an app or a backend actually sends it.
• Write the segment name and its purpose in one sentence.
• Check the trait catalogue for the exact trait name, type and allowed values.
• Decide which environment you will test in first.

The steps

Checking who matches

The dashboard offers ways to look at identities and their traits, and in many versions it can show which identities a segment currently includes, or which segments an identity belongs to. Use these views while testing. They turn a guess into a fact.

Rules are useless without data. This chapter explains how traits get from your product into Flagsmith, in plain steps without code.

The moments when traits are sent

• At sign-in. The app tells Flagsmith who the user is and sends the main facts it knows.
• When something changes. The user upgrades, changes country or finishes onboarding, and the app or backend sends the changed fact.
• At app start. Facts like the app version and device type are sent each time, since they may change after an update.
• In the background. A scheduled job copies fresh facts, such as order counts, from your database.

Setting versus reading

SDKs generally offer two different actions. One is “give me the flags for this user, and here are some traits”. The other is “just update this trait”. Choose based on what the screen needs. If the app needs flags anyway, send the traits along with the same request and save a trip.

Removing a trait

To remove a fact that no longer applies, you send the trait with an empty value, which in most versions deletes it. Do this when, for example, a customer cancels a plan. Leaving an old trait lying around means the user may still match old segments.

Keep traits in step with the truth

Be gentle with writes

If you send the same unchanged traits with every single request, you create many needless writes. Where your SDK allows it, send traits only when they change, or use the option to send short-lived facts without saving them.

Flagsmith can decide the answer in two places. Each has strengths and different rules about traits.

Remote evaluation

In remote evaluation, the app asks Flagsmith for the flags of a user, and Flagsmith works out the answer on its servers. Traits are sent with the request or read from storage. This is the default for client-side apps, and it keeps your rules and other users’ data away from the device.

Local evaluation

In local evaluation, a trusted server-side program downloads the whole environment once, including features, segments and overrides, and keeps it in memory. When it needs an answer for a user, it works it out itself, using the traits you supply at that moment. It refreshes the downloaded copy from time to time. This reduces network chatter and can be faster under heavy load.

The catch with local evaluation

With local evaluation, Flagsmith does not hold the user’s traits unless you also send them there. So if you rely on stored traits, you must supply them from your own systems each time, or the rules will see an empty user. Test this early.

Choosing between them

• Browser and mobile apps: remote evaluation, because the server-side key must never be placed in a device.
• Backend with high traffic and trusted data: local evaluation is worth trying.
• Mixed systems: use both, each where it fits.

A trait has a life: it is born, it changes and it eventually goes away. Planning for each stage prevents stale data.

Stage 1: Birth

A fact first appears, for example when a user signs up. The app or backend sends the first value, and Flagsmith stores it against the identity.

Stage 2: Use

Each time flags are requested, the trait is compared with segment rules. Its value decides which segments the user belongs to.

Stage 3: Change

The user’s situation changes. The new value is sent, and the old one is replaced. From the very next request, the new value drives targeting.

Stage 4: Staleness

If nothing updates the trait when reality changes, it becomes stale. A customer who cancelled a year ago may still be marked premium. This is the most common quiet bug in trait systems.

Stage 5: Removal

The fact no longer applies, or the user leaves. The trait is cleared, and in some cases the whole identity is deleted to meet privacy rules.

stateDiagram-v2
    [*] --> Created: First value sent
    Created --> InUse: Evaluated on each request
    InUse --> Updated: Fact changes and new value sent
    Updated --> InUse
    InUse --> Stale: Reality changed, nothing updated
    Stale --> Updated: Sync catches up
    InUse --> Removed: Trait cleared
    Stale --> Removed: Clean-up
    Removed --> [*]

Planning for each stage

Deleting users

Privacy laws in many places give people the right to have their data removed. If identities and traits count as personal data in your setup, you need a way to delete them on request. Plan this early. It is far easier to include deletion in the design than to add it after a request arrives.

A “schema” is just an agreed list of traits and their meanings. A tidy schema keeps a growing company out of trouble.

Start from the questions, not the data

Many teams begin by sending every fact they have, then wonder what to do with it. Do the opposite. List the decisions you want flags to make: who gets early access, which plan unlocks which feature, which regions are ready. Then decide which minimal facts are needed to make each decision.

The catalogue

Principles of a good schema

• Few and meaningful. Every trait must be used by at least one rule, or removed.
• Stable names. Renaming a trait means every segment using it must change at once.
• Coarse rather than precise. “age_group” is usually safer and just as useful as an exact birth date.
• Derived, not raw. Send “is_premium” or “plan” instead of raw payment details.
• Documented owners. Every trait has a team that answers questions about it.

Planning change

When you must rename or retype a trait, do it in steps. First send both the old and the new trait. Then update segments to use the new one. Finally stop sending the old one and remove it. Doing it all at once risks a gap where nobody matches any rule.

Trait-based segmentation solves many everyday problems. Here are the most common ones, with plain examples.

Use case 1: Plan-based entitlements

Use case 2: Early access for staff and beta users

Use case 3: Regional launches

Use case 4: Compatibility with old versions

Use case 5: Cohort tests

Use case 6: Loyalty and behaviour

Use case 7: Gradual rollouts with safety

Use case 8: Customer-specific behaviour in business products

Use case 9: Kill switches for part of the audience

Segments pair naturally with experiments. Used well, they help teams learn what works for whom.

Multivariate flags

A multivariate flag has several possible values, split by percentages. A button might be blue for fifty percent of users, green for thirty and orange for twenty. A segment override can change these splits for a certain group. For instance, new customers might see an equal three-way split, while long-time customers always see the blue button.

Why segments help experiments

• Focus. A test about checkout belongs to people who actually reach checkout.
• Fairness. Comparing new customers with long-time customers mixes two different groups. Segments keep comparisons clean.
• Safety. Risky variations can be shown first to staff or to a small group.
• Exclusion. Some groups, such as customers in a sensitive period, can be kept out of tests.

An example

Things to watch

Traits are data about people. Treat them with the same care you give any customer data.

Minimise what you send

The safest data is data you never collect. For every trait, ask: “Which rule needs this?” If none, do not send it. Prefer labels over details: “premium” instead of a payment history; “age_group” instead of a birth date.

Avoid direct personal identifiers

Use an internal customer number, or a one-way scrambled form of an email address, as the identity identifier instead of the raw email or phone number. If a trait or identifier leaks in a log or a screenshot, it should not point straight to a person.

Sensitive categories

Never use traits for sensitive information such as health conditions, religion, political opinions or similar categories, unless you have a clear legal basis and strong controls. Many rules place special limits on these. A simple company rule of “no sensitive categories in Flagsmith” avoids a lot of risk.

Who can see what

• Control who can view identities and traits in the dashboard. Few people need to see them.
• Use environment settings that hide sensitive values where offered.
• Give staff the least access they need for their work.
• Review the access list regularly.

Trust and tampering

Traits sent by a client app can be changed by a clever user. If a trait gives paid features, send it from a trusted backend, and consider disabling client-set traits in that environment. For harmless traits such as the app language, a client is fine.

Keys

The client-side environment key is designed to be visible in apps and only lets them read flags and set limited facts. The server-side key is powerful and must be secret. Store it in a secrets manager and rotate it from time to time.

Rules and laws

Data protection laws in many countries, such as the European GDPR, India’s data protection law and others, care about how personal data is collected, used, stored and deleted. Talk to your privacy or legal team. Show them the trait catalogue, and tell them where Flagsmith is hosted.

Products with millions of users need targeting that stays fast and stays up. Here is what to think about.

What costs time

For each flag request, Flagsmith must load the identity and its traits, compare them with every segment rule, and choose the override for each feature. A few dozen simple segments are trivial. Hundreds of complicated segments, with many nested rules and heavy text patterns, cost more. Writes also cost: saving traits on each request creates database work.

Ways to keep it fast

Scale out and stay up

The managed Flagsmith service handles scaling for you, using spread-out read layers. A self-hosted installation can run several copies of the API behind a load balancer, with a primary database that has a standby copy ready to take over. The write path for traits tends to be the busiest part, so give the database plenty of room, and watch it as traffic grows.

If Flagsmith has a bad day

Apps should survive a short outage. Give every flag a safe default value in the code. Where possible, let SDKs keep a recent copy of flags so the app can carry on. Decide in advance what each feature does when it cannot learn the answer: for a risky new feature, “off” is normally safest.

When a user says “I do not see the feature”, you need a fast way to find out why.

The identity page

The Flagsmith dashboard can show the details of an identity: its traits, the segments it currently belongs to and the feature values it would receive. This is the single most useful debugging view. Open the user’s identity, check the traits, and compare them with the segment rules.

A debugging routine

The audit log

Flagsmith keeps an audit log that records who changed what and when, including edits to segments and overrides. If a group suddenly behaves differently, check whether somebody edited a rule a few minutes earlier. Because segments are shared across a project, one edit can have wide effects.

Useful numbers to watch

• How many users fall in each important segment, and how that changes over time.
• How many identities have each trait set, to spot missing data.
• How many trait writes happen per minute.
• Error rates in the app after a segment change.

A segment rule is a small program. Like any program, it needs testing.

Build a test table

For each segment, write down a handful of imaginary users and the answer you expect. Include the normal cases, the edges and the odd ones. Run each through Flagsmith, using test identities in a safe environment, and compare.

Use staging that looks like production

Test in a staging environment with the same segments and similar traits as production. Use fake users with names that cannot be confused with real people, such as “test-premium-india-01”. Never test by editing real customers’ traits.

Dry runs for rollouts

Before a big launch, go through the full plan in staging: create the segments, add the overrides, change the percentages and check each step with test users. A rehearsal in a safe space finds mistakes cheaply.

After the change

• Check a few real identities in production to confirm they land in the expected segments.
• Watch error graphs and key business numbers for the next hour.
• Have a one-minute undo plan: for example, disable the override.

No design is perfect. Here is an honest look at what trait-based segmentation gives and what it costs.

Rules in Flagsmith versus rules in code

Flexibility versus clarity

The freedom to define any segment is also the freedom to make a mess. Teams that enjoy the freedom without discipline end up with hundreds of overlapping segments that nobody understands. A modest list of well-named, well-owned segments is nearly always better than a huge, clever one.

Central rules versus local needs

Shared segments encourage reuse, but one edit touches every feature that uses it. Some teams prefer a few shared segments for company-wide ideas, such as Staff, and private segments for feature-specific needs, with clear names. Use the style that fits your size.

Patterns are habits that other teams have already tested. Anti-patterns are habits that looked clever and then caused pain.

Pattern 1: Staff first

Every new feature goes first to the Staff segment. Employees are forgiving, they know whom to tell, and they find the obvious problems.

Pattern 2: Widening rings

Release in rings: staff, then beta testers, then ten percent, then fifty percent, then everyone. Each ring is one segment or one percentage, and each ring has a pause to watch the numbers.

Pattern 3: Entitlement segments

Create one segment per plan, based on a single trusted trait. Flags attach to these segments for limits and features. The business changes a plan’s rights by editing overrides, not by editing code.

Pattern 4: Compatibility guards

Use an app-version segment to hide features from versions that cannot support them. Pair it with a plan to retire old versions.

Pattern 5: Derived traits

Compute a simple label in your backend, such as “customer_tier”, from many raw facts, and send only the label. Rules stay short, and the complex logic lives in a system built for it.

flowchart LR
    S["Staff"] --> B["Beta Testers"]
    B --> P10["10 percent of users"]
    P10 --> P50["50 percent of users"]
    P50 --> ALL["Everyone"]
    S -.-> W1["Watch and fix"]
    B -.-> W2["Watch and fix"]
    P10 -.-> W3["Watch and fix"]
    P50 -.-> W4["Watch and fix"]

Experienced teams build a few simple habits. Beginners tend to make the same few slips.

Best practices

Common mistakes

Troubleshooting guide

Where Flagsmith runs changes a few practical details of trait handling.

The hosted service

In the hosted service, Flagsmith runs everything. Scaling, upgrades and read layers close to your users are taken care of. Limits on identities, traits or segments may depend on your plan, so check them before designing a large system.

Self-hosting

Because Flagsmith is open source, a team can run it on its own servers or cloud account. A typical layout has several copies of the API behind a load balancer, a main database with a standby copy, a cache and background workers. Teams choose this path when they must keep data in their own network, or when they want complete control.

flowchart LR
    APPS["Apps and Servers using SDKs"] --> LB["Load Balancer"]
    LB --> API1["Flagsmith API Copy 1"]
    LB --> API2["Flagsmith API Copy 2"]
    API1 --> DB[("Primary Database: identities and traits")]
    API2 --> DB
    DB --> STBY[("Standby Database")]
    API1 --> CACHE["Cache Layer"]
    API2 --> CACHE
    TEAM["Team in Dashboard"] --> LB
    API1 --> WORK["Background Workers"]

What matters for traits when self-hosting

• Database room. Traits are many small writes. Make sure the database has headroom, and watch its load as users grow.
• Retention. Decide how long identities are kept, and set up clean-up of old ones.
• Backups. Identities and traits are real data. Back them up, and practise restoring.
• Privacy. You are now the data host. Control access, encrypt data in transit and at rest, and record who can see what.
• Upgrades. After an upgrade, retest a few segment rules, especially those that use newer operators.

Regions and data location

Some companies must keep personal data in certain countries. Where Flagsmith runs, and where its database lives, then matters. Ask Flagsmith about the regions of the hosted service, or choose a self-hosted install in the right location. This is a good reason to keep traits minimal.

Cost thinking

The software cost is mainly the plan tier. Indirect costs include database size, the effort to maintain traits and the time people spend managing segments. Tidy habits keep all three low.

As more teams use Flagsmith, habits matter as much as features. This chapter covers the human side.

Who owns a segment?

Every segment should have an owner, a person or team, and a one-line purpose. Without an owner, nobody knows if a segment can be changed or deleted. Write the owner in the description, and review the list each quarter.

Who owns a trait?

Every trait has two owners: the team whose system is the source of truth, and the teams whose segments depend on it. Changes to a trait’s meaning must be announced to both.

Permissions

Flagsmith lets administrators control who can view and edit things at several levels: organisation, project and environment. Common sense suggests that many people may read segments, fewer may edit them, and very few may edit segments that affect production for large groups. Remember that editing a segment rule changes it for every environment in the project.

Review for risky changes

Some plans of Flagsmith offer an approval workflow, sometimes called change requests, where a second person must approve changes to a protected environment before they go live. Use it for production overrides that affect many users. Edits to shared segment definitions are especially worth a second pair of eyes.

A short change note

Whenever you edit a segment or an override, write a short note: what changed, why, who is affected, how to undo. A one-line habit like this makes the audit log and team memory far more useful.

Retiring segments and traits

Teaching newcomers

New teammates should learn in their first week: the trait catalogue, the list of main segments, how priority works, how to debug an identity and who to ask. A one-page guide in plain words, with real examples from your project, is worth more than a long manual.

Let us follow a made-up product, “Acme Docs”, through a full project to see how every idea in this guide fits together.

The situation

Acme Docs is a document tool with two million monthly users. It has three plans: free, standard and premium. The team wants to give each plan a different upload limit, and also to launch a new “smart search” page carefully. They use one Flagsmith project with Development, Staging and Production.

Stage 1: Decide the questions

The team writes down the decisions they want flags to make: What upload limit does this user get? Should this user see smart search? From this, they decide which facts are needed: the plan, whether the user is staff, the app version and the country.

Stage 2: Build the trait catalogue

They create a one-page catalogue with four traits: plan (text, from billing), is_staff (true or false, from the company directory), app_version (version style, from the app at start-up) and country (two-letter code, from the account profile). Each has an owner, and the billing team is the owner of plan.

Stage 3: Send the traits

The backend sends plan and is_staff whenever they change, and also at sign-in. The app sends app_version at each launch. The environment option that lets client apps set traits is turned off in production, so that users cannot change their own plan.

Stage 4: Define the segments

Stage 5: Attach overrides

The feature “upload_limit_mb” has a default of 25, an override of 100 for Standard Users, 500 for Premium Users and 1000 for Staff, ordered with Staff at the top. The feature “smart_search” is off by default. In production, an override turns it on for Staff first.

flowchart LR
    A["Decide questions"] --> B["Write trait catalogue"]
    B --> C["Send traits from billing and app"]
    C --> D["Define segments"]
    D --> E["Add overrides in Staging"]
    E --> F["Test with fake users"]
    F --> G["Copy overrides to Production for Staff"]
    G --> H["Widen to 10 percent, then 50, then all"]
    H --> I["Review and clean up"]

Stage 6: Test

In Staging, the team creates ten fake users: free, standard and premium; staff and non-staff; app versions 4.9.9, 5.0.0 and 5.10.0; and one with no plan trait. They check each result against a table of expected answers. They discover that the rule for versions was matching 5.10.0 as older than 5.9.0 because of text comparison. They switch the rule to the version-aware style and retest.

Stage 7: Roll out

In Production, smart search is first on for Staff for three days. Then for ten percent of users who are on a ready app version. The team watches error rates and search success. Everything stays calm. They raise the percentage to fifty and then to everyone over the next week, with a short note in the change log at each step.

Stage 8: Learn and tidy

After the launch, they delete the ring segments and keep the plan segments. They write down lessons: send traits from the backend, test versions, and never skip the missing-trait test. They add these to the team’s checklist.

Once the basics feel comfortable, a few deeper ideas decide how well your targeting ages as the product grows.

Nested rules

A segment can contain rules inside rules. The top level says how the main groups combine, and each inner group says how its own conditions combine. This lets you express sentences such as “country is India or Brazil, and plan is premium or standard, and the user is not staff”. Written out, that is three groups: ANY of two countries, ANY of two plans, and NONE of the staff condition, all required together.

Nested rules are powerful but hard to read. Keep the nesting shallow. If a rule needs more than two levels, ask whether a derived trait, such as “launch_group”, computed in your backend, would say the same thing in one line.

Pattern matching with care

Flexible text patterns, often called regular expressions, can match many forms of a value at once. They are also easy to get wrong, slow when complicated, and hard for colleagues to read. Use them only when simple equals or list matching cannot do the job, and always test them against both matching and non-matching examples.

Segments that depend on other segments

Some teams build segments that mirror other segments, such as “Premium Users in India” copied from “Premium Users” with one extra condition. Copies drift apart. When the definition of premium changes, one copy is updated and the other forgotten. Prefer one clear segment per idea, and combine ideas using override order or derived traits instead of copying rules.

Trait drift

Trait drift is the slow growth of differences between what a trait says and what is true. A customer changes country, but the old value stays. A plan is cancelled, but the trait still says premium. Drift quietly gives people the wrong features. Fight it with three habits:

• Update on change. Wire the source system so that every change sends the new value.
• Reconcile regularly. Once a night or week, compare a sample of identities with the source system and repair differences.
• Measure it. Track how many identities disagree with the source. A rising number is a warning.

Identity hygiene

Identities pile up. Every visitor who ever opened your app may have left an identity behind. Many are never seen again. Decide how long unused identities should live, and remove old ones, for both cost and privacy. If your anonymous visitors get a new identifier every visit, you may be creating a new identity for each of them, which fills the database with throwaway records. Prefer a stable anonymous identifier, or use short-lived traits that are not saved.

Versioning your segments

Treat a major change to a segment like a change to an interface. Create a new segment with the new rule, attach it to features beside the old one, check the effect, and then remove the old one. This avoids the surprise of changing a rule that many features quietly depend on.

flowchart LR
    OLD["Old segment in use"] --> NEW["Create new segment with improved rule"]
    NEW --> ATT["Attach new segment to features beside the old one"]
    ATT --> CMP["Compare results with test users"]
    CMP --> SW["Switch overrides to the new segment"]
    SW --> DEL["Delete the old segment"]

A worked example: cleaning up a messy project

Questions to ask yourself once a year

• Do our traits still describe the decisions we need to make?
• Which segments have not been used in the last six months?
• How many identities disagree with their source of truth?
• Would we be comfortable showing our trait catalogue to a privacy reviewer tomorrow?
• Could a new teammate debug a wrong flag value in ten minutes?

Targeting features by user attributes is a long-standing idea. The descriptions below reflect what these companies have discussed publicly, as patterns, not details of private systems.

Facebook: gates based on user attributes

Facebook has described an internal gating system that decides who sees a new feature using attributes of users, such as whether they are employees, which country they are in and what share of users should be included. New features commonly reach staff first, then small groups, and then larger ones. That is the same ring idea described in this guide.

Netflix: careful, group-aware change

Netflix has discussed testing changes on small slices of its audience before broad release, and comparing the groups with measurements. Group-based testing needs clear, stable groups and good records of who saw what, which is exactly what traits and segments provide.

Google: experiments and launch controls

Google has written about running many controlled experiments and about launch processes that expand a change step by step. Targeting by user attributes, region and device type is a normal part of those approaches.

Uber and similar services: place-based rules

Ride and delivery services operate in many cities, each with different rules and readiness. A trait for the city or region lets a feature be switched on city by city, matching local support and law.

Spotify and subscription services: plan-based features

Subscription products give different features and limits to free and paid users. Driving those differences from a single “plan” fact, rather than from scattered code, is a common design that trait-based segmentation supports.

Software for businesses: customer-specific behaviour

Companies that sell to other companies often turn on pilot features for a single customer. A company trait lets a segment target only that customer’s employees, without creating a separate version of the product.

Experienced pilots do not trust memory for routine steps, and neither should you. Copy these into your team wiki.

Before you add a trait

• Name the rule or decision that needs it. No rule, no trait.
• Choose a clear name, a type and allowed values.
• Choose one source of truth and one owner.
• Check whether it is personal data, and whether you may use it.
• Decide how and when it will be updated and removed.
• Add it to the catalogue.

Before you create a segment

• Write the name, the purpose and the owner.
• Check that every trait in the rule exists with the right type.
• Think about users with missing traits.
• Think about the order among other segments.
• Prepare a test table with expected answers.

Before you attach an override in production

• Test with fake users in staging.
• Check the order of overrides for this feature.
• Decide the starting group and how it will widen.
• Write the undo step.
• Tell the people who need to know.

After a change

• Open a few real identities and check their segments.
• Watch error and business graphs for the next hour.
• Record what changed in the change log.

Every quarter

• List all segments and traits. Delete unused ones.
• Check owners and descriptions.
• Review who can edit segments and see identities.
• Look for stale traits.
• Run a test table for the main segments.

A short reference for the words used in this guide.

Quick answers to the questions that come up most often.

Let us pull the whole story together in a few lines you can remember.