featuregate

README

Collector Feature Gates

This package provides a mechanism that allows operators to enable and disable experimental or transitional features at deployment time. These flags should be able to govern the behavior of the application starting as early as possible and should be available to every component such that decisions may be made based on flags at the component level.

Usage

Feature gates must be defined and registered with the global registry in an init() function. This makes the Gate available to be configured and queried with the defined Stage default value. A Gate can have a list of associated issues that allow users to refer to the issue and report any additional problems or understand the context of the Gate. Once a Gate has been marked as Stable, it must have a RemovalVersion set.

var myFeatureGate = featuregate.GlobalRegistry().MustRegister(
	"namespaced.uniqueIdentifier",
	featuregate.Stable,
    featuregate.WithRegisterFromVersion("v0.65.0")
	featuregate.WithRegisterDescription("A brief description of what the gate controls"),
	featuregate.WithRegisterReferenceURL("https://github.com/open-telemetry/opentelemetry-collector/issues/6167"),
	featuregate.WithRegisterToVersion("v0.70.0"))

The status of the gate may later be checked by interrogating the global feature gate registry:

if myFeatureGate.IsEnabled() {
	setupNewFeature()
}

Note that querying the registry takes a read lock and accesses a map, so it should be done once and the result cached for local use if repeated checks are required. Avoid querying the registry in a loop.

Controlling Gates

Feature gates can be enabled or disabled via the CLI, with the --feature-gates flag. When using the CLI flag, gate identifiers must be presented as a comma-delimited list. Gate identifiers prefixed with - will disable the gate and prefixing with + or with no prefix will enable the gate.

otelcol --config=config.yaml --feature-gates=gate1,-gate2,+gate3

This will enable gate1 and gate3 and disable gate2.

Feature Lifecycle

Features controlled by a Gate should follow a three-stage lifecycle, modeled after the system used by Kubernetes:

1. An alpha stage where the feature is disabled by default and must be enabled through a Gate.
2. A beta stage where the feature has been well tested and is enabled by default but can be disabled through a Gate.
3. A generally available or stable stage where the feature is permanently enabled. At this stage the gate should no longer be explicitly used. Disabling the gate will produce an error and explicitly enabling will produce a warning log.
4. A stable feature gate will be removed in the version specified by its ToVersion value.

Features that prove unworkable in the alpha stage may be discontinued without proceeding to the beta stage. Instead, they will proceed to the deprecated stage, which will feature is permanently disabled. A feature gate will be removed once it has been deprecated for at least 2 releases of the collector.

Features that make it to the beta stage are intended to reach general availability but may still be discontinued. If, after wider use, it is determined that the gate should be discontinued it will be reverted to the alpha stage for 2 releases and then proceed to the deprecated stage. If instead it is ready for general availability it will proceed to the stable stage.

Documentation

Index

• Variables
• type Gate
  • func (g *Gate) Description() string
  • func (g *Gate) FromVersion() string
  • func (g *Gate) ID() string
  • func (g *Gate) IsEnabled() bool
  • func (g *Gate) ReferenceURL() string
  • func (g *Gate) Stage() Stage
  • func (g *Gate) ToVersion() string
• type RegisterFlagsOption
• type RegisterOption
  • func WithRegisterDescription(description string) RegisterOption
  • func WithRegisterFromVersion(fromVersion string) RegisterOption
  • func WithRegisterReferenceURL(referenceURL string) RegisterOption
  • func WithRegisterToVersion(toVersion string) RegisterOption
• type Registry
  • func GlobalRegistry() *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) MustRegister(id string, stage Stage, opts ...RegisterOption) *Gate
  • func (r *Registry) Register(id string, stage Stage, opts ...RegisterOption) (*Gate, error)
  • func (r *Registry) RegisterFlags(flagSet *flag.FlagSet, _ ...RegisterFlagsOption)
  • func (r *Registry) Set(id string, enabled bool) error
  • func (r *Registry) VisitAll(fn func(*Gate))
• type Stage
  • func (s Stage) String() string

Variables

var ErrAlreadyRegistered = errors.New("gate is already registered")

ErrAlreadyRegistered is returned when adding a Gate that is already registered.

Types

type Gate

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

Gate is an immutable object that is owned by the Registry and represents an individual feature that may be enabled or disabled based on the lifecycle state of the feature and CLI flags specified by the user.

func (*Gate) Description

func (g *Gate) Description() string

Description returns the description for the Gate.

func (*Gate) FromVersion

func (g *Gate) FromVersion() string

