telemetry/featuregate/README.md

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.

Defining Feature Gates

Declaratively in metadata.yaml (Recommended)

The preferred way to define feature gates is declaratively in the component's metadata.yaml file. The mdatagen code generator will automatically register the gate and generate the necessary Go code.

feature_gates:
  - id: namespaced.uniqueIdentifier
    description: A brief description of what the gate controls
    stage: alpha
    from_version: 'v0.65.0'
    reference_url: 'https://github.com/open-telemetry/opentelemetry-collector/issues/6167'

The supported fields are:

Field	Required	Description
id	Yes	Unique identifier for the feature gate
description	Yes	Brief description of what the gate controls
stage	Yes	Lifecycle stage: alpha, beta, stable, or deprecated
from_version	Yes	Version when the feature gate was introduced
to_version	For stable/deprecated	Version when the gate reached its current stage
reference_url	Yes	URL with contextual information (issue or PR)

Running mdatagen will generate the gate registration in the internal/metadata submodule. The status of the gate can then be checked in code:

if metadata.NamespacedUniqueIdentifierFeatureGate.IsEnabled() {
  setupNewFeature()
}

See the mdatagen documentation for more details.

Programmatically in code

For packages that don't use mdatagen, feature gates can 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.