Before learning any buttons, let us understand the problem the audit log solves.

Flags change behaviour without a release

A normal code change goes through a long road. It is written, reviewed, tested, built and deployed. Every step leaves a record, such as a commit, a pull request and a build number. A flag change skips most of that road. Someone clicks a switch, and the behaviour of the live product changes within seconds.

That speed is the whole point of flags. But speed without memory is dangerous. If nobody can see what was clicked, then a flag becomes a hidden hand moving things around in the dark.

Questions the history answers

• What changed? Which flag, which setting, which environment.
• Who did it? A person, or an automated tool using a key.
• When? The exact time, so it can be matched against graphs and error spikes.
• What was the old value? So you can go back.
• Why? Sometimes recorded in a comment or a linked request.

Four groups who depend on it

A few Flagsmith words appear in every audit entry. Let us make sure they are clear.

Organisation, project and environment

An organisation is your company account. Inside it live projects, usually one per product. Inside each project live environments, such as Development, Staging and Production. Each environment has its own settings for every flag.

Feature and feature state

A feature (or flag) is a named switch. It exists at the project level. A feature state is the setting of that feature in one environment: on or off, plus an optional value. So one feature has many feature states, one per environment.

Segments and overrides

A segment is a named group of users defined by rules. A segment override gives the feature a different setting for that group. An identity override does the same for one named user.

Who can act

People log in and act as users of the dashboard. Programs act through API keys. Either one may change things, and both can appear in the history.

The audit log is a time-ordered list of actions taken inside your Flagsmith organisation.

The simple definition

The audit log is a record that Flagsmith writes automatically each time something important is changed. Each line says roughly: “At this time, this actor did this thing to this object.” Lines are added at the top as time passes, so the newest change is first.

Nobody has to remember to write it

This is a key point. You do not fill in a form. The system writes the entry itself whenever a change is saved. That is why an audit log can be trusted more than a hand-written diary. A person can forget to write. The system does not forget.

What a typical entry holds

• The time of the change.
• The actor: the user, or the key used.
• A short description, such as “Flag state updated for feature checkout_v2 in environment Production”.
• The project and often the environment.
• A link to the object that changed, where the dashboard supports it.

People often mix up two related views. They answer different questions, so let us separate them.

The organisation or project audit log

This is the wide view. It lists changes across many objects: features, segments, environments, users, permissions and more. Use it to ask: “What happened in this project yesterday afternoon?”

The history of one flag

This is the narrow view. It shows the story of a single feature, often in one environment: when it was turned on, when its value changed, when an override was added. Use it to ask: “How did this flag get into the state it is in now?”

Side by side

Not every click is recorded, but the important ones that change behaviour or access are. Here are the usual families of events.

Flag events

• A feature is created, renamed, edited or deleted.
• A feature state is switched on or off in an environment.
• A value changes, including multivariate values and their percentages.
• Tags and descriptions are edited, in many versions.

Targeting events

• A segment is created, edited or deleted.
• A segment override is added, changed, reordered or removed.
• An identity override is added, changed or removed.

Environment and project events

• An environment is created, cloned or deleted.
• Environment settings change, such as requiring approval for changes.
• Keys are created or regenerated.

People and access events

• Users are invited, removed or given new roles.
• Permission groups change.

Workflow events

• A change request is created, approved, published or deleted.
• A scheduled change is set or cancelled.

What is not recorded

Ordinary reading is not a change, so the log does not fill up each time an app asks for flags. It would be huge and useless. The log is about writes, not reads. If you need to know which users were served which value, that is a different tool: evaluation analytics or your own application logs.

Let us walk through how to read a typical audit log page, from the top.

The order of lines

The newest entry is at the top. As you scroll down, you travel back in time. This matches the way we think about incidents: start with now, and look backwards until you find the culprit.

The columns or parts of each line

Filtering and searching

Busy projects produce many entries. Filters help you narrow down. Typical filters include a date range, a search for a flag name or text, a project or environment, and sometimes the type of object. In an incident, the best first filter is a time window around the moment the problem started.

Time zones

The dashboard may display time in your browser’s time zone, while exports and APIs often use UTC. A flag change at 16:00 in Kolkata is 10:30 in UTC. When you compare with a graph or a log from another tool, always compare in the same zone.

Let us take one imaginary entry apart, piece by piece, to see how to read it like a detective.

An example in words

Suppose the log shows: “Yesterday at 14:32, user Asha Rao, Flag state updated: checkout_v2, environment Production, enabled changed from off to on.”

The five questions every entry should answer

• Who? The actor.
• What? The kind of change.
• Which? The object and environment.
• When? The time.
• From what to what? The before and after.

An entry is only useful if you can tell who or what made the change.

Human actors

When a person logs in and clicks, the entry normally shows their name or email. This makes follow-up easy: you can ask them why. It also means that shared accounts are harmful. If five people use one login called “admin”, the audit log says “admin did it”, and the trail ends.

