experiments

Documentation

Overview

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

• func Enable(ctx context.Context, id ...ID) context.Context
• type ID
  • func GetByName(name string) (id ID, ok bool)
  • func Register(name string) ID
  • func (id ID) Enabled(ctx context.Context) bool
  • func (id ID) String() string
  • func (id ID) Valid() bool

Functions

func Enable

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.

Types

type ID

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

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

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

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

func (id ID) String() string

String return the experiment name.

func (ID) Valid

func (id ID) Valid() bool

Valid is false for zero ID{} value.