A flag you cannot measure is a switch in the dark. You do not know if it works, if it matters, or if it is safe to remove.

Flags are easy to make and hard to forget

Creating a flag takes a minute. Removing one takes a conversation, a code change, a deployment and some courage. So flags pile up. Teams that ship quickly often end up with hundreds, many of them finished long ago. Each leftover flag is a small risk: it adds a branch to the code, a name to the dashboard and a chance that someone switches it by mistake.

Four questions analytics can answer

The cost of not knowing

Without measurement, teams make two opposite mistakes. They keep flags for ever “just in case”, because nobody can prove they are unused. Or they remove a flag that looked unused and break a rarely visited feature, such as a yearly report. Both mistakes are cheap to avoid with a few weeks of evidence.

A small set of terms explains the whole subject. Learn them once and every later chapter reads easily.

flowchart LR
    A["Your application asks about a flag"] --> E["Evaluation happens"]
    E --> C["SDK counts it"]
    C --> B["Counts are batched"]
    B --> F["Sent to Flagsmith"]
    F --> D["Dashboard shows charts"]

Read the figure from the left. Your application asks about a flag, and that question is an evaluation. If analytics is enabled, the SDK adds one to a local counter for that flag. After a short wait, the SDK sends the batch of counters to Flagsmith, which stores them by flag, environment and time. The dashboard then draws charts from the stored counts. The key lesson is that the chart is a summary of messages sent by your apps, so it can only be as complete as those messages.

Several kinds of measurement sit near feature flags. Knowing which one you are looking at prevents wrong conclusions.

The core idea

Flag analytics answers one narrow question: how often was each flag evaluated, where and when? It describes the use of the flags themselves. It does not directly tell you whether customers liked a feature, whether sales rose or whether the site was fast. Those are different questions, answered by different tools.

Four neighbouring tools

What flag analytics cannot tell you

• It does not tell you if a feature is liked. A flag can be evaluated a million times for a feature nobody wants.
• It does not prove a flag is correct. It counts questions, not whether the answers were right.
• It does not usually list each user who received each value. It is mainly a count, not a per-person record.
• It is not an audit log. It records usage, not who changed what.

Everything in analytics is built on one small event. Understanding it removes most confusion about the numbers.

The moment of asking

Somewhere in your code is a line that says, in effect, “is the new checkout enabled for this user?”. That line asks the SDK for a flag. The SDK looks up the state, from a stored copy or from Flagsmith, and returns the answer. That whole step is one evaluation. If the code asks ten times on one page, there are ten evaluations, unless the code is written to ask once and remember.

Evaluation is not a request

Two numbers are often mixed up. An API request is a network call from your application to Flagsmith, such as “give me all flags for this user”. An evaluation is a single question about one flag, usually answered from data the SDK already holds. One request can supply the data for hundreds of evaluations. So evaluation counts are normally far higher than request counts, and the two charts measure different things.

Why this matters

If a flag shows zero evaluations, that is strong evidence that no running code asks about it, but only if analytics was enabled in all the places that could ask. If a flag shows ten thousand evaluations an hour, that is evidence of heavy use in code, not of ten thousand customers. Every interpretation must keep the definition in mind.

Between the question in your code and the bar on the chart lie several small steps. Each one can add delay or lose a little data.

The five steps

sequenceDiagram
    participant App as Your application
    participant SDK as Flagsmith SDK
    participant FS as Flagsmith service
    participant UI as Dashboard
    App->>SDK: Is flag X enabled?
    SDK-->>App: Yes or no
    SDK->>SDK: Add one to the tally for X
    Note over SDK: Wait for the batch interval
    SDK->>FS: Send the batch of tallies
    FS->>FS: Add to time buckets
    UI->>FS: Request chart data
    FS-->>UI: Counts by time

Where delay and loss come from

• Batch wait. Counts sit in memory for a short period before being sent, so the chart lags a little behind real time.
• Processing. Flagsmith may add counts to storage in the background, so there is a further short lag.
• Sudden shutdown. If an application stops before sending its latest batch, those last counts can be lost.
• Network failure. A failed send may drop or retry the batch, depending on the SDK.

Flag analytics does not appear by magic. Each application, through its SDK, must be told to collect and send counts.

It is an SDK setting

Most Flagsmith SDKs have an option, commonly named something like “enable analytics”, set when the SDK is created. When it is off, the SDK does not count. When it is on, it keeps tallies and sends them. Because it is a per-application setting, you may find that some of your services report and others do not. The chart will then show only what the reporting ones saw.

