Before meeting the tool, let us feel the pain it removes.

Constants that never stay constant

Programmers call a fixed number written into the code a constant. But many so-called constants are not truly fixed. The number of search results per page, the maximum size of an upload, the time to wait for a payment provider, the text of a banner, and the discount shown on a sale all need to change as the business learns. Each change, if buried in code, needs a new release.

The cost of a release

A release is not free. Someone must make the change, review it, run tests, build the program, deploy it, and watch it. For mobile apps, the cost is higher still: the new version must pass an app store review and then wait for users to update, which can take days or weeks. For something as small as a wording change, the effort is out of all proportion.

Why speed matters in a crisis

Imagine a payment provider starts responding slowly during a busy evening. If the wait time and retry count are fixed in code, the fix is a full release in the middle of an incident. If they are remote config values, an engineer changes two numbers in a dashboard and the problem eases within a minute or two. When things go wrong, that difference is priceless.

A flag answers yes or no. A remote config value answers “how much?” or “which one?” or “what should it say?”.

The definition

A remote config value is a piece of data, such as a number, a word, a sentence, or a small block of settings, that is stored in Flagsmith and read by your application while it runs. Because it lives outside the code, you can change it without changing or redeploying the application.

One object with two parts

In Flagsmith, flags and remote config are not two separate things. Both are a feature. Every feature has an on/off state, and may also carry a value. A pure on/off switch simply has no value. A pure setting, such as a page size, may be thought of as a feature whose main purpose is its value. Many features use both: the state says whether a behaviour is active, and the value says how it should behave.

An example

Suppose you have a feature called “search-results-per-page”. Its value is twenty in Production and fifty in Staging. Your search code asks Flagsmith for the value and shows that many results. Tomorrow the product team wants thirty. They open the dashboard, change the value in Production to thirty, and within moments your servers start returning thirty results. No code changed.

flowchart LR
    DASH["Dashboard: change value to 30"] --> FS["Flagsmith stores the new value"]
    FS --> SDK["Application SDK fetches or refreshes"]
    SDK --> APP["Application uses 30 for the next request"]
    

Both live in the same place, but they solve different problems.

The simple rule

Use a flag when your code needs to decide whether to do something. Use a value when your code needs to know how much, how long, which one, or what text. Many features use both together.

Why not use only values?

A value of zero or an empty text can mimic “off”, but this creates confusion. Is zero a real setting or a switch? A clear on/off state avoids that ambiguity. Using both, state for whether and value for how, keeps your intent obvious.

Why not use only flags?

You could create ten flags called “page-size-10”, “page-size-20”, and so on, but this is clumsy and hard to maintain. A single value is simpler and far easier to change.

To use values well, learn the parts that surround them.

Where features live

Flagsmith organises everything in layers. An organisation holds your team. A project represents one product or application and owns the list of features. An environment, such as Development, Staging, or Production, holds the actual state and value of each feature. A feature is defined once for the project, but each environment keeps its own state and its own value for it.

The parts of a feature

• Name: the label your code uses to ask for it. It should be clear and permanent.
• Description: a human explanation of what the feature does and what the value means, including its unit and allowed range.
• State: on or off in each environment.
• Value: the data held, which can differ per environment.
• Tags: labels for grouping, such as the owning team or the type of setting.
• Overrides: special values for particular segments or individual users.
• Variations: several weighted values for multivariate features.

flowchart TD
    P["Project"] --> F["Feature: search-results-per-page"]
    F --> D["Description and tags"]
    F --> E1["Development: on, value 50"]
    F --> E2["Staging: on, value 25"]
    F --> E3["Production: on, value 20"]
    E3 --> S1["Segment override: beta users, value 30"]
    E3 --> I1["Identity override: one customer, value 40"]
    

The description is part of the design

A value without a description is a riddle. Someone will see “thirty” in the dashboard and wonder whether it means seconds, items, or percent. Write down what the number means, its unit, and the safe range. This one habit prevents a great many mistakes.

What kind of thing can a value hold, and how should your code treat each?

The basic types

Flagsmith values commonly come in a few basic types. A string is text, such as a sentence or a code name. An integer is a whole number, such as a count or a number of seconds. A boolean is true or false. Depending on your SDK, the value you receive may already have the right type, or may arrive as text that your code must convert. Check how your SDK behaves, because this is a common source of surprise.

Structured values

Sometimes one setting is not enough, and a group of related settings makes sense, such as a timeout, a retry count, and a back-off factor together. Teams often store a small block of structured text, in a format such as JSON, as the value, and have their application read it into separate settings. This is flexible, but it comes with extra risks, which we cover in a later chapter.