Machine actors

Programs may change flags through the Flagsmith API using a key. Examples are a deployment pipeline that turns on a flag after a successful release, or a script that creates flags from a configuration file. Entries for such changes may show the key or a service identity instead of a person.

Why naming keys well helps

If your keys are called “key1” and “key2”, then an entry that mentions them tells you nothing. If they are called “release-pipeline” and “terraform-sync”, the entry tells a story at once. Give every key a clear name that states the program and the purpose.

Single sign-on and identity

If your company uses single sign-on, the actor in the log can be tied to your central identity. When a person leaves the company and their identity is closed, you can still read what they did long ago, because the history names them.

When you open one feature, Flagsmith can show you how that feature has changed over time. This is often the fastest path to an answer.

Where it lives

On the feature’s page, in many versions, there is a section or tab that lists past changes for that feature, often with a way to switch between environments. It shows the same kind of facts as the wide audit log, but only for this feature, so there is far less noise.

Why it is easier than the wide log

In a busy project, the wide log might contain hundreds of lines per day. If you only care about one flag, you would have to search and filter. The single flag history does that filtering for you. It is like opening a patient’s file instead of reading the hospital’s whole daily diary.

Versions of a flag

Some Flagsmith versions and plans support versioning of feature states. Each saved change creates a numbered version, and you can look at an older version, compare it to the current one, and in some cases restore it. Where this exists, it gives you more than a sentence of description: it gives you the full old setting.

A flag in Production and the same flag in Staging are two different settings with two different histories.

Same flag, different timelines

A feature exists once in a project, but its state exists in every environment. Turning it on in Staging does nothing to Production. So the history of that flag in Production is a separate list from the history in Staging.

What this means for investigations

When customers report a problem, make sure you are reading the history of the right environment. A very common mistake is to open the Staging history, see a calm list, and conclude that nobody changed anything. The real change was in Production.

Reading across environments

It is useful to compare environments. If Staging was switched on two weeks ago and Production only yesterday, you can see how long the flag was tested before release. This pattern, repeated, tells you about your team’s release discipline.

When something goes wrong, a calm, repeatable method beats frantic clicking. Here is a path that works.

flowchart TD
    A["Problem reported or alert fires"] --> B["Note the exact start time"]
    B --> C["Open audit log for the right environment"]
    C --> D["Filter to a window before and after the start"]
    D --> E{"Any change just before the problem?"}
    E -- "Yes" --> F["Read the entry: who, what, which, when, from and to"]
    E -- "No" --> G["Widen the window and check other objects"]
    G --> H{"Found a candidate?"}
    H -- "No" --> I["Look outside flags: releases, infrastructure, data"]
    H -- "Yes" --> F
    F --> J["Contact the actor for the reason"]
    J --> K["Decide: revert, fix forward, or leave"]
    K --> L["Record the finding and the action"]

Step 1: Write down the start time

Before you open anything, find the first moment the problem was seen: an alert time, a graph bend, a customer message. Write it down with its time zone. Everything else is measured against this time.

Step 2: Open the right log

Choose the project and environment where customers are affected. Usually it is Production.

Step 3: Filter by time

Look at one hour before the start time and a little after. Changes made long before are rarely the cause of a sudden problem, unless a scheduled change fired later.

Step 4: Read candidates carefully

For each entry in the window, ask the five questions. Prefer entries that touch features related to the broken part of the product.

Step 5: Contact the actor

Ask a short, friendly question. Aim is to learn the intention, not to blame. Many incidents are honest mistakes, and a calm tone gets you the facts faster.

Step 6: Decide the response

• Revert if the change is clearly the cause and the old state is safe.
• Fix forward if reverting would cause other trouble.
• Leave it if the change is unrelated.

Step 7: Record what you learned

Write a short note: what happened, which entry, what was done. This note is the first page of your incident history.

Finding the change is half the job. The other half is returning safely to a good state.

Reading the before and after

A good entry tells you the previous value and the new one. If the entry says that the enabled state moved from off to on, going back is simple: switch it off. If it says that a text value changed from “Pay now” to “Buy now”, you can set it back.

When the change is complex

Some changes touch many things at once: several overrides, a percentage split and a value. For these, a one-line entry may not be enough to rebuild the previous state. This is where flag versions are very valuable, because they keep the whole old picture.

Rolling back with care

• Check that the old state is safe. A flag that was on for three months might depend on changes made in the meantime.
• Check the environment before you click.
• Make the revert as a normal change, so it also appears in the audit log.
• Tell the people who watch the product.

A revert is also a change

Going back does not erase history. It adds a new line: “Asha switched it off at 14:41”. The old line stays. That is exactly how a good history should behave. Nothing is hidden, and the whole story, including the mistake and the fix, can be read later.

Change requests add a layer of review. The audit log records how that review unfolded.

A quick reminder

A change request is a proposal. Someone suggests a change, others review it, and only after approval is it applied. Environments can be set so that changes must go this way.

