How flags work
The building blocks, and how Slydog decides what each user gets.
Organizations and roles
Everything lives in an organization, and organizations are fully separate from each other. Members have one of four roles:
- Viewer reads everything.
- Editor also changes flags and segments.
- Admin also manages apps, environments, SDK keys, API tokens and members.
- Owner can do everything, including transferring or deleting the organization.
Invite people from Members. An invite link works once, for 7 days, for whoever signs in with the invited email.
Apps and environments
An app holds flags, segments and environments. Use one app per product, or one per codebase.
An environment, such as local, development or production, has its own rules for every flag and its own SDK keys. The same flag can be on in development and off in production. You can copy a flag's rules from one environment to another.
A protected environment asks for confirmation before any change, and the
API answers 428 CONFIRMATION_REQUIRED until a request includes
"confirm": true. New apps protect production.
Environments can also expire on their own (Pro), which suits one environment per pull request: see API, CI and scripts.
Flags and variations
A flag has a key, such as new-checkout, a type (Boolean,
String, Number or JSON) and a list of
variations, the values it can serve. One variation is the
off variation: what everyone gets while the flag is off. Variations are
the same in every environment.
A new flag starts off everywhere. Only flags marked Available to clients can be read with a client key, from browsers and mobile apps; anyone with your app can read their values.
How a flag is evaluated
For one environment and one context, Slydog checks, in order:
- Off? Everyone gets the off variation.
- Targets: lists of specific keys that get a given variation.
- Rules, top to bottom. The first rule whose conditions all match decides.
- Default rule: what everyone else gets while the flag is on.
Targets, rules and the default rule each serve either one variation or a percentage rollout.
With the Node.js provider this happens inside your server, from rules it keeps in memory, so reading a flag doesn't wait on the network. With OFREP, Slydog evaluates and answers.
Contexts and context kinds
The evaluation context says who or what you're evaluating for. Its
targetingKey is the key that targets and rollouts use. Every other field is
an attribute that rules can match.
{ targetingKey: "user-123", plan: "pro", country: "US" }
Each app lists its context kinds, such as user,
home or device. A context with no kind is a
user. To evaluate for several at once, send a multi-kind context; each
target, rule and rollout says which kind it uses:
{
kind: "multi",
user: { targetingKey: "user-123", plan: "pro" },
home: { targetingKey: "home-42" },
}
Rules and conditions
A rule is a list of conditions, all of which must match. A condition takes a context kind, an attribute and an operator:
- Text: is one of, starts with, ends with, contains, matches pattern (an RE2 regular expression).
- Numbers: is less than, is at most, is more than, is at least. Dates are compared as milliseconds since 1970.
- Segments: is in segment.
Any condition can be negated ("is not one of"). The attribute key means the
context's key. If the context doesn't have that kind or attribute, the condition doesn't
match, negated or not. An attribute that's a list matches when any of its items does.
Segments
A segment is a reusable group, such as "beta testers" or "staff": keys to include, keys to exclude, and rules that match anyone else. Use it in any flag's rules with is in segment, and change who is in it in one place.
Percentage rollouts
A rollout splits a context kind between variations by percentage, say 10%
on and 90% off of users. It's sticky: the same key gets the same
variation every time, on every server, and changing the percentages moves the fewest
people possible. Contexts without a key of the rollout's kind get your code's default.
To raise a rollout on a timetable, such as 5%, 25%, 50% then 100% a day apart, start a ramp when you save the change. A ramp pauses rather than overwrite the rollout if someone changes it by hand.
Making changes
- Kill switch. Turning a flag off reaches every server within seconds. No deploy, no waiting for caches.
- Scheduled changes. Choose Apply at a set time when you save, and the change applies within a minute of that time. Until then you can pause or cancel it from Scheduled.
- Approvals. An owner can turn on Require approval for protected environments on the Approvals page. Changes to production then wait for someone else who could make them. Switching a flag off can skip approval, so an emergency is never held up.
- Audit log. Every change, with who made it, when, and what it was before and after.
- Retiring a flag. Archive it once your code no longer reads it. It leaves every environment, and anything still asking for it gets its code default. Slydog shows when each flag was last evaluated, so you can spot flags nothing uses.
Over a plan's limit
Flags never stop working because of a limit. A month counts as over only when it's more than 2% over the plan's monthly active users. After two months over in a row, the organization gets a grace period, and after that it becomes read-only until it upgrades or usage drops: flags keep evaluating, but nobody can change them. Owners and admins get an email when a grace period starts.