Always convert and check

Whatever the type, the receiving code should treat the value as untrusted input. It should convert it to the type it needs, check that it is within a sensible range, and fall back to a safe default if it is not. A person typing into a dashboard can make a typing mistake as easily as anyone, and an extra zero can turn a ten-second timeout into a hundred.

The same setting often needs different values in testing and in production.

Why values differ by environment

A development environment may want very long timeouts so engineers can debug. Staging may want results that mimic production but on small data. Production wants tuned, safe values. Because each environment stores its own value for each feature, you can set all of these independently, and a change in one never affects the others.

Safe experimentation

This separation lets developers try values freely. A developer can raise a limit in Development to see how the code behaves, with no risk to customers. When the team is happy, someone sets the agreed value in Production deliberately.

Keeping environments aligned

The danger is drift. Over time, environments may end up with values that nobody remembers choosing, so that Staging no longer resembles Production and tests give false comfort. Review values across environments regularly, and record the reason when they are meant to be different.

A value does not have to be the same for everyone, even within one environment.

Segments in short

A segment is a saved group of users defined by rules over their traits, which are facts about them such as plan, country, or app version. A segment override gives a feature a different state or value for members of that segment.

Values for groups

This is where remote config becomes powerful. You can say “the upload limit is ten megabytes for everyone, but fifty megabytes for the enterprise plan.” Or “the banner says one thing in India and another in Germany.” Or “the timeout is eight seconds, but twelve seconds for users on slow networks.” One feature, one place to manage, many values depending on who is asking.

Priority matters

Because a person can belong to several segments, overrides are checked in a priority order and the first match wins. If a staff member is also on the enterprise plan, which value should they get? You decide by arranging the order, putting the more important or more specific rule first.

Sometimes the right group is a group of one.

Identities and traits

An identity is a unique ID for one user, device, or account. A trait is a fact about that identity. The application sends them together when it asks for values, so Flagsmith can tailor its answer.

Identity overrides

An identity override pins a feature to a particular state or value for exactly one identity. This beats every segment rule, because it is the most specific kind of rule there is. Support teams use it to help one customer: “give this customer a higher export limit while we investigate their problem.” Engineers use it to test a value on their own account in Production before changing it for anyone else.

Handle with care

Personal overrides are easy to create and easy to forget. Months later, nobody remembers why one customer has a special limit, and it may no longer be right. Record the reason for each, add a review date, and include identity overrides in your regular clean-up.

When you want to hand out different values to different users in controlled shares, you use a multivariate feature.

What multivariate means

A multivariate feature has several possible values, called options or variations, and each option has a weight, which is the percentage of users who should receive it. For example, a button label could have three options: “Buy now”, “Add to basket”, and “Get it today”, each given a third of the audience.

Stable assignment

Flagsmith assigns each identity to an option using a repeatable calculation based on the identity and the feature. This means the same person receives the same option every time they return, rather than seeing “Buy now” in the morning and “Get it today” in the afternoon. It also means that no list of “who got what” needs to be stored.

Control and variations

The feature’s own value acts as the standard, or control. The other options are variations that take a share of users from the control. Setting all variation weights to zero means everyone sees the control. This makes it easy to turn an experiment off without deleting it.

flowchart LR
    U["User identity"] --> H["Repeatable calculation on identity and feature"]
    H --> B{"Which share does it fall into?"}
    B -->|"First 40 percent"| A["Control value"]
    B -->|"Next 30 percent"| V1["Variation one"]
    B -->|"Last 30 percent"| V2["Variation two"]
    

What multivariate values are good for

• Testing different wordings, colours, or layouts.
• Trying several limits or thresholds on small audiences to see which performs best.
• Rolling out a new value slowly, by giving it a small weight and increasing it.

With environments, segments, identities, and variations all possible, you need a clear picture of who beats whom.

From most specific to most general

When an application asks for a value, Flagsmith works down a ladder. The first rung that has an opinion decides the answer.

1. Identity override: a value set for this exact person.
2. Segment overrides: checked in priority order, and the first one whose rules match gives its value.
3. Multivariate allocation: if the feature has variations, the user’s stable bucket picks one.
4. Environment value: the normal value for the feature in this environment.

The exact interaction between segment overrides and multivariate options can depend on how you configure them. Always check how your setup behaves by testing with a few sample identities, and consult the current documentation for edge cases.