What the log can show

• That a request was created, and by whom.
• That it was approved, and by whom.
• That it was published, and at what time.
• The resulting change to the flag itself.

Two layers of story

The request holds the reason and the conversation. The audit log holds the facts and the timing. For a complete picture, read both. A strong team writes a clear title and description on every request, and then the audit log entry can be traced back to the request that explains it.

The actor of a published change

Be careful here. A change request may be written by one person, approved by another, and published by a third. The entry for the final flag change may show the person who published it, while the request shows the author and the approver. To know who truly authored the idea, open the request, not only the log.

A scheduled change creates a gap between the moment it was decided and the moment it took effect. The history must make both clear.

Two times, not one

If someone schedules a flag to turn on tomorrow at nine, there are two events: the moment of scheduling (today) and the moment of going live (tomorrow). A reader who only looks at the time of going live may wonder who did it, because nobody was at a keyboard at that moment.

How to read such entries

• Find the entry for the scheduling to see who decided.
• Find the entry for the live change to see when it took effect.
• Check whether the schedule was edited or cancelled in between.

Why this matters in incidents

Imagine a problem begins at nine in the morning, and the audit log shows a change at that exact moment. If you search for a person who was working at nine, you may waste time. Look for a schedule set earlier. A scheduled change is a time bomb with a note attached, and the note is in the earlier part of the log.

Flag settings are not only on and off. Targeting changes also alter who sees what, and they are recorded too.

Segment changes

A segment is shared by many features. If someone edits the rules of a segment, for example changing “plan equals premium” to “plan equals premium or standard”, every feature that uses that segment may behave differently for some users. The change is recorded against the segment, not against each feature.

This is a classic trap in investigations. You open a feature’s history and see nothing recent. The feature itself did not change. But the segment it relies on did. So always check the segment history as well.

Segment overrides

Adding, removing or reordering an override on a feature is a change to that feature in that environment, and is recorded as such. Reordering is especially important, because the order decides which override wins when a user belongs to more than one segment.

Identity overrides

A setting for one person is a very targeted change. It is easy to forget because it affects only one user. Over time, many such overrides may appear. The history is how you find out who added a special case for a user and when.

The audit log is most useful when its news reaches the places where people already look.

Webhooks

A webhook is a way for one program to knock on another program’s door when something happens. Flagsmith can be set up to send a small message to a web address of your choice whenever certain events occur, including audit-log type events in many versions. The receiving program can then do something useful with it.

Common destinations

• Chat tools. A short message in a team channel: “Production flag checkout_v2 was turned on by Asha”.
• Monitoring tools. An event marker on a graph, so you can see a flag change as a vertical line next to an error curve.
• Ticket systems. A note added to a ticket that mentions the flag.
• Security tools. A copy of events in a central store for long-term analysis.

Built-in integrations

Flagsmith offers integrations with several popular tools. The list changes over time, so look at the integrations section of your dashboard to see which are offered for your plan.

Why graph markers are powerful

When an engineer looks at a graph of errors and sees a sharp jump, the next question is “what happened then?”. If a flag change appears as a marker at exactly that moment, the answer is visible without opening any log. This often cuts the time to find a cause from half an hour to a minute.

flowchart LR
    CHANGE["Flag change saved"] --> LOG["Audit log entry written"]
    LOG --> HOOK["Webhook or integration fires"]
    HOOK --> CHAT["Team chat message"]
    HOOK --> MON["Marker on monitoring graph"]
    HOOK --> SEC["Security data store"]
    HOOK --> TICKET["Ticket note"]

The dashboard is good for people. Programs prefer the API.

Why use the API

Flagsmith has an administration API that lets programs read and manage data. In many versions, this includes the audit log. With it, you can fetch the latest entries on a schedule, copy them to your own storage and run your own reports.

Typical uses

• Daily export. A job copies the last day’s entries into your central log store.
• Compliance reports. A job prepares a monthly list of Production changes for auditors.
• Alerting. A job watches for unusual patterns, such as many deletions in a short time.

Keys and permissions

The administration API uses a different kind of key from the one used by apps to read flags. It is powerful and must be treated like a password. Give it only to the jobs that need it, store it in a secrets vault and rotate it.

Paging and limits

A big log cannot be returned in one piece. The API gives a page at a time, and the program asks for the next page until all are read. A well-written job remembers the latest entry it saw, so it only fetches new ones next time.

Time and ordering

Entries have timestamps, usually in UTC. When you copy them elsewhere, keep the original timestamp and add your own copy time as a separate field. Never replace one with the other, because later you will want to know both when the change happened and when you learned about it.

Let us look behind the screen. Understanding the parts helps you reason about speed, reliability and trust.

The big picture