A rollout checklist

Coverage is the heart of trust

The statement “this flag has zero evaluations” means nothing until you know every place that could evaluate it reports data. Old mobile app versions, batch jobs that run monthly, partner integrations and rarely used admin tools are the usual silent corners. A flag can look dead when one forgotten script quietly depends on it.

The dashboard presents flag usage as simple charts. Learn what each part shows and what it hides.

Where to look

Open a project, choose an environment and open a flag. In versions that include flag analytics, an Analytics area, tab or panel for that flag shows evaluation counts over time. There is also usage reporting at the organisation level, covering API traffic for the whole account. Menu names differ between versions, so look for words such as Analytics, Usage or Evaluations.

The chart in plain words

The horizontal axis is time. The vertical axis is a count. Each bar or point is the number of evaluations that arrived in that slice of time. A flat line at zero means nothing reported. A steady line means steady use. A sudden step up means a release, a campaign or a new service began asking. A sudden drop to zero means something stopped: a deployment, an outage or a change that bypassed the flag.

The same data looks very different at different zoom levels. Choose the range for the question you are asking.

Time ranges

Dashboards usually offer a few ranges, such as the last day, the last week or the last month. Available choices and retention depend on your plan and version. The short range suits “did the rollout just work?”. The long range suits “is anything still using this flag?”.

Buckets

A bucket is a slice of time, say one hour or one day, into which counts are added. In a day-by-day chart, each bar is a day’s total. Larger buckets smooth out noise but hide short events. Smaller buckets reveal bursts but look jagged.

Time zones

Charts may group by days in UTC, the neutral world clock, or in your browser’s local zone, depending on version. A “day” boundary can therefore fall in the middle of your afternoon. When comparing with other tools, make sure both use the same zone.

flowchart TD
    Q["What do I want to know?"] --> A["Right now: short range"]
    Q --> B["Regular use: month range"]
    Q --> C["Safe to delete: longest range plus rare-job check"]
    A --> D["Fine buckets show minutes"]
    B --> E["Daily buckets show rhythm"]
    C --> F["Look for monthly and yearly spikes"]

Most wrong conclusions from flag charts come from mixing up what is being counted. Here are the three classic traps.

Trap 1: “ten thousand evaluations means ten thousand users”

One user can trigger many evaluations. A page that checks a flag each time a component draws will produce hundreds from a single visit. Conversely, a flag checked once per session produces one. So the same number of users can give wildly different evaluation counts depending on how the code was written.

Trap 2: “evaluations equal API calls”

An SDK typically fetches flags once and answers many evaluations from memory. Evaluations can be a thousand times more frequent than requests. If you try to predict your bill from evaluations, you will overestimate. If you try to predict flag usage from request counts, you will underestimate.

Trap 3: “the enabled count equals the audience”

A flag may be evaluated and return “off” for most users. The number of evaluations tells you the flag was asked about, not that the feature was shown. To learn how many users saw the feature, you need the product’s own events, tagged with the flag state, as Chapter 17 explains.

Besides per-flag charts, Flagsmith shows how much your whole account talks to it. This view is about capacity and cost.

What usage reporting shows

Organisation-level usage typically breaks traffic into kinds of request: calls that fetch flags, calls that fetch or update identities and traits, calls that download an environment document for local evaluation, and calls to the management API. Exact categories differ by version. Plans often include a monthly allowance, and the usage view shows how close you are to it.

Why this differs from flag analytics

What drives request volume

• The number of users and how often each opens your app.
• Whether SDKs refresh flags frequently or cache them for longer.
• Whether you use identity-based requests, which are made per user, or environment-wide requests.
• Whether servers use local evaluation, which replaces many requests with periodic downloads.
• Retries and misbehaving clients, such as an app stuck in a loop.

Reading the trend

Plot usage against your own business numbers, such as daily active users. If requests per user steadily rise, something has become chattier. If they fall sharply, a cache or a bug may have stopped traffic. The ratio is usually more informative than the raw total.

How your application evaluates flags changes what analytics sees. The same flag can look different depending on who asks.

Two families of SDK

Client-side SDKs run in browsers and mobile apps. They usually ask Flagsmith for the flags of one user and then answer evaluations from the result. Server-side SDKs run in your backend. They can either ask Flagsmith for each answer, or download the whole rule set and evaluate locally. The second approach is called local evaluation. It saves network calls and makes answers faster.

