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

    Constants

    This section is empty.

    Variables

    This section is empty.

    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.

                  Source Files