flowchart TD
    Q["Application asks for a value"] --> I{"Identity override exists?"}
    I -->|"Yes"| R1["Use the identity's value"]
    I -->|"No"| S{"A segment override matches?"}
    S -->|"Yes, highest priority first"| R2["Use that segment's value"]
    S -->|"No"| M{"Feature has variations?"}
    M -->|"Yes"| R3["Use the option from the stable bucket"]
    M -->|"No"| R4["Use the environment value"]
    

Keeping it understandable

The more layers you use, the harder it is to explain why a user got a certain value. Prefer a few well-named segments over many overlapping ones, document each override, and use the dashboard’s tools for viewing a particular identity’s effective values when you investigate a puzzle.

Follow a single question from your code to Flagsmith and back.

The steps

Your application uses a Flagsmith SDK, a ready-made library that talks to the service. When the application starts, the SDK is set up with an environment key. When your code needs a setting, it asks the SDK for the value of a named feature, usually supplying a default, which is the value to use if nothing better is available. The SDK finds the feature in the flags it has received, and returns the value, converted to a type your code can use.

Where the answers come from

The SDK may have the answers from a recent request to Flagsmith, from a copy saved on the device, or from a downloaded set of rules held in memory on a server. In every case, the code asking the question is the same: “what is the value of this feature for this user?”

sequenceDiagram
    participant Code as Your Code
    participant SDK as Flagsmith SDK
    participant FS as Flagsmith
    Code->>SDK: Value of search-results-per-page, default 20
    SDK->>SDK: Look in the flags already received
    alt Flags are present
        SDK-->>Code: The value, for example 30
    else Flags missing or request failed
        SDK-->>Code: The default, 20
    end
    SDK->>FS: Refresh in the background
    FS-->>SDK: Latest values
    

The state and the value together

A feature has both a state and a value, so your code has a choice about how to treat a disabled feature that still has a value stored. Some teams read the value only when the feature is on, treating off as “use the built-in default”. Others read the value regardless. Decide on one convention for your team, write it down, and check how your SDK behaves, because mixed conventions lead to confusing bugs.

Where your code runs changes how values arrive and how much to trust them.

Server-side readers

A server runs on machines you control. Its SDK uses a secret server-side key, and can either ask Flagsmith for each user’s values, or download the whole environment’s rules once and answer in memory, which is called local evaluation. Local evaluation is very fast and reduces traffic, but changes reach the server only when the next refresh happens, commonly within about a minute by default.

Client-side readers

A browser or a mobile app runs on a device you do not control. Its SDK uses a public client-side key, asks Flagsmith for the values for one user, caches them, and uses them to shape the interface. The device receives only that user’s own results, never the full rules.

What to trust

Anything that reaches a client can be read and may be altered by the user. So values sent to a client must be harmless to reveal, and decisions of real importance must be checked on the server. A banner message in a value is perfect for a client. A secret address is not. A limit that merely adjusts the interface is fine on a client, while a limit that protects your servers must be enforced on the servers themselves.

From a click in the dashboard to a changed behaviour in a user’s hands.

The journey

A person changes a value in the dashboard. Flagsmith saves the change and records it in the audit log. The new value is then copied to the layer that serves reads, so SDKs can see it. After that, each SDK learns of it in its own way: servers using remote evaluation on their next request, servers in local mode at their next refresh, and clients at their next fetch.

sequenceDiagram
    participant P as Person in Dashboard
    participant FS as Flagsmith
    participant Log as Audit Log
    participant Srv as Server SDK
    participant Cli as Client SDK
    P->>FS: Change value from 20 to 30
    FS->>Log: Record who, what, and when
    FS->>FS: Publish to the serving layer
    Srv->>FS: Next refresh
    FS-->>Srv: New value 30
    Cli->>FS: Next fetch
    FS-->>Cli: New value 30
    

The lifecycle of a setting

Not every setting should live forever

Remote config is for things that change or might need to change. A setting that has stayed the same for a year and will not change again is better off as a plain constant in code, which is simpler and cannot be altered by accident. Review old values regularly and ask whether each still earns its place.

Not every setting deserves a dial. Good candidates share a few traits.

Good candidates

• Operational tuning: timeouts, retry counts, batch sizes, cache durations, thresholds.
• Limits and quotas: upload sizes, request rates, number of items, per plan.
• Messages and copy: banners, notices, labels, help links.
• Choices among a few options: which provider to use, which layout to show, which algorithm version.
• Gradual changes: any number you want to raise or lower in small steps while watching results.
• Emergency adjustments: values you may need to change fast during an incident.

Poor candidates

