luci: go.chromium.org/luci/server/experiments Index | Files

package experiments

import "go.chromium.org/luci/server/experiments"

Package experiments allow servers to use experimental code paths.

An experiment is essentially like a boolean command line flag: it has a name and it is either set or not. If it is set, the server code may do something differently.

The server accepts a repeated CLI flag `-enable-experiment <name>` to enable named experiments. A typical lifecycle of an experiment is tied to the deployment cycle:

1. Implement the code path guarded by an experiment. It is disabled by
   default. So if someone deploys this code to production, nothing bad will
   happen.
2. Enable the experiment on staging by passing `-enable-experiment <name>`
   flag. Verify it works.
3. When promoting the staging to canary, enable the experiment on canary as
   well. Verify it works.
4. Finally, enable the experiment when promoting canary to stable. Verify
   it works.
5. At this point the experimental code path is running everywhere. Make it
   default in the code. It makes `-enable-experiment <name>` noop.
6. When deploying this version, remove `-enable-experiment <name>` from
   deployment configs.

The difference from command line flags:

* An experiment is usually short lived. If it needs to stay for long, it
  should be converted into a proper command line flag.
* The server ignores enabled experiments it doesn't know about. It
  simplifies adding and removing experiments.
* There's better testing support.

Index

Package Files

experiments.go

func Enable Uses

func Enable(ctx context.Context, id ...ID) context.Context

Enable enables zero or more experiments.

In other words Enable(ctx, exp) returns a context `ctx` such that exp.Enabled(ctx) returns true. All experiments must be registered already.

This is an additive operation.

type ID Uses

type ID struct {
    // contains filtered or unexported fields
}

ID identifies an experiment.

The only way to get an ID is to call Register or GetByName.

func GetByName Uses

func GetByName(name string) (id ID, ok bool)

GetByName returns a registered experiment given its name.

Returns ok == false if such experiment hasn't been registered.

func Register Uses

func Register(name string) ID

Register is usually called during init() to declare some experiment.

Panics if such experiment is already registered. The package that registered the experiment can then check if it is enabled in runtime via id.Enabled().

func (ID) Enabled Uses

func (id ID) Enabled(ctx context.Context) bool

Enabled returns true if this experiment is enabled.

In production servers an experiment is enabled by `-enable-experiment <name>` CLI flag.

In tests an experiment can be enabled via Enable(ctx, id).

func (ID) String Uses

func (id ID) String() string

String return the experiment name.

func (ID) Valid Uses

func (id ID) Valid() bool

Valid is false for zero ID{} value.

Package experiments imports 4 packages (graph) and is imported by 2 packages. Updated 2020-09-30. Refresh now. Tools for package owners.