flowchart TD
    UI["Dashboard"] --> API["Admin API"]
    CI["Pipelines and scripts"] --> API
    API --> AUTH["Authentication and permissions"]
    AUTH --> LOGIC["Business logic: features, segments, environments"]
    LOGIC --> DB[("Primary database")]
    LOGIC --> AUDIT["Audit recorder"]
    AUDIT --> DB
    AUDIT --> HOOKS["Webhooks and integrations"]
    LOGIC --> CACHE["Flag serving caches"]
    CACHE --> SDKS["Apps reading flags"]

The components in plain words

The separation of reading and writing

The path that serves flags to apps is separate from the path that records changes. Apps read from a fast serving layer. Changes go through the admin path, are stored, recorded and then pushed into the serving layer. This design keeps flag reading very quick and keeps the audit log out of the way of customers.

A caution about self-hosted installs

If you run Flagsmith yourself, the audit log lives in your database. Its safety depends on your backup, access control and retention choices. The hosted service handles this for you, within the terms of your plan.

When you press Save, a small chain of events runs in the background. Knowing the chain explains why audit entries are trustworthy and why they sometimes look the way they do.

The chain, step by step

sequenceDiagram
    participant P as Person or script
    participant A as Admin API
    participant G as Permission check
    participant D as Database
    participant R as Audit recorder
    participant H as Webhooks
    P->>A: Save change
    A->>G: Who is this and may they do it
    G-->>A: Allowed
    A->>D: Write new feature state
    A->>R: Create audit entry
    R->>D: Store entry with server time
    R->>H: Trigger notifications
    A-->>P: Success

Why the server’s clock matters

If the time came from the person’s computer, anyone could write any time they like. Because the server writes the time, entries are consistent and hard to fake. This is why audit logs from a proper system carry more weight than screenshots or hand-written notes.

What happens when something fails

If the save fails, there should be no audit entry for a change that did not happen. If the save works but the notification to a chat tool fails, the audit entry still exists. This is a vital difference: the record is the truth, and notifications are only convenient messengers. If your chat channel misses a message, the log is still right.

An audit record is born, lives a quiet life and eventually leaves. Following that life helps you plan what to keep.

Birth

The record is created at the moment of the change, with the actor, the time and the description. From this moment, it should never be edited. A good audit system is append-only: new lines are added, and old lines are left alone.

Young life: active reading

In the first days and weeks, the record is read often. People look at it in incidents, in reviews and in standups. It is stored in the main database, so it is quick to search.

Middle life: occasional reading

After a few months, reading becomes rare, mostly for investigations and audits. Some teams move older records into cheaper storage, through exports.

Old age: retention limits

No system keeps everything forever without cost. The hosted Flagsmith service may keep audit data for a limited period, which can depend on the plan, and self-hosted installs depend on your own settings. Check the retention period that applies to you, and compare it with what your auditors expect. If the system keeps ninety days and your auditors ask for a year, you need your own exports.

Death: deletion

At the end of the retention period, the record is removed. Some rules, such as privacy laws, may even require removal of personal details after some time. Others, such as financial rules, may require long keeping. Your policy must balance these.

flowchart LR
    B["Created at change time"] --> Y["Active period: quick to search"]
    Y --> M["Older period: occasional reading"]
    M --> E{"Exported to long-term storage?"}
    E -- "Yes" --> L["Kept in your archive"]
    E -- "No" --> R["Removed at end of retention"]
    L --> X["Removed per your own policy"]

A simple retention plan

An audit log grows forever, unless it is trimmed. A log that grows without care can become slow. Let us see how to keep it healthy.

How fast does it grow

Growth depends on how often people and programs change flags. A small team might create a few dozen entries per day. A big organisation with automated pipelines may create thousands. Programs are the real danger: a script that rewrites flags every minute, even when nothing changes, can fill the log with useless entries.

Writes are cheap, reads can be heavy

Adding a line is quick. Searching through millions of lines with loose filters can be slow. This is why time filters matter. Asking for “the last hour” is cheap. Asking for “everything containing the word checkout” over three years is expensive.

Habits that keep it fast

• Always filter by a time window first.
• Do not poll the API every second. Every minute or every five minutes is plenty for most needs.
• Make automation idempotent: only write a change if the value is different from what is already there.
• Export old data and keep the live system lean.

Self-hosted considerations

If you host Flagsmith, the audit table is in your database. Watch its size, index it properly according to the documentation, and plan clean-up jobs that follow your retention policy. A very large table can slow down not only the audit page but other parts of the system that share the database.

The serving path is protected

Customers reading flags do not touch the audit table. Even if the log is large, flag serving stays quick. That separation is a deliberate and wise design.

The log is a mirror of your control system. Who may read it, and who may change it, deserves careful thought.

Reading is also sensitive

An audit log can reveal flag names, project structure, who works on what and when. Names like “payment_fraud_check_off” tell outsiders a lot. Limit read access to people who need it: engineers, security and auditors.

Writing must be impossible

Nobody, not even an administrator, should be able to edit or delete an audit line through the dashboard. A log that an administrator can edit is a log that a bad administrator can tidy up. Make sure that no feature, role or script lets people rewrite history.

