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.

const (
	myFeatureGateID = "namespaced.uniqueIdentifier"
	myFeatureStage  = featuregate.Stable
)

func init() {
	featuregate.MustRegisterID(
		myFeatureGateID, 
		myFeatureStage, 
		featuregate.WithRegisterDescription("A brief description of what the gate controls"),
		featuregate.WithRegisterReferenceURL("https://github.com/open-telemetry/opentelemetry-collector/issues/6167"),
		featuregate.WithRegisterRemovalVersion("v0.70.0"),
	)
}

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

if featuregate.IsEnabled(myFeatureGateID) {
	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 stage where the feature is permanently enabled and the Gate is no longer operative.

Features that prove unworkable in the alpha stage may be discontinued without proceeding to the beta stage. Features that make it to the beta stage will not be dropped and will eventually reach general availability where the Gate that allowed them to be disabled during the beta stage will be removed.

Documentation

Index

• type FlagValue
  • func (f FlagValue) Set(s string) error
  • func (f FlagValue) String() string
• type Gate
  • func (g *Gate) GetDescription() string
  • func (g *Gate) GetID() string
  • func (g *Gate) IsEnabled() bool
  • func (g *Gate) ReferenceURL() string
  • func (g *Gate) RemovalVersion() string
  • func (g *Gate) Stage() Stage
• type Registry
  • func GetRegistry() *Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Apply(cfg map[string]bool) error
  • func (r *Registry) IsEnabled(id string) bool
  • func (r *Registry) List() []Gate
  • func (r *Registry) MustRegister(g Gate)
  • func (r *Registry) MustRegisterID(id string, stage Stage, opts ...RegistryOption)
  • func (r *Registry) Register(g Gate) error
  • func (r *Registry) RegisterID(id string, stage Stage, opts ...RegistryOption) error
• type RegistryOption
  • func WithRegisterDescription(description string) RegistryOption
  • func WithRegisterReferenceURL(url string) RegistryOption
  • func WithRegisterRemovalVersion(version string) RegistryOption
• type Stage
  • func (s Stage) String() string

Types

type FlagValue

type FlagValue map[string]bool

FlagValue implements the flag.Value interface and provides a mechanism for applying feature gate statuses to a Registry

func (FlagValue) Set

func (f FlagValue) Set(s string) error

Set applies the FlagValue encoded in the input string

func (FlagValue) String

func (f FlagValue) String() string

String returns a string representing the FlagValue

type Gate

type Gate struct {
	// Deprecated: [v0.64.0] Use GetID() instead to read,
	//				use `Registry.RegisterID` to set value.
	ID string
	// Deprecated: [v0.64.0] use GetDescription to read,
	// 				use `WithRegisterDescription` to set using `Registry.RegisterID`.
	Description string
	// Deprecated: [v0.64.0] use `IsEnabled(id)` to read,
	//              use `Registry.Apply` to set.
	Enabled bool
	// contains filtered or unexported fields
}

Gate is an immutable object that is owned by the `Registry` to 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) GetDescription

func (g *Gate) GetDescription() string

func (*Gate) GetID

func (g *Gate) GetID() string

func (*Gate) IsEnabled

func (g *Gate) IsEnabled() bool

func (*Gate) ReferenceURL

func (g *Gate) ReferenceURL() string

func (*Gate) RemovalVersion

func (g *Gate) RemovalVersion() string

func (*Gate) Stage

func (g *Gate) Stage() Stage

type Registry

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

func GetRegistry

func GetRegistry() *Registry

GetRegistry returns the global Registry.

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns a new empty Registry.

func (*Registry) Apply

func (r *Registry) Apply(cfg map[string]bool) error

Apply a configuration in the form of a map of Gate identifiers to boolean values. Sets only those values provided in the map, other gate values are not changed.

func (*Registry) IsEnabled

func (r *Registry) IsEnabled(id string) bool

IsEnabled returns true if a registered feature gate is enabled and false otherwise.

func (*Registry) List

func (r *Registry) List() []Gate

List returns a slice of copies of all registered Gates.

func (*Registry) MustRegister

func (r *Registry) MustRegister(g Gate)

MustRegister like Register but panics if a Gate with the same ID is already registered. Deprecated: [v0.64.0] Use MustRegisterID instead.

func (*Registry) MustRegisterID

func (r *Registry) MustRegisterID(id string, stage Stage, opts ...RegistryOption)

MustRegisterID like RegisterID but panics if an invalid ID or gate options are provided.

func (*Registry) Register

func (r *Registry) Register(g Gate) error

Register registers a Gate. May only be called in an init() function. Deprecated: [v0.64.0] Use RegisterID instead.

func (*Registry) RegisterID

func (r *Registry) RegisterID(id string, stage Stage, opts ...RegistryOption) error

type RegistryOption

type RegistryOption func(g *Gate)

RegistryOption allows for configuration additional information about a gate that can be exposed throughout the application

func WithRegisterDescription

func WithRegisterDescription(description string) RegistryOption

WithRegisterDescription adds the description to the provided `Gate“.

func WithRegisterReferenceURL

func WithRegisterReferenceURL(url string) RegistryOption

WithRegisterReferenceURL adds an URL that has all the contextual information about the `Gate`.

func WithRegisterRemovalVersion

func WithRegisterRemovalVersion(version string) RegistryOption

WithRegisterRemovalVersion is used when the `Gate` is considered `StageStable`, to inform users that referencing the gate is no longer needed.

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 flag 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 version.
	//
	// The Gate will be enabled by default and will return an error if modified.
	StageStable
)

func (Stage) String

func (s Stage) String() string