What changes for analytics

Behaviour varies between SDK languages and versions. Some report analytics in local mode and some need a separate setting. Verify with a test flag rather than assuming.

flowchart LR
    B["Browser or phone"] -->|"fetch flags, send batches"| F["Flagsmith"]
    S1["Server, remote mode"] -->|"ask per request, send batches"| F
    S2["Server, local evaluation"] -->|"download rules, send batches"| F
    F --> D["Analytics charts"]

Flag charts are reliable for trends and for yes-or-no questions. They are not an accounting ledger. Know where they blur.

Sources of error

What the errors mean in practice

For trends, shape and presence, small losses do not matter. A flag with a million evaluations is clearly used whether the true figure is 950,000 or 1,050,000. The danger lies at the edges. A flag with five evaluations a month might be a vital rare job, or noise. An apparent zero might be a small loss. For deletion decisions, absence of evidence is not enough, so combine analytics with a search of the code and a conversation with the owner.

flowchart TD
    Z["Chart shows near zero"] --> C1["Is analytics enabled in every app that could ask?"]
    C1 --> C2["Does the code still mention the flag?"]
    C2 --> C3["Is there a rare job: monthly, yearly, seasonal?"]
    C3 --> C4["Does the owner agree?"]
    C4 --> R["Safe to retire"]

The most popular use of flag analytics is spring-cleaning. Done carefully, it shrinks risk and complexity.

Kinds of stale

A clean-up routine

When you release a feature gradually, flag analytics tells you whether the release is reaching the places you expect.

What to watch

During a staged rollout, the flag’s evaluation line shows whether the new code path is being asked about at all. If the evaluations never rise after deployment, either the new build is not live, the code never calls the flag, or reporting is off. This is a fast sanity check, long before business results appear.

A rollout view

Remember that evaluation counts do not show how many users received “on”. Pair the chart with your product metrics and error rates, which tell the real story of health.

sequenceDiagram
    participant R as Release owner
    participant F as Flagsmith
    participant A as Analytics chart
    participant M as Monitoring
    R->>F: Raise rollout to ten per cent
    F-->>A: Evaluations continue
    R->>A: Check the flag is being asked about
    R->>M: Check errors and speed
    M-->>R: Healthy or not
    R->>F: Proceed, hold or roll back

Usage numbers help you predict next quarter’s bill and next year’s infrastructure. They are an early warning system.

Forecasting from trends

Plot monthly API requests alongside active users. Divide one by the other to get requests per user. If your user base is expected to double and the ratio is stable, expect roughly double the requests. If the ratio is rising, find out why before the bill does it for you.

Ways to reduce request volume

If you self-host

If you run Flagsmith yourself, the same numbers drive server sizing, database growth and the task processor workload that handles analytics writes. Analytics data accumulates. Plan storage, retention and cleaning so it does not slowly consume the database. Settings and defaults differ by version, so check the self-hosting documentation.

Flagsmith’s built-in charts answer simple questions. For richer questions, connect flags to the tools you already use.

The two directions

Flagsmith offers integrations of several types, which vary by version and plan. Some send flag change events to monitoring and chat tools, so a flag change appears as a marker on your performance charts or a message in a channel. Others send flag state or evaluation information to product analytics and data tools, so you can analyse behaviour by flag value. Check your own list of integrations for the tools that are currently supported.

flowchart LR
    F["Flagsmith"] -->|"flag change events"| M["Monitoring tool"]
    F -->|"flag state or identity data"| P["Product analytics"]
    F -->|"notifications"| C["Chat channel"]
    F -->|"events"| W["Data warehouse"]
    M --> I["Insight: did the change cause a problem?"]
    P --> J["Insight: did behaviour differ?"]

The question “did the new feature help?” needs flag state and user behaviour in the same place. Here is how teams get there.

The idea

Your product analytics tool records events like “clicked buy” or “finished onboarding”. If each event also carries the value of the relevant flag for that user, such as “new checkout: on”, you can compare groups. Did users with the flag on finish onboarding more often than users with it off? That comparison is the heart of measuring a feature’s effect.

Three ways to attach the flag

Keep the groups honest

For a fair comparison, the groups must be alike apart from the flag. If staff are in the “on” group and customers in the “off” group, any difference may be about who they are. Percentage splits, which assign users randomly by a stable calculation, give similar groups. Remember also that a user must have actually seen the feature to be compared, not only been assigned to the group.