FromVersion returns the version information when the Gate's was added.

func (*Gate) ID

func (g *Gate) ID() string

ID returns the id of the Gate.

func (*Gate) IsEnabled

func (g *Gate) IsEnabled() bool

IsEnabled returns true if the feature described by the Gate is enabled.

func (*Gate) ReferenceURL

func (g *Gate) ReferenceURL() string

ReferenceURL returns the URL to the contextual information about the Gate.

func (*Gate) Stage

func (g *Gate) Stage() Stage

Stage returns the Gate's lifecycle stage.

func (*Gate) ToVersion

func (g *Gate) ToVersion() string

ToVersion returns the version information when Gate's in StageStable.

type RegisterFlagsOption

type RegisterFlagsOption interface {
	// contains filtered or unexported methods
}

RegisterFlagsOption is an option for RegisterFlags.

type RegisterOption

type RegisterOption interface {
	// contains filtered or unexported methods
}

RegisterOption allows to configure additional information about a Gate during registration.

func WithRegisterDescription

func WithRegisterDescription(description string) RegisterOption

WithRegisterDescription adds description for the Gate.

func WithRegisterFromVersion

func WithRegisterFromVersion(fromVersion string) RegisterOption

WithRegisterFromVersion is used to set the Gate "FromVersion". The "FromVersion" contains the Collector release when a feature is introduced. fromVersion must be a valid version string: it may start with 'v' and must be in the format Major.Minor.Patch[-PreRelease]. PreRelease is optional and may have dashes, tildes and ASCII alphanumeric characters.

func WithRegisterReferenceURL

func WithRegisterReferenceURL(referenceURL string) RegisterOption

WithRegisterReferenceURL adds a URL that has all the contextual information about the Gate. referenceURL must be a valid URL as defined by `net/url.Parse`.

func WithRegisterToVersion

func WithRegisterToVersion(toVersion string) RegisterOption

WithRegisterToVersion is used to set the Gate "ToVersion". The "ToVersion", if not empty, contains the last Collector release in which you can still use a feature gate. If the feature stage is either "Deprecated" or "Stable", the "ToVersion" is the Collector release when the feature is removed. toVersion must be a valid version string: it may start with 'v' and must be in the format Major.Minor.Patch[-PreRelease]. PreRelease is optional and may have dashes, tildes and ASCII alphanumeric characters.

type Registry

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

func GlobalRegistry

func GlobalRegistry() *Registry

GlobalRegistry returns the global Registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns a new empty Registry.

func (*Registry) MustRegister

func (r *Registry) MustRegister(id string, stage Stage, opts ...RegisterOption) *Gate

MustRegister like Register but panics if an invalid ID or gate options are provided.

func (*Registry) Register

func (r *Registry) Register(id string, stage Stage, opts ...RegisterOption) (*Gate, error)

Register a Gate and return it. The returned Gate can be used to check if is enabled or not. id must be an ASCII alphanumeric nonempty string. Dots are allowed for namespacing.

func (*Registry) RegisterFlags

func (r *Registry) RegisterFlags(flagSet *flag.FlagSet, _ ...RegisterFlagsOption)

RegisterFlags that directly applies feature gate statuses to a Registry.

func (*Registry) Set

func (r *Registry) Set(id string, enabled bool) error

Set the enabled valued for a Gate identified by the given id.

func (*Registry) VisitAll

func (r *Registry) VisitAll(fn func(*Gate))

VisitAll visits all the gates in lexicographical order, calling fn for each.

type Stage

type Stage int8

Stage represents the Gate's lifecycle and what is the expected state of it.

const (
	// StageAlpha is used when creating a new feature and the Gate must be explicitly enabled
	// by the operator.
	//
	// The Gate will be disabled by default.
	StageAlpha Stage = iota
	// StageBeta is used when the feature gate is well tested and is enabled by default,
	// but can be disabled by a Gate.
	//
	// The Gate will be enabled by default.
	StageBeta
	// StageStable is used when feature is permanently enabled and can not be disabled by a Gate.
	// This value is used to provide feedback to the user that the gate will be removed in the next versions.
	//
	// The Gate will be enabled by default and will return an error if disabled.
	StageStable
	// StageDeprecated is used when feature is permanently disabled and can not be enabled by a Gate.
	// This value is used to provide feedback to the user that the gate will be removed in the next versions.
	//
	// The Gate will be disabled by default and will return an error if modified.
	StageDeprecated
)

func (Stage) String

func (s Stage) String() string