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.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 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:
- An
alphastage where the feature is disabled by default and must be enabled through aGate. - A
betastage where the feature has been well tested and is enabled by default but can be disabled through aGate. - A generally available stage where the feature is permanently enabled and
the
Gateis 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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type FlagValue
deprecated
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 ¶
Description returns the description for the Gate.
func (*Gate) ReferenceURL ¶
ReferenceURL returns the URL to the contextual information about the Gate.
func (*Gate) RemovalVersion ¶
RemovalVersion returns the removal version information for Gate's in StageStable.
type RegisterOption ¶ added in v0.71.0
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 WithRegisterReferenceURL ¶
func WithRegisterReferenceURL(url string) RegisterOption
WithRegisterReferenceURL adds a URL that has all the contextual information about the Gate.
func WithRegisterRemovalVersion ¶
func WithRegisterRemovalVersion(version string) RegisterOption
WithRegisterRemovalVersion is used when the Gate is considered StageStable, to inform users that referencing the gate is no longer needed.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
func GlobalRegistry ¶ added in v0.70.0
func GlobalRegistry() *Registry
GlobalRegistry returns the global Registry.
func (*Registry) MustRegister ¶ added in v0.71.0
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 ¶ added in v0.71.0
Register a Gate and return it. The returned Gate can be used to check if is enabled or not.
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 )
Source Files