A flag splits users. An experiment asks which side did better. The split is easy. The reading of results is the hard part.

What an experiment needs

An experiment compares two or more versions of a feature using a fair split, a clear measure, enough users and a planned length. Flags handle the split. The measurement and the statistics usually live in a product analytics or dedicated experimentation tool. Flagsmith’s own capabilities for experiments and the exact tools it connects with differ between versions and plans, so check what yours offers.

Common ways to go wrong

Where flag analytics fits

The evaluation chart is a health check for the experiment: is the flag being asked about by both groups, and is traffic steady? It cannot tell which version won. That answer lives in your outcome data.

Not every flag is on or off. Some return one of several values. Counting then becomes a question of which value.

What multivariate means

A multivariate flag has more than two possible values, for example a button colour of “blue”, “green” or “orange”, each assigned to a share of users. Flagsmith manages the split. For analytics, the new question is not only how often the flag was evaluated but how often each value was returned.

What you can and cannot see

Built-in flag analytics is primarily about evaluation counts per flag. Depending on version, richer breakdowns by value may or may not be available. Where they are not, attach the returned value to your own events, as Chapter 17 describes, and analyse the split there. Check your version’s documentation for what the Analytics view shows for multivariate flags.

Charts that nobody looks at are decoration. A small, purposeful dashboard turns numbers into habits.

Start from questions, not data

Write down the three or four questions people actually ask: Are my flags used? Is the rollout reaching traffic? Are we near our plan limit? Which flags are old? Each question becomes one panel. Anything that does not answer a question is left out.

A sensible starter dashboard

Design habits

• Label units on every chart: “evaluations per day”, not just “count”.
• Use the same time zone everywhere.
• Put the most important panel top left, where people look first.
• Keep it to one screen. A long scroll hides the very thing you wanted to show.
• Show a note about coverage: which services report.

Nobody watches a dashboard all day. Alerts watch for you and speak only when something deserves attention.

Useful alerts

Where to build them

Flagsmith itself offers limited alerting in some places, such as notifications about usage in some plans. For fine-grained alerts, send the numbers or events to your monitoring tool through an integration or the API, and create alerts there, where on-call rotas and notification channels already exist. Check what your version supports.

Avoiding alert fatigue

An alert that fires too often is soon ignored. Set thresholds from real history, give each alert an owner and an action, and delete alerts nobody acts on. Fewer, trusted alerts beat many noisy ones.

flowchart LR
    N["Numbers from Flagsmith"] --> T["Threshold from real history"]
    T --> A["Alert fires"]
    A --> O["Named owner"]
    O --> X["Documented action"]
    X --> L["Review: keep, tune or delete the alert"]

Cleaning once is a project. Cleaning every month is a habit. Analytics makes the habit cheap.

The monthly rhythm

Making it stick

• Give every flag an owner and an expected end date when it is created, using the description or tags.
• Publish one number each month: flags created, flags removed, flags older than ninety days.
• Make removal part of the “definition of done” for any feature behind a flag.
• Keep deletion rights narrow so removals are deliberate.

Two records sit near each other and are often confused. One says what was used. The other says what was changed.

Using them together

The two records answer the classic incident question when combined. The audit log says “at 14:02 someone raised the rollout to fifty per cent”. Flag analytics, alongside your error charts, shows “at 14:03 evaluations rose and errors followed”. Neither alone would tell the story as clearly.

flowchart TD
    I["Incident: errors rise at 14:03"] --> AL["Audit log: change at 14:02"]
    I --> FA["Flag analytics: evaluations rose at 14:03"]
    AL --> C["Cause: rollout step"]
    FA --> C
    C --> R["Roll back and review"]

Flag counts feel harmless, but the data around them can touch people. Handle it with the same care as other analytics.

What data is involved

Built-in evaluation counts are mostly numbers by flag, environment and time, which carry little personal information. But the wider picture includes identities and traits, which may describe real people, and integrations, which send data to other tools. Those are where privacy questions arise.

Safe habits

Security of the pipeline

SDKs send counts using your environment key. A client-side key is public by nature, so assume anyone could send false counts with it. Do not make business decisions that depend on these counts being tamper-proof. Treat them as helpful signals, not as audited facts.

When a chart looks wrong, the cause is usually one of a handful of ordinary things. Work through them in order.