Role-based access

Flagsmith supports roles and permissions at organisation, project and environment levels in many plans. Use them like this:

• Developers can change Development and Staging.
• Only a small, named group can change Production.
• Only a very small group can manage users, keys and permissions.
• Auditors get read-only access.

Protect the keys

Admin API keys can change flags and read the log. A leaked key is like a stolen master key, and the log will show actions as if done by a legitimate service. Rotate keys, keep them in a vault, never place them in source code, and give each tool its own key so that you can revoke one without stopping the others.

Protect the exports

Copies of the log in other systems are just as sensitive as the original. Give them the same access controls and encryption.

Personal data

The log holds names or emails of your team members. This is personal data in many laws. Share it only for legitimate purposes, and keep it as long as needed, no more.

An audit log is only as good as your belief that it is true. Let us see what makes it trustworthy, and what its limits are.

Properties of a trustworthy log

• Automatic. Written by the system, not by people.
• Complete. Covers every important change, with no way to skip it.
• Accurate in time. Time from the server, not from the user.
• Attributable. Every entry tied to an actor.
• Append-only. Not editable through normal use.

Where trust can break

Even a good log has weak points. Anyone with direct access to the database, such as an administrator of a self-hosted install, could in theory change rows. A hosted service reduces that risk, since only the provider’s own staff can access storage, under strict rules. For self-hosting, you should limit database access, log database administrators’ actions and make regular copies.

Making a second copy

The best protection is an independent copy. If you export entries every few minutes to a separate system that the Flagsmith administrators cannot edit, then any later tampering would show up as a difference between the two copies. Think of it as two witnesses who were not in the same room.

Tamper evidence

Some teams add a fingerprint to exported batches, for example a checksum, stored elsewhere. If the batch changes later, the fingerprint no longer matches. This is a simple and strong way to prove that old records are untouched.

What the log cannot prove

• That the person typing was really the account owner. A stolen password can look like the owner.
• That a change was wise. It only says it happened.
• That nothing happened outside Flagsmith, for example a direct database edit on a self-hosted system.

Many rules and standards ask companies to prove that changes to production systems are controlled. The audit log is one piece of that proof. This chapter explains the common ideas in general terms. It is not legal advice, and your own advisers should confirm what applies to you.

The common requirement

Most standards ask three simple things: that changes are authorised, that they are traceable and that records are protected. Flags are production changes, so they fall under these questions.

How the audit log helps

Examples of frameworks where this matters

Security and service standards such as SOC 2 and ISO 27001 ask for controlled change management and logging. Financial reporting rules, for companies that fall under them, ask for control over systems that affect reported numbers, and a flag that changes pricing or a payment path can fall in that area. Privacy laws such as GDPR ask that personal data in logs is handled properly, with a clear purpose and limited keeping time. Industries such as healthcare and banking have their own rules about tracing who changed what.

What auditors usually do

An auditor picks a sample of changes, for example ten Production flag changes from the last quarter. For each one, they ask you to show the audit entry, the approval, and the reason. If you can open the entry, show the linked request and explain the reason within a few minutes, you pass easily. If the trail leads to “I do not remember”, you will have a harder day.

Preparing for an audit

• Keep a short document that describes how flags are controlled.
• Keep exports for the whole period the auditor asks about.
• Run a practice sample yourself every quarter.
• Remove accounts of people who have left.

A log that nobody reads is a locked drawer. Turning the log into signals makes it a living safety net.

What is worth watching

• Production changes outside working hours. Sometimes legitimate, but worth a glance.
• Deletions. Deleting a flag, segment or environment is rare and dangerous.
• Permission changes. New administrators, new keys, changed roles.
• Bursts. Many changes in a few minutes, which may signal a runaway script or an attack.
• Changes by unusual actors. A key that has been quiet for months suddenly acting.
• Disabled safeguards. Turning off the approval requirement on Production.

Useful metrics

Alert design

Alerts should be few and meaningful. If you alert on every change, people mute the channel. Start with three: any deletion in Production, any permission change, and any Production change made without a change request while that rule exists.

Weekly review

Once a week, a person spends ten minutes reading the Production entries of the past seven days. It sounds old-fashioned, yet it is surprisingly good at spotting small strange things that no alert thought of.

flowchart TD
    LOG["Audit log"] --> EXP["Regular export"]
    EXP --> STORE["Central log store"]
    STORE --> RULES["Alert rules"]
    STORE --> DASH["Dashboards and metrics"]
    STORE --> ARCH["Long-term archive"]
    RULES --> PAGE["Alert to on-call or security"]
    DASH --> REV["Weekly human review"]

Even a well-designed history can have trouble. Knowing the common failures in advance means you will not panic when one appears.

Scenario 1: The log shows nothing, but behaviour changed

This is the most confusing case. Possible explanations are many, and the audit log is only one witness among several.