• Secrets: passwords, tokens, private keys. These belong in a secrets manager.
• Large data: long lists, documents, full catalogues. These belong in a database.
• Per-user data: a customer’s address or settings. These belong in your own data store.
• Things that never change: true constants are simpler in code.
• Settings that need deep review and migration: changes to data formats or schemas should go through code and tests, not a dial.

flowchart TD
    A["A setting in the code"] --> B{"Is it secret?"}
    B -->|"Yes"| S["Use a secrets manager"]
    B -->|"No"| C{"Is it large or per-user data?"}
    C -->|"Yes"| D["Use a database"]
    C -->|"No"| E{"Might it need to change without a release?"}
    E -->|"No"| K["Keep it as a constant in code"]
    E -->|"Yes"| R["Use a remote config value"]
    

Good names and descriptions turn a pile of settings into a manual.

Names that explain themselves

A name is a permanent promise. Code will depend on it, so renaming later is costly. Choose names that say what the setting is, in which area, and in what unit. “payment-timeout-seconds” tells you three things at once. “timeout2” tells you nothing. A common pattern is area, then purpose, then unit, joined with dashes.

Descriptions that guide the next person

Fill in the description for every feature. Say what the value controls, the unit, the allowed range, what a sensible default is, and who owns it. If changing the value could affect cost or customers, say so.

Tags

Use tags to mark the owning team, the type of setting, and whether it is scheduled for review. Tags make it easy to filter a long list when you do a clean-up.

A remote value is typed by a human into a dashboard. Your code must treat it as input from outside, however friendly the source.

What can go wrong

• Typing mistakes: an extra zero, a missing digit, a stray space.
• Wrong type: text where a number was expected.
• Out-of-range numbers: zero, negative, or absurdly large values.
• Empty values: a blank where something was expected.
• Unknown choices: a mode name your code does not recognise.
• Broken structure: a block of structured text that cannot be read.

A sensible validation routine

1. Convert the value to the type the code needs.
2. Check the range or the allowed list. A timeout must be between one and thirty seconds. A mode must be one of the known names.
3. Fall back to the last good value, or the built-in default, if the check fails.
4. Log a warning that names the feature and the bad value, so a person can fix it.

flowchart TD
    V["Value received from Flagsmith"] --> T{"Right type after conversion?"}
    T -->|"No"| F["Use last good value or default, log a warning"]
    T -->|"Yes"| R{"Within the allowed range or list?"}
    R -->|"No"| F
    R -->|"Yes"| U["Use the value"]
    

Put one small module between your application and Flagsmith, and many problems disappear.

The idea

Instead of asking Flagsmith directly from many places, create one module in your own code that owns all remote settings. It has one clearly named function for each setting, such as “search page size” or “payment timeout”. Each function reads the value, converts it, validates it, applies a default, and returns a trustworthy result. The rest of the application only ever calls these functions.

What it gives you

• One place for defaults. Every setting has its safe default written once.
• One place for validation. Ranges and allowed lists are checked consistently.
• Clear types. The rest of the code never has to worry about text versus numbers.
• Easy testing. Tests can replace the module with fixed values.
• Easy change. If you ever switch tools, only this module changes.
• Good logging. The module can log the effective value at start-up and whenever it changes.

flowchart LR
    A["Application code"] --> M["Your settings module"]
    M -->|"Read, convert, validate, default"| SDK["Flagsmith SDK"]
    SDK --> FS["Flagsmith"]
    M --> L["Log effective values"]
    

A block of structured text can hold many settings at once. Use it with open eyes.

Why teams use them

Sometimes several settings belong together: a timeout, a retry count, and a back-off factor, or the colours and text of a promotional banner. Putting them in one structured value means one feature to manage instead of five, and changes to the group happen at the same moment.

The risks

• Invalid structure. One missing bracket or comma can make the entire value unreadable.
• Shape drift. Someone adds, removes, or renames a field, and old code no longer understands it.
• Size. Big values slow every request, because they travel with all the flags.
• Hidden complexity. A dashboard text box is a poor place to edit a long, nested structure, and mistakes are easy.
• No type checking. The dashboard cannot tell you that a number field now holds text.

How to use them safely

1. Keep them small. A handful of related fields is plenty.
2. Add a version field. Let the code know which shape it is reading, so old and new can coexist.
3. Validate every field. Treat each field like its own value, with a type, a range, and a default.
4. Ignore unknown fields. A tolerant reader survives additions.
5. Fall back as a whole. If the structure is unreadable, use the last good copy or the built-in defaults.
6. Draft elsewhere. Edit and check the text in an editor that highlights mistakes, then paste it in.

Every read needs an answer to the question “what if there is no answer?”