flowchart TD
    S["Chart shows nothing or looks wrong"] --> A["Is analytics enabled in the SDK?"]
    A --> B["Is the app using the right environment key?"]
    B --> C["Is the app version deployed and running?"]
    C --> D["Can the app reach Flagsmith: network, blockers, firewall?"]
    D --> E["Is the time range and time zone right?"]
    E --> F["Has enough time passed for batches?"]
    F --> G["Is the flag name spelled the same in code and dashboard?"]

Common symptoms and causes

An anti-pattern is a habit that looks sensible and causes trouble later. These five are the most common with flag analytics.

Flag analytics is cheap, simple and very useful. It is also approximate and narrow. Seeing both sides helps you use it well.

Built-in analytics compared with other ways

Cost and overhead

Counting costs very little: a tally in memory and an occasional message. For most applications the extra load is negligible. In extremely busy services, check that analytics does not add noticeable load, and if it does, consider enabling it on a sample of instances. Always test the effect before widening.

Experienced teams repeat a short list of habits. New teams repeat a short list of mistakes. Here are both.

Habits worth building

Mistakes to catch early

Numbers need owners. Without them, charts are admired once and then forgotten.

Who owns what

Permissions around data

Viewing analytics, identities and integration settings are all permissions in Flagsmith, and plans may offer fine-grained control. Give read access widely to those who need to understand usage, and keep changes to integrations and keys narrow. A short written policy of one page, covering who may enable integrations and what data may leave, avoids arguments later.

Documentation that helps

• A one-page glossary: evaluation, request, identity, coverage.
• A runbook for “chart looks wrong” with the path from Chapter 25.
• A list of integrations with owners and purposes.
• A statement of retention: how long analytics are kept and why.

Teams do not need everything at once. Grow in steps, and take the next step when the current one feels comfortable.

flowchart LR
    L1["Level 1: analytics on, charts viewed ad hoc"] --> L2["Level 2: coverage list, monthly usage review"]
    L2 --> L3["Level 3: hygiene routine, owners and end dates"]
    L3 --> L4["Level 4: integrations, flag markers, alerts"]
    L4 --> L5["Level 5: flag-tagged product events and experiments"]

To finish, here is one imaginary company taken from “we have no idea” to a calm, measured flag practice, using everything in this guide.

BrightCart, the imaginary online shop, has grown to ninety engineers and about three hundred flags, a web app, an Android app, an iOS app and nine backend services. Nobody knows which flags are alive. A recent incident, in which an engineer removed an apparently unused flag that a monthly invoicing job still read, has made the team nervous. The platform lead is asked to bring order.

What would have gone wrong without the routine?

Without it, the team would have kept adding flags until the dashboard became unreadable, or deleted by hunch until another job broke. Plan limits would have arrived as a surprise bill. The next experiment would have been argued from opinion, because nobody could say which users saw what. Each risk is ordinary, and each is closed by a habit in this guide.

Rules are easier to remember as stories. Here are five typical chart shapes, what they meant and what the team did.

Story 1: the line that never rose

A team released a new search feature behind a flag and raised the rollout to twenty per cent. An hour later the evaluation line was still flat. The release owner did not celebrate or panic. She checked the path: the flag was spelled with a capital letter in the code and a lower-case letter in the dashboard. The code was asking for a flag that did not exist, and was quietly using its default. A one-letter fix brought the line to life. The lesson is that a flat line right after a release is a cheap, early warning that the code never reached the flag.

Story 2: the cliff after Tuesday

A flag that normally showed steady evaluations dropped to zero on a Tuesday afternoon. The team feared an outage. Looking at the deployment history, they saw that a backend service had been upgraded the same day and moved to local evaluation. The service was working perfectly. It just was not reporting counts in its new mode. Enabling the right setting restored the line. The lesson is to check analytics after changing how a service evaluates flags.

Story 3: the monthly heartbeat

A flag showed zero for twenty-seven days and then a burst of thousands of evaluations on the last night of the month. An engineer new to the team had marked it for deletion. The owner explained that it controlled month-end invoicing. The chart, viewed over a longer range, showed a perfectly regular heartbeat. The lesson is that the range you view decides whether you see the heartbeat at all.

Story 4: the sawtooth