• A trait changed in your own system, so users moved into or out of a segment.
• A percentage rollout uses a hash of the user identifier, and a new set of users joined the product.
• An app release changed how flags are used, with no flag change at all.
• A cache in an app delayed an old change, which finally took effect.
• You are reading the wrong environment or project.

Work through this list calmly before you suspect that the log is missing entries.

Scenario 2: The actor is a mystery

The entry names a key with a vague name, or a user who left the company. Ask the platform team which pipeline uses that key. Check the key’s creation entry in the log, which names who made it. If nobody owns it, revoke it in a quiet moment, watch for broken tools, and replace it with named keys.

Scenario 3: The webhook did not arrive

A change was made, but the chat channel stayed silent. Remember that the log is the truth, and the webhook is the messenger. Look at the log first. Then check that the webhook address is correct, that the receiver was up and that retries are working.

Scenario 4: The log is too old

You need the history of a change from two years ago, but the dashboard only keeps a shorter period. If you exported it, you can answer. If not, the best you can do is gather indirect evidence: release notes, tickets, chat history. This is the strongest reason to start exports on day one.

Scenario 5: A flood of entries

A broken script writes the same flag every second. The log fills up, and real entries are buried. Stop the script, remove its key permissions if needed, and add a check that avoids writing identical values.

Scenario 6: Time confusion

Two engineers disagree about the order of events because one reads local time and the other reads UTC. Agree on UTC for incident notes, and display the offset on every timestamp.

Scenario 7: The self-hosted database is lost

If you run Flagsmith yourself, a database failure takes the log with it, unless you have backups and an exported copy. Test restoring a backup at least once a year.

Every tool has strengths and limits. An honest look at both helps you decide what to add around it.

Trade-offs worth thinking about

Detail versus noise

A very detailed log answers more questions, but is harder to read and larger. A short log is easy to read, but sometimes leaves questions unanswered. Flagsmith chooses a balanced middle, and you can add your own detail through descriptions and linked requests.

Long retention versus privacy

Keeping records for years helps investigations and audits. It also keeps personal data of staff for a long time. Decide how long is really needed and write it down.

Open access versus safety

Letting everyone read the log builds trust and speeds learning. Letting only a few read it reduces the exposure of sensitive names. A common compromise is to let all engineers read Development and Staging entries, and restrict Production and permission entries to a smaller group.

Speed versus review

Requiring approvals adds a step, but adds traceability and a second pair of eyes. Skipping approvals is fast but leaves the log as the only protection, and a log can only tell you about a problem afterwards.

Teams that use audit logs well tend to follow the same few patterns. Teams that struggle tend to repeat the same few mistakes.

Good patterns

Anti-patterns

Here is a practical list of habits to adopt and traps to avoid.

Best practices

1. Give every person their own account. Use single sign-on if possible.
2. Name every key. Use the program and the purpose, such as “release-pipeline-prod”.
3. Use change requests for Production. Write a clear title and reason.
4. Link tickets. Put the ticket number in the description of changes and requests.
5. Export regularly. Keep an independent copy that matches your retention policy.
6. Send Production events to the right place. Chat, monitoring and security stores.
7. Review weekly. Ten minutes with the Production entries.
8. Practise investigations. Pick a past incident and see whether the log answers the five questions.
9. Remove old accounts and keys. Every quarter.
10. Write a one-page runbook. Where the log is, how to read it, who to call.

Common mistakes

Troubleshooting quick guide

• Cannot see the log. Your role may not include read access. Ask an administrator.
• Entry looks short. Open the detail view or the flag version for more.
• Cannot find a known change. Widen the time range, change the environment, and remove text filters.
• Export job misses entries. Check paging, and overlap your time windows slightly, removing duplicates afterwards.
• Webhook silent. Check the address, the receiver, secrets and retries.

Let us follow an imaginary company, “Acme Cart”, through a real-feeling incident, to see all the ideas working together.

The alert

At 00:12 UTC, an alert says that the share of successful payments has dropped from 98 percent to 71 percent. The on-call engineer, Meera, writes down the start time: about 00:05 UTC, when the graph bent.

Opening the log

Meera opens the audit log for the Production environment and filters from 23:30 to 00:15 UTC. She finds three entries.

Reading the clues

The entry at 00:04 matches the start of the problem very closely. It was a scheduled change, so nobody was at a keyboard. Meera looks for the entry that set the schedule, and finds it in the log from the previous afternoon: Asha Rao scheduled it, with a change request linked to a ticket. The request had two approvals.

The 00:09 entry is unrelated: only a description was changed.

Deciding

The new payment provider works for the Beta Users, but fails at scale for some card types. Meera decides to revert. She switches “payment_provider_v2” off in Production, using the emergency path, which still creates an audit entry. She posts the finding in the incident channel.

Confirming

Within a few minutes, the graph climbs back to 97 percent. The audit log now shows Meera’s revert at 00:19. Together, the entries give a precise story:

sequenceDiagram
    participant A as Asha
    participant S as Schedule
    participant F as Flag in Production
    participant M as Meera
    A->>S: Schedule enable for everyone at 00:04
    S->>F: 00:04 enable for everyone
    F-->>M: 00:12 payment success alert
    M->>F: 00:19 switch off
    F-->>M: Success rate recovers

What the team learned

• The scheduled change had no staged rollout. Next time, release to ten percent first.
• The graph had no flag markers. They added them, so the cause would have been visible in seconds.
• The change request lacked a test plan. They added a “how to check” section to the request template.
• Nobody was blamed. Asha helped write the new template.

Tools record facts. People decide what to do with them. A small amount of written governance turns an audit log from a passive record into an active safety system.

A one-page flag change policy

The policy does not need to be long. It should answer a few plain questions, and everyone should be able to find it in under a minute.

• Who may change flags in each environment?
• Which changes need a change request and how many approvals?
• What counts as an emergency, and what is the emergency path?
• Where is the audit log, who reviews it and how often?
• How long is history kept, and where are the exports?
• Who owns keys and integrations?

Owners for each piece

Naming conventions help the log

The log repeats names of flags, segments and keys. Clear names make every line easier to read. A flag called “checkout_v2_payment_provider” tells a reader what is happening. A flag called “test2” does not. Agree on a pattern: area, feature, purpose. Keep the same style in all projects.

Lifecycle of a flag, written in the log

A healthy flag has a visible life: created, tested in Development, tested in Staging, enabled in Production gradually, fully released, then removed once it is no longer needed. The log should show each of these steps. If it shows a flag created three years ago and never touched, ask whether it is a forgotten switch.

Regular clean-up with a record

When you remove old flags, do it deliberately: list candidates, ask owners, remove in a batch, and write a short note saying what was removed and why. The audit log keeps the lines for the deletions, and your note keeps the reason.

When a company grows, one small log becomes many logs. New questions appear about how to see the whole picture.

Many projects

Large companies often have one project per product. Each project has its own audit view. For a security team that cares about all of them, opening a dozen dashboards is tiring. The answer is central collection: export all entries into one store and add a field that names the project. Then one search covers everything.

Many environments with the same name

Many projects have an environment called “Production”. When logs are merged, the environment name alone is not enough. Always store the project name or identifier together with the environment.

Cross-checking with other change records

Flags are only one kind of change. Releases, database changes, infrastructure changes and feature settings in other tools also affect users. The most valuable view is a single timeline that combines them all. When Flagsmith entries sit in the same timeline as deployments and configuration changes, correlations become visible at once.

flowchart LR
    F["Flagsmith audit log"] --> C["Central change timeline"]
    D["Deployment records"] --> C
    I["Infrastructure changes"] --> C
    DB["Database migrations"] --> C
    C --> V["Single view for incidents and audits"]

Analytics on change behaviour

Once the entries are in a data store, you can ask interesting questions. Which flags change most often? Which teams change Production at night? How long do flags live? How many flags were never removed? These questions guide clean-up and training.

Linking flag changes to experiments

If your team runs experiments, the audit log gives exact start and end times for each variant change. Analysts can use these times to cut data windows correctly, instead of guessing from meeting notes.

Automation that respects the log

Pipelines that manage flags as configuration must write meaningful changes only. If a pipeline compares the desired state with the current one, and only changes the differences, the log contains only real changes. If it overwrites everything on every run, the log fills up with noise, and the signal is lost.

Multiple Flagsmith installs

Some companies run separate installs, for example one per region or one for a regulated business unit. The same advice applies: collect all logs centrally, tag each entry with its install, and keep time in UTC.

A smoke alarm is only useful if it rings. Test your audit trail before you need it.

The five-minute test

1. In a Development environment, change a flag in a small way.
2. Open the audit log. Can you find your change within a minute?
3. Check the actor, time, flag, environment and before and after values.
4. Check that your chat message or graph marker appeared, if set up.
5. Check that your export job picked it up at the next run.

The drill

Once a quarter, pick a past Production change at random, without telling the team. Ask a colleague to explain it using only the log and linked requests. Time how long it takes. Aim for under five minutes. If it takes longer, find what slowed them: missing reason, vague key name, absent ticket link.

The permission test

Create a test account with the lowest developer role. Try to change Production. It should be refused. Try to read the audit log. Check that it behaves as designed. Test an auditor account too, which should read but not change.

The tamper test for exports

Take a batch of exported entries, change one character in a copy and run your integrity check. It must report a difference. If it does not, the check is not protecting you.

The restore test

For self-hosted installs, restore a backup into a spare environment and confirm that the audit log is present. For hosted use, confirm that you can rebuild history from your exports.

Nobody builds a perfect audit practice in a day. Here is a path with four levels, so you can see where you are and what comes next.

How to move up

After you have read many entries, shapes start to appear. Learning to recognise these shapes lets you spot trouble and good health at a glance.

Pattern 1: The staircase