Why defaults matter

The network will fail one day. The service may be slow. A feature may be deleted, misspelled, or missing from an environment. In every one of these cases, your code must still do something sensible. A default value written into the code is what saves the day.

Choosing a default

The best default is usually the value the application used before the setting became remote. It is known to work, because the code ran with it for months. If a new setting has no history, choose the safest, most conservative value: a generous timeout rather than a tiny one, a modest limit rather than none.

The disabled state

When the feature is off but still holds a value, decide what the code does. A common, safe convention is: “if the feature is off, use the built-in default and ignore the stored value”. This gives you a quick way to return to normal: just switch the feature off. Write the convention down, so everyone understands what “off” means for a value.

Where defaults live

Keep defaults in your settings module, not scattered across the code. A single list of defaults is easy to review, easy to test, and easy to update when you learn better numbers.

flowchart TD
    A["Need the value"] --> B{"Answer received in time?"}
    B -->|"No"| C{"Last good value available?"}
    C -->|"Yes"| L["Use the last good value"]
    C -->|"No"| D["Use the built-in default"]
    B -->|"Yes"| E{"Feature on and value valid?"}
    E -->|"Yes"| U["Use the received value"]
    E -->|"No"| D
    

Changing a number for everyone at once is a release too, and deserves the same care.

Config changes can break things

It is tempting to think of a value change as harmless, since no code is deployed. But a wrong timeout, limit, or switch of provider can cause as much damage as a bug, and a change made to everyone in one step can cause that damage everywhere at once. Many serious incidents in the industry begin with a configuration change rather than a code change.

Ways to roll out gradually

• Start with yourself. Use an identity override on your own account in Production.
• Then staff. Use a segment of employees.
• Then a small share. Use a multivariate feature, with the new value as a variation given a small weight, such as one or five percent.
• Widen in steps. Raise the weight while watching your graphs.
• Finish. Make the new value the environment default, and retire the variation.

Values are perfect for finding out which choice works better, by trying several on real users.

The basic idea

A multivariate feature gives different users different values in stable shares. If half of your visitors see one button label and half see another, and you measure how many click, you can learn which label works better. Flagsmith handles the splitting. To measure the results, you connect it to an analytics tool and compare the groups there.

Good experiments to run with values

• Wording of buttons, titles, and messages.
• The number of items shown in a list.
• Thresholds, such as the amount that unlocks free delivery.
• Time limits and reminders.
• Choice between two back-end algorithms, identified by name.

Doing it well

1. State the question first. “Does the shorter label increase clicks?”
2. Choose one main measure. Decide in advance what counts as success.
3. Change one thing at a time. Otherwise you will not know what caused the difference.
4. Run long enough. Cover whole weeks, so that weekday and weekend behaviour are both included.
5. Record the assignment. Send the user’s variation to your analytics tool so results can be grouped.
6. End the experiment. Make the winner the default and delete the variations.

flowchart LR
    U["Users"] --> FS["Flagsmith assigns a stable variation"]
    FS --> A["Group A sees value A"]
    FS --> B["Group B sees value B"]
    A --> AN["Analytics tool records behaviour"]
    B --> AN
    AN --> R["Compare results and choose a winner"]
    

Values travel with the flags, so their size and the way they are cached affect every user.

Values ride along with every fetch

When an SDK asks for flags, it receives all features for the environment, each with its state and value. If your values are tiny, this is a small reply. If you have stuffed large pieces of text or structured data into values, every request carries that weight, for every user, on every device. Keep values short.

How many features are too many?

There is no magic number, but a project with thousands of features, many of them old, produces large replies and a crowded dashboard. Clean up regularly, and keep the active list lean.

Caching layers

• On servers: local evaluation keeps the whole environment in memory and answers instantly, refreshing on a schedule.
• On clients: SDKs keep answers in memory and often in local storage, so the app starts with saved values and updates in the background.
• In your settings module: you can cache the validated, converted value, so conversion and checking happen once per change, not on every read.

Read once, use many times

If code in a busy loop reads the same value thousands of times, converting and validating it every time wastes effort. Read the value once per request or once per refresh, store the validated result, and use that.

A good design assumes that one day the answer will be late, old, or missing.

Three kinds of trouble

• Missing: the service cannot be reached, or the feature does not exist in this environment.
• Late: the answer arrives slowly and may hold up the code waiting for it.
• Stale: the application is using an older value than the one now set, because a refresh has not happened or has silently stopped.

Layers of protection

