OpenTelemetry Collector feature gates carry a Stage field (alpha → beta → stable → deprecated → removed) that conventionally signals maturity progression toward default-on behavior. But some gates are designed as permanent switches, intentionally held at alpha forever, and reading a gate’s status as “not yet mature” is wrong for these cases. Gate status must be interpreted with intent, not just the stage label.
The transitional stages describe a pre-GA readiness trajectory: a gate moves alpha → beta as the feature stabilizes, then to stable as it becomes the default. The permanent pattern is different: the gate exists as a perpetual opt-in control, typically for security or data-integrity reasons, and its alpha status reflects “you must explicitly consent to this behavior” rather than “this isn’t ready yet.” Conflating the two leads to wrong planning. You write comments like “remove this override once it graduates to stable” and discover years later that it’s not going anywhere, because contributors keep proposing promotion and maintainers keep declining: not “not yet” but “never, by design.”
The canonical example is filelog.allowFileDeletion, which guards the delete_after_read option in the filelog receiver. Introduced in v0.70.0 (Jan 2023), defined as stage: alpha in pkg/stanza/fileconsumer/metadata.yaml with no to_version. Maintainer @djaglowski on the original issue #16314:
The worst case scenario is that a malicious actor is able to delete important files… putting this functionality behind a permanent feature gate… a malicious actor who is only able to reconfigure the collector (but not in control of the startup command) is unable to delete files.
Three+ years later, still alpha, no graduation in progress. The alpha label is functioning as a security control that requires an explicit --feature-gates=filelog.allowFileDeletion flag at startup, inaccessible via config-file modification alone. Other candidates fall in the same category: any security-sensitive or policy-sensitive toggle where the gate is the UX, not the readiness indicator. Search any long-lived alpha gate’s original RFC for language like “permanent,” “security,” “opt-in,” or “defense-in-depth.”
Read the originating issue, not just the docs, when an alpha gate is load-bearing in your config. Document override intent with “this is permanent” rather than “until it graduates,” to prevent future drift in your own planning. Don’t time your infrastructure removal cycle to gate graduation for permanent gates; they don’t graduate, so your override is permanent too. See OTel Metric Temporality for an adjacent OTel-spec quirk that also rewards going to primary sources over docs.