A healthy release looks like a staircase. A flag is switched on for a small group, then a larger group, then everyone, with gaps of minutes or hours between steps. Each step is a separate entry. If you see a staircase, the team is releasing carefully, and each step gave them a chance to look at graphs before taking the next.

Pattern 2: The cliff

A cliff is a single entry that takes a flag from nothing to everyone at once. Cliffs are sometimes fine, for small and safe changes. For risky changes, a cliff is a warning sign, and it often appears at the start of an incident story.

Pattern 3: The seesaw

A flag that goes on, off, on, off within a short time is a seesaw. It usually means that someone is trying to find a cause by trial and error, or that two people are fighting over the same switch. Ask what is happening. A seesaw in Production is a sign that the team needs a calmer process.

Pattern 4: The midnight visitor

A Production change made at an odd hour by a person who normally works elsewhere deserves a quick check. It may be perfectly innocent, such as an engineer in a different time zone. It may also be an account that someone else is using. Asking costs one message.

Pattern 5: The burst

Many entries in a few seconds, all by one actor, usually point to a script. Check that it is the script you expect, and that it is not writing the same value again and again.

Pattern 6: The long silence

A flag with no changes for a year may be stable and healthy, or forgotten. If the feature is fully released, it is a candidate for removal. If the flag controls something that should be reviewed, such as a limit or a price, a long silence may mean that nobody has looked at it for too long.

Pattern 7: The orphan override

An identity override added a long time ago for one user, never removed, is an orphan. These special cases pile up and make behaviour hard to predict. The history shows who created them and when, which helps decide whether to remove them.

Support teams meet the effects of flag changes first, often without knowing a flag exists. A little shared knowledge turns confusing tickets into quick answers.

The typical customer message

A customer writes: “Yesterday I could see the new reports page, and today it is gone.” The support agent cannot tell whether this is a bug, a planned change or something about the customer’s own account. The audit log helps answer the first two questions in minutes.

A simple routine for support

What support should not do

• Do not change Production flags to fix a single ticket, unless that is your approved process.
• Do not share internal flag names or the names of colleagues with customers.
• Do not promise that a feature will return before the owner confirms it.

Read-only access is enough

Support staff rarely need to change anything. A read-only role for Production and the ability to read the audit log is usually enough. This keeps the risk low while keeping the answers fast.

Audit trails are an old idea. Almost every serious industry keeps one. The descriptions below are general patterns that are widely discussed, not details of any private system.

Cloud platforms

Major cloud providers such as Amazon Web Services, Google Cloud and Microsoft Azure offer activity logs that record who called which management operation and when. Security teams rely on them for investigations and compliance. The lesson for flags is the same: every administrative action should be recorded with an actor and a time, and teams should export these records somewhere safe.

Source control

Systems such as Git keep a history of every change to code, with an author, a time and a message. Developers rely on that history daily, to find which change introduced a bug. A flag audit log plays the same role for behaviour changes that happen outside the code.

Banking and payments

Banks keep strict records of every transaction and every administrative change to account settings. Regulators expect these records to be complete, protected from edits and kept for set periods. Payment flags are close to this world, so teams working in payments usually follow similar discipline.

Healthcare

Healthcare systems record who looked at or changed a patient record, and when. The principle of attributable, time-stamped, append-only history is the same, even if the stakes are different.

Aviation

Aeroplanes carry flight recorders, and airlines keep maintenance logs that record every repair and inspection. After an accident, investigators rebuild events from these records. The culture of learning without blaming, often highlighted in aviation safety, is exactly the culture that makes audit logs useful in software.

Large technology companies

Companies that run products at huge scale, such as large social networks, video services and search engines, have written publicly about internal tools for feature gating and configuration changes. Common themes include change review, staged exposure, and fast correlation between a configuration change and a spike in errors. These themes match the practices in this guide.

Copy these into your team wiki. Short lists, used often, beat long manuals read once.

Setting up a healthy audit practice

• Personal accounts for all people, with single sign-on if possible.
• Named keys for every program, with an owner list.
• Change requests required on Production.
• Production events sent to a team channel.
• Flag markers on important graphs.
• Exports scheduled, with a stored copy outside Flagsmith.
• Retention written down and compared with audit needs.
• Three alerts: deletions, permission changes, bypassed review.

When investigating an incident

• Write the start time and time zone.
• Pick the right project and environment.
• Filter to a window around the start.
• Check feature, segment and override entries.
• Look for scheduled changes set earlier.
• Check traits, rollouts and app releases if the log is quiet.
• Ask the actor kindly for their reason.
• Record the finding and the action.

Before a big launch

• List scheduled changes for the coming week.
• Confirm the right people hold Production access.
• Confirm that alerts and markers are working.
• Make sure the change request lists a checking plan.
• Choose a staged rollout rather than a sudden switch.

Every quarter

• Run a drill on a past change.
• Review accounts, roles and keys.
• Check that exports are complete and protected.
• Run a sample for the auditors as practice.
• Remove old flags with a recorded note.

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.