1. Short timeouts on any request, so a slow service never holds up your application.
2. Cached values from the last successful fetch, used while fresh ones cannot be obtained.
3. Built-in defaults for everything, used when there is no cache.
4. Validation so that a bad value is never used.
5. Circuit breakers that stop asking a failing service for a while and use fallbacks instead.

Detecting staleness

Stale values are quiet failures. A server in local mode that stops refreshing keeps using old numbers, and nothing shouts. Record the age of the rules held in memory and alert if it grows far beyond the refresh interval.

stateDiagram-v2
    [*] --> Normal
    Normal --> Degraded: "Refresh fails"
    Degraded --> Normal: "Refresh succeeds"
    Degraded --> Alert: "Age exceeds limit"
    Alert --> Normal: "Refresh succeeds"
    

A convenient place to keep settings is not automatically a safe place to keep secrets.

Never store secrets

Passwords, private keys, access tokens, and connection strings with credentials do not belong in remote config values. Values can be seen by people with dashboard access, they appear in audit history, and, for client-side use, they are delivered to devices where users can read them. Keep secrets in a dedicated secrets manager.

Assume client values are public

Anything sent to a browser or phone can be read by the person holding it. Do not put internal addresses, private pricing logic, or unreleased plans in values that reach clients. Even if you hide the value in the interface, it still travelled over the network.

Do not use values as permissions

A value that says “this user may export” decides what the interface shows. It must not be the only guard. The server must check permission for real, every time, because clients can be tampered with.

Protect who may change values

Changing a value is a production change. Limit who can edit Production, use approval workflows where your plan supports them, and keep the audit log on. Give automation, such as scripts that change values, narrow credentials and rotate them regularly.

Mind the data inside traits

Segment rules use traits. Send only the facts needed for targeting, such as plan and region, and use internal identifiers rather than emails or names.

As more people can change more values, rules keep the system trustworthy.

Give every value an owner

For each feature, a named person or team is responsible. They decide when it changes, answer questions about it, and remove it when it is no longer needed. Record the owner in a tag or the description.

Levels of access

A simple and effective rule is three tiers. Everyone on the engineering team may change values in Development. A wider group, including testers and product managers, may change Staging. A small group, or an approval workflow, controls Production. Where your plan includes finer roles, use them.

Change requests

In plans that offer them, change requests let one person propose a change and another approve it before it takes effect, much like a code review. Use them for values that touch money, safety, or legal rules, such as pricing thresholds and rate limits.

Scheduled changes

Where available, a change can be scheduled for a future time. A promotional banner can go live at midnight on a holiday without anyone being awake, and a second scheduled change can restore normal text afterwards. Scheduling also helps with changes that must happen outside busy hours.

The audit log

Flagsmith records who changed what and when. Use it to answer “what changed?” during incidents, to review activity, and to demonstrate control to auditors.

If you cannot see a value’s effect, you cannot tell whether a change helped or hurt.

Log the effective value

Have your settings module log the value actually in use, with the feature name, at start-up and whenever it changes. When someone asks “what timeout was the payment service using at three in the afternoon?”, you can answer from the logs.

Mark changes on graphs

Send value-change events from Flagsmith to your monitoring tool using webhooks or integrations, so a marker appears on your error and speed graphs at the exact moment of a change. This makes the connection between a change and its effect obvious.

Measure what the value affects

• For a timeout: the rate of timeouts and the rate of failed payments.
• For a page size: the page load time and the number of next-page clicks.
• For a rate limit: the number of rejected requests and the load on the system.
• For a message: the number of support contacts and clicks on its link.

Watch the machinery too

• Age of the rules held in server memory.
• Success rate of refreshes.
• How often defaults were used instead of real values.
• Number of validation failures, which suggests mistakes in the dashboard.

flowchart LR
    FS["Flagsmith change events"] --> MON["Monitoring tool"]
    APP["Application logs of effective values"] --> MON
    MET["Metrics on what the value affects"] --> MON
    MON --> DASH["Graphs with change markers"]
    MON --> AL["Alerts on staleness and failures"]
    

The best time to plan how to undo a change is before you make it.

The goal

When a value change goes badly, you want to return to a good state quickly and calmly. Because values live outside the code, a rollback is just another value change, which can be far faster than redeploying software.

Before you change

• Note the old value. Write it in the change request, the ticket, or a chat message, so nobody has to dig for it.
• Know the speed. Understand how long the change will take to reach servers and devices, so you know how long to wait.
• Prepare the rollback. If your plan supports scheduling, you may even schedule a return to the old value as a safety net.
• Decide the trigger. Write a sentence such as “if the error rate stays above the limit for ten minutes, restore the old value”.