One flag’s chart looked like a saw, with sharp spikes every five minutes. The cause was a mobile app that refreshed flags on a timer, with thousands of phones set to the same schedule after a common release. Counts were fine, but the burst loaded the service. The team added a small random delay to the refresh so phones no longer all arrived together. The lesson is that charts reveal patterns in your own code, not just in your users.

Story 5: the double staircase

During a percentage rollout, evaluation counts rose in two clear steps, matching the two times the release manager increased the percentage. The counts rose even though the flag was evaluated for everyone, so the team was puzzled. The reason was a new page that asked about the flag more often when the feature was on, because of the extra interface it drew. The lesson is that evaluation counts can change because behaviour changed, not just because traffic did.

Mobile apps are the hardest place to count. People forget to update, phones go offline and the operating system sleeps your app.

Why mobile data looks thin

A server runs all day and sends its batches on time. A phone does not. The app may be closed within seconds of opening, before a batch is sent. The phone may be in a tunnel, on aeroplane mode or short of battery. Mobile operating systems often pause background activity to save power. As a result, counts from mobile apps tend to arrive later and in smaller amounts than the real number of evaluations.

The long tail of old versions

When you ship a new mobile version, only part of your users upgrade quickly. Others keep old versions for months or years. An old version released before analytics was enabled will never report. An old version that uses a different flag name will evaluate a flag you think is dead. This is why flags that mobile apps depend on should be retired slowly and with care.

A safe rule for mobile flags

Do not remove a flag that a mobile app might read until you have measured how many users still run versions that read it. Your app store consoles or product analytics can tell you the share of users on each version. When the oldest version that reads the flag falls below a level you are comfortable with, plan the removal, and make the code’s default behaviour safe for those who remain.

Charts are kept per environment. Comparing them tells you whether your stages behave alike, and whether what you test is what you ship.

Staging versus Production

If a flag is evaluated thousands of times a day in Production but never in Staging, your tests are not exercising that code path. That is a finding, not just a statistic. It suggests missing test coverage for a feature customers use. If a flag is evaluated in Staging and never in Production, a feature may not have been deployed there, or may be reached only by a path real users never take.

Useful comparisons

Across projects

If your organisation has several projects, compare their flag counts, flag ages and request volumes. A project with three hundred flags and almost no traffic is a clean-up target. A project with twenty flags and enormous traffic is a capacity target. Uniform dashboards across projects make this easy to see at a glance, and a monthly one-page comparison is often enough to start good conversations.

flowchart LR
    D["Development counts"] --> C["Compare"]
    S["Staging counts"] --> C
    P["Production counts"] --> C
    C --> G["Gap: flag live in Production but untested in Staging"]
    C --> H["Healthy: same flags alive in all stages"]

Some flags exist to be switched in emergencies. Their analytics tell a different story: here, being busy is good and being silent is suspicious.

What a kill switch is

A kill switch is a flag that lets you turn off a risky or expensive part of your system quickly, such as a recommendation engine, a third-party payment option or a heavy report. Normally the flag is on and the feature runs. In trouble, someone turns it off and the system protects itself. These flags are meant to live for years.

What to watch

Rehearse the emergency

The scariest kill switch is the one that does not work when needed. Test them on a calm day in a safe environment: switch off, watch evaluations and behaviour, switch on again. Flag analytics supports the rehearsal by showing that the code is asking, but you must also confirm the feature really stops, using the application itself or its own metrics.

Protect these flags from clean-up

Because kill switches may be evaluated quietly for years, a naive hygiene routine might treat them as ordinary. Tag them clearly as operational, give them named owners and exclude them from automatic removal lists. A removal should require a written decision.

The dashboard answers common questions. Your own questions may need the data in your own tools.

Why export

Dashboards are limited by their design and by the retention of your plan. If you want to keep two years of history, join flag usage with sales, or draw a chart the dashboard does not offer, you need the numbers elsewhere. Flagsmith provides a management API, and depending on version and plan there may be endpoints for usage and flag analytics, along with integrations that stream events outward. Check the documentation for what is available to you.

A simple reporting pipeline

Safe habits for automation

• Use a dedicated credential with read-only rights where possible, never a person’s personal token.
• Respect rate limits, and avoid fetching more often than the data changes.
• Store the date of each fetch, so gaps are visible later.
• Document the pipeline so someone else can repair it.

Managers, product owners and executives need conclusions, not definitions. A few habits make numbers understandable and honest.

Say what it means in one sentence

