Feature flags

Prometheus uses --enable-feature=<name> to gate experimental, breaking, or risky behaviours. The full user-facing reference is docs/feature_flags.md. The internal registry is util/features/, which the API surfaces at /api/v1/features for the UI.

How a flag is registered

Each subsystem calls features.Set(category, name, enabled) during construction. Categories are the constants in util/features/features.go:

Category	Used by
api	web/api/v1/api.go
otlp_receiver	web/web.go
prometheus	cmd/prometheus/main.go
promql	promql/engine.go
promql_functions	promql/functions.go
promql_operators	promql/parser/
rules	rules/manager.go
scrape	scrape/manager.go
service_discovery_providers	discovery/manager.go
templating_functions	template/template.go
tsdb	tsdb/db.go, tsdb/agent/db.go
ui	web/ui/ui.go

/api/v1/features returns { category: { name: bool } } — the UI uses it to grey out experimental controls.

Runtime flags vs config-file features

Some legacy --enable-feature toggles have been promoted to first-class config-file fields. The flag stays accepted (with a deprecation log line) and util/features continues to surface the corresponding entry. Examples:

• extra-scrape-metrics — moved to global.extra_scrape_metrics and per-scrape_config.
• created-timestamp-zero-ingestion — accepted as a flag, but the canonical setting is scrape_config.track_timestamps_staleness plus --enable-feature=created-timestamp-zero-ingestion.

Notable currently-experimental features

A representative slice; consult docs/feature_flags.md for the canonical list.

Flag	Status (3.11)	Effect
exemplar-storage	Stable, opt-in	Enable in-memory exemplar buffer.
memory-snapshot-on-shutdown	Stable, opt-in	Faster startup by persisting head state on clean shutdown.
extra-scrape-metrics	Deprecated (use config field)	Adds scrape_timeout_seconds etc.
promql-per-step-stats	Stable	Returns per-step totalQueryableSamples.
promql-experimental-functions	Continually-evolving	Enables functions marked experimental in parser/functions.go.
created-timestamp-zero-ingestion	Stable, opt-in	Inject zero samples for start timestamps.
st-storage	New (3.11)	Persist start timestamps in TSDB and Agent WAL; expose via RW2.
xor2-encoding	New (3.11)	Use the new XOR2 chunk encoding.
fast-startup	New (3.11)	Write series_state.json to speed up active-series rehydration.
old-ui	Deprecation path	Switch back to the 2.x UI.
otlp-deltatocumulative	Experimental	Convert OTLP delta to cumulative inside the receiver.
otlp-native-delta-ingestion	Experimental	Preserve delta temporality.
out-of-order-attributes	Experimental	Allow out-of-order labels on samples.
metadata-wal-records	Stable	Write metadata records to the WAL (so remote write v2 can ship them).
agent	Stable	Provided here for completeness — actually the --agent CLI flag, not a feature flag.

Lifecycle of a feature flag

1. Introduced as a --enable-feature=<name> toggle, default off, documented in docs/feature_flags.md.
2. After at least one stable release, may be promoted to a config-file field with the same semantics.
3. Once GA, the flag is accepted but logs a deprecation warning when set.
4. Eventually the flag is removed; users on older configs are pointed at the new field.

The release coordinators decide promotion timing; the recipe is documented loosely in RELEASE.md.

Entry points for modification

• Add a flag: add to the kingpin parser in cmd/prometheus/main.go, propagate via the relevant manager's Options, and register with features.Set. Document in docs/feature_flags.md.
• Promote a flag: add the equivalent config field, log a deprecation when the flag is used alone, and document the migration in docs/migration.md.
• Remove a flag: remove from the parser, the manager option, and the util/features registration; bump the release notes with a [CHANGE] entry.