During an incident

1. Check the audit log for recent changes to values and flags.
2. Restore the previous value of the most likely suspect.
3. Wait for the change to propagate, and watch the graphs.
4. If it was not the cause, restore the next suspect, and keep notes.

Where history comes from

The audit log shows past changes and who made them. Some plans offer versioning of feature states, which keeps earlier versions available to compare or restore. Check which of these your plan includes, and rely on them, but still keep your own notes of important changes.

flowchart TD
    A["Problem noticed"] --> B["Check audit log for recent value changes"]
    B --> C{"Suspect found?"}
    C -->|"Yes"| D["Restore the previous value"]
    C -->|"No"| E["Look at code deployments and other causes"]
    D --> F["Wait for propagation and watch graphs"]
    F --> G{"Problem gone?"}
    G -->|"Yes"| H["Record what happened and why"]
    G -->|"No"| B
    

Remote config is one tool among several. Each has its place.

The common alternatives

• Constants in code: simplest and safest, but every change needs a release.
• Configuration files: shipped with the application, changed with a deployment.
• Environment variables: set when a process starts, usually needing a restart to change.
• A database table: flexible and under your control, but you must build the editing screens, history, and targeting yourself.
• Cloud parameter stores: managed key-value services offered by cloud providers, good for server settings and secrets, usually without user targeting or rollouts.
• A remote config service such as Flagsmith: a dashboard, targeting, rollouts, history, and SDKs, ready-made.

Using them together

Most healthy systems use several. Secrets go in a secrets manager. Deployment details such as database addresses go in environment variables or configuration files. True constants stay in code. Tunable, targetable, frequently changing settings go in remote config. Each tool does what it does best.

Common ways teams use remote config values. These describe general practices, not any named customer.

A few proven shapes cover most uses.

How the patterns combine

Real systems blend them. An emergency “reduce load” switch might be an operational dial, a switch plus a message, and a named selector at once: the state turns on a reduced mode, the value chooses the level, and a text value tells users what is going on. Keep each piece simple, and let them work together.

flowchart LR
    S["State: reduced mode on"] --> A["Application reduces load"]
    V1["Value: level 2"] --> A
    V2["Value: message text"] --> U["Users see a clear notice"]
    A --> U
    

These traps catch teams again and again.

More mistakes to avoid

• Unclear names and missing units. Nobody knows whether “thirty” means seconds or items.
• Secrets in values. Use a secrets manager.
• Environment drift. Staging no longer resembles Production, so tests mislead.
• Mixed conventions about the disabled state. Some code reads the value when off, some does not.
• Settings that should be constants. A value that never changes is a risk with no benefit.
• Pointing a test app at Production. A classic way to change live values by accident.
• Ignoring propagation delay. Expecting an instant effect on every server and device.

If you keep one page of this guide, keep this one.

Values add paths through your code. Each one deserves a test.

Test the code, not the live service

Automated tests should not depend on the live Flagsmith service or on whatever someone has set in the dashboard today. Use the offline mode of an SDK, or a small replacement that returns the exact values a test needs. Tests then run fast, give the same result every time, and cannot be broken by someone editing a setting.

What to test

• Normal values: the code behaves correctly at typical, smallest, and largest allowed values.
• Bad values: wrong type, empty, zero, negative, and absurdly large values are rejected and replaced by a fallback.
• Missing values: when the feature does not exist, the default is used.
• Disabled state: the code treats “off” according to your team’s convention.
• Changes while running: if the value changes during use, nothing breaks, and long-running operations behave sensibly.
• Different groups: users in each segment receive the expected value.

Test in a real environment too

Keep a Staging environment where values are set on purpose, and run an end-to-end test against it. This proves that keys, addresses, and rules work together, which fakes in unit tests cannot show.

An honest look at what remote config gives you and what it asks of you.

The main trade-offs in plain words

When a value does not behave as expected, start with the symptom.

A calm routine for any problem

1. Check what changed. Read the audit log and recent deployments first.
2. Check the effective value. Look at what a particular identity actually receives, including overrides.
3. Check the code’s view. Look at the logged effective value in your application.
4. Check timing. Has enough time passed for caches and refreshes?
5. Fix and guard. Correct the cause, then add validation, logging, or a test so it is caught sooner next time.

Let us follow one setting through its whole life, to see how every idea in this guide fits together.

An online store calls an outside payment provider whenever a customer pays. The code waits a certain number of seconds for the provider to reply and, if nothing arrives, tries again a few times. For years, these numbers were written into the code. The team decides to turn them into remote config values.