Instead of “evaluations rose forty per cent”, say “the new checkout is being asked about much more, which means the release reached the busy pages as planned”. Always connect the number to a decision or a meaning. If you cannot, the number may not be worth showing.

Choose honest wording

Show uncertainty plainly

Because flag counts are approximate, say so in a short note: “Counts may miss a few per cent due to batching and blocked requests”. People trust numbers more when limits are admitted. They trust them less when a limit is discovered by surprise.

Some flags are silent for most of the year and vital for a few days. Analytics alone will call them dead. A calendar will not.

Flags with a rhythm

Think of tax season features, festival sales, year-end reports, school-term logic and holiday banners. Their charts show long flat stretches and short, intense bursts. A hygiene routine that looks only at the last thirty days will propose deleting them every month, and will be wrong each time.

Mark them clearly

Test before the season, not during

A flag that has been silent for ten months may depend on code that nobody has run since. Before its season, switch it on in Staging, run through the feature and confirm the evaluation counts appear. Finding a broken seasonal feature in the first minutes of the sale is the most expensive way to discover it.

flowchart LR
    Q["Quiet months"] --> R["Rehearse in Staging before the season"]
    R --> L["Launch: bursts of evaluations"]
    L --> V["Review after the season"]
    V --> K["Keep, simplify or retire"]
    K --> Q

The numbers you get depend on how your code asks. A few small habits in the code make the charts far easier to trust.

Ask once, near the decision

If a page checks the same flag in twelve places, the evaluation count is twelve times the number of page views, and it tells you little. Where practical, ask once at the point where the decision is made, keep the answer for the rest of that request or screen, and pass it along. Counts then look like real decisions, and charts are easier to compare over time.

Use clear, stable flag names

A flag name is a promise between code and dashboard. Use names that describe the feature, avoid spelling variations and keep one name per concept. If two flags secretly mean the same thing, analytics will split their counts and mislead you. When a flag must be renamed, create the new one, change the code, wait until the old one falls silent, and only then remove it.

Choose safe defaults

When Flagsmith cannot be reached, your code falls back to a default. Choose defaults that are safe: usually “off” for new features, and “on” for protective behaviour. Remember that defaults can hide problems from analytics, because a request that fell back to the default may not be counted the same way as a normal evaluation. Watch for flags that look steady while the service is actually failing to reach Flagsmith.

Keep flag logic thin

The more complicated the code around a flag, the harder it is to remove and the harder its counts are to interpret. A flag that guards one clear decision, such as which checkout page to show, is easy to measure and easy to retire. A flag woven through twenty functions makes every evaluation ambiguous: which decision was this count for? Prefer one flag per decision, and keep the branch small, so that when the flag’s work is done, deleting it is a short, safe edit rather than a risky rewrite.

It also helps to add a comment next to each flag check naming its owner and its planned removal date. When a future engineer meets the flag at three in the morning, that single comment answers two questions at once: whom to ask, and whether this flag is meant to stay. Small notes like this turn analytics findings into quick, confident actions.

Make the flag easy to find in code

Keep flag names in one place, such as a shared list or constants file in each application, rather than scattered strings. A single list makes it easy to search for every use of a flag before removal, and ensures spelling matches the dashboard. Teams that do this report that the Story 1 mistake in Chapter 32, a misspelt name, almost never happens again.

Before you act on a number, run through a short list. It takes two minutes and prevents most wrong conclusions.

The ten questions

Using the checklist as a team habit

The checklist works best when it is shared. In a review meeting, ask the person presenting a chart to answer the first four questions out loud before showing any conclusion. Over a few weeks, this becomes automatic, and the quality of discussion rises: people stop arguing about what a number means and start discussing what to do. New joiners also learn the vocabulary quickly, because they hear the same questions asked of every chart, whether it is a small flag or a major launch.

Keep a short log of times the checklist caught a mistake, such as a missing service in the coverage list or a time zone mix-up. These stories are the best training material you will ever have, because they are real, local and recent. Share one at each monthly review, and the habit will sustain itself.

Why the last two matter most

People tend to look for evidence that agrees with what they already believe. Asking what would prove you wrong is a simple discipline that breaks the habit. Asking the owner reminds you that a number is a clue to a human story: a launch, a quirk, a deadline. Charts rarely explain themselves.

Short, direct answers to the questions people ask most often about flag analytics in Flagsmith.

Flag analytics is a counter beside every switch. It is simple, approximate and very useful, as long as you know exactly what it counts.