Step 1: Define the features

The team creates two features. The first is “payment-provider-timeout-seconds”, described as “how long to wait for the payment provider before giving up, in seconds, allowed range one to thirty, default eight, owned by the payments team”. The second is “payment-retry-count”, described in the same careful way with an allowed range of zero to five and a default of two.

Step 2: Wire them into the code

A settings module reads each value, converts it to a whole number, checks the allowed range, and falls back to the default if anything is wrong. The payment code asks the settings module, never Flagsmith directly. The module also logs the effective values when the service starts and whenever they change.

Step 3: Set the values per environment

In Development, the timeout is thirty seconds, to give engineers time to debug. In Staging, it is ten. In Production, it is eight. The same two features exist everywhere, with different values in each place, and a change in one never touches the others.

Step 4: A busy evening

One night, the provider begins to answer slowly. Failed payments rise on the team’s graph. The engineer on call checks the audit log, sees no recent changes, and decides to tune the settings. They note the old values, then raise the timeout to twelve and lower the retry count to one, so that slow requests are not multiplied by retries.

Step 5: The change spreads

Flagsmith saves the change and records it in the audit log, and a webhook posts a message to the team chat. Servers using local evaluation pick up the new values at their next refresh, within about a minute. A marker appears on the failure-rate graph at the moment of the change, and the line starts to fall.

Step 6: Recovery and clean-up

An hour later the provider recovers. The engineer restores the original numbers, using the values they wrote down, and the marker on the graph shows the return to normal. In the morning, the team writes a short note in their incident record explaining what happened and what was changed. They also decide that the retry count deserves an approval step in future, because it affects customers directly, and enable a change request for it.

sequenceDiagram
    participant Eng as On-Call Engineer
    participant FS as Flagsmith
    participant Chat as Team Chat
    participant Srv as Payment Servers
    participant Mon as Monitoring
    Mon->>Eng: Failure rate rising
    Eng->>FS: Raise timeout to 12 and lower retries to 1
    FS->>Chat: Webhook announces the change
    FS->>Mon: Change marker on the graph
    Srv->>FS: Next refresh within about a minute
    FS-->>Srv: New values
    Mon->>Eng: Failure rate falling
    Eng->>FS: Restore the original values later
    

Most teams do not start from scratch. They already have settings scattered through their code, and need a calm way to move them.

Start with an inventory

Search your code for numbers and phrases that might need to change: timeouts, limits, page sizes, thresholds, messages, and provider names. List each one with where it lives, what it does, who owns it, and how often it has changed in the last year. You will often find that most never change, and a handful change often. Those few are your first candidates.

Choose a few good candidates

Pick settings that are small, harmless to reveal, easy to understand, and that the team has actually wished to change quickly. Avoid starting with the most critical setting in the company. Early successes build trust.

Build the settings module first

Before moving any values, create the module that will read, convert, validate, and default them. Fill it with the current hard-coded numbers as defaults. At this point nothing has changed in behaviour, because Flagsmith has no values yet and the defaults match what the code always did.

Create the features with matching values

For each chosen setting, create a feature in Flagsmith with the current value in every environment, and a good description. Because the value matches the default, the application’s behaviour stays the same.

Compare, then trust

For a time, let the module log whenever the Flagsmith value differs from the old hard-coded one. When the two agree for a good period, and you have confirmed that the application reads values correctly, you are free to change values from the dashboard with confidence. Finally, remove the old constants from the code, leaving only the defaults in the settings module.

flowchart LR
    A["Inventory settings"] --> B["Pick a few good candidates"]
    B --> C["Build settings module with current values as defaults"]
    C --> D["Create features with the same values"]
    D --> E["Compare and log differences"]
    E --> F["Change values from the dashboard"]
    F --> G["Remove old constants"]
    

Before you rely on remote config for something important, walk through these questions with your team.

How to use the checklist

Hold a short review before your first important setting goes live, and again each time your use grows in a big way. Go through each row and ask for a real answer, not a hope. Any row where the team hesitates is a place where something will eventually go wrong. Write down each gap, give it an owner, and fix the most dangerous first.

Every important word in this guide, in one place.

Remote config values turn the small numbers and words buried in your code into dials you can reach from a dashboard. Flagsmith stores them alongside flags, lets you set them per environment, group, and person, hands them out in controlled shares for experiments, and records every change. Used with care, they make your software faster to tune, safer to change, and easier to rescue in a crisis. Used carelessly, they become one more source of outages, so good names, safe defaults, validation, and gradual rollouts matter as much as the tool itself.