Migration context

In-flight migrations and how they shape day-to-day work.

AppenderV2 (Issue #17632)

Migrating every storage write path from V1 (Appender) to V2 (AppenderV2).

Why

• V1 separates samples, exemplars, metadata into different methods. V2 bundles them into a single AppendEntry per sample, which:
  • Reduces lock contention.
  • Allows per-sample exemplars.
  • Carries always-on metadata (type/unit/help) that drives consistent ingestion semantics.
  • Supports start timestamps inline.

Status

• Done: scrape (scrape/scrape_append_v2.go), TSDB (tsdb/head_append_v2.go), agent (tsdb/agent/db_append_v2.go), inbound RW2 (storage/remote/write_handler.go), OTLP (storage/remote/write_otlp_handler.go), teststorage.
• In progress: rule manager, federation handler, several internal helpers.
• Pending: removal of V1. Target ETA is Q2 2026 per the comment in storage/interface.go.

How to help

When touching code that calls storage.Appendable.Appender(ctx), check whether the same storage now exposes AppendableV2. If so, prefer V2.

Mantine UI (3.x)

Migrating from the legacy 2.x React UI to the new Mantine-based UI.

Status

• The Mantine UI is the default since v3.0.0 (Nov 2024).
• The legacy UI lives behind --enable-feature=old-ui.
• Both are bundled into the binary; users can flip between them at runtime.

What's left

• Removing the legacy UI in a future major release. Until then, every API change must keep both UIs working.
• Continual conversion of remaining custom CodeMirror plumbing into the shared web/ui/module/ packages so external consumers (Thanos UI, Grafana editor) can keep using them.

3.x evolution

In April 2026, the Mantine UI itself migrated from Mantine 8 to Mantine 9 (mantine-ui: migrate from Mantine 8 to 9, 2026-04-07). The migration was scoped to a single PR per the project conventions.

AWS SDK v1 -> v2

Migrating every AWS SD (EC2, ECS, Elasticache, Kafka, Lightsail, RDS, STS, etc.) from the legacy github.com/aws/aws-sdk-go to github.com/aws/aws-sdk-go-v2.

Status

• Done: EC2, ECS, Elasticache, Kafka, Lightsail, RDS, STS — all using the v2 SDK.
• Lessons learned: the migration introduced regressions: #18133 (EC2 SD ignoring endpoint), various minor differences in pagination semantics. Each SD's tests were beefed up after.
• The maintainers list in MAINTAINERS.md for discovery/aws/ is unchanged.

Lingering work

• Continued tuning of the per-SD configuration; some options have different names between SDK v1 and v2.
• Review whether more AWS roles (e.g. CloudWatch tagged resources) should be added.

Remote Write 2.0

Adding (and now maturing) the Remote Write 2.0 protocol.

Why

• Per-sample exemplars (RW1 carries them only via the metadata watcher).
• Native histograms (RW1 has them but with awkward serialisation).
• Type/unit metadata in band.
• Start timestamps in band.

Status

• Sender support: storage/remote/queue_manager.go handles RW2 with proto_message: io.prometheus.write.v2.Request.
• Receiver support: web/api/v1/api.go accepts both message types via acceptRemoteWriteProtoMsgs.
• Compliance suite: compliance/ validates senders.
• Spec: still iterating in the upstream prometheus/proposals repo and prompb/io/... definitions.

What's next

• Push for receivers to default to RW2 negotiation in 3.x.
• Eventually deprecate RW1 (no firm timeline).

Native histograms

Native histograms started in 2021-10-09 (model/histogram/). They are now stable but the wider ecosystem migration is ongoing.

Status

• Storage: stable in TSDB head, blocks, WAL, agent.
• Wire formats: in RW1 protobuf, RW2 protobuf, OpenMetrics 1.0 (encoded as classical _bucket series + a hint), and the protobuf scrape format.
• PromQL: all the major operators (histogram_quantile, histogram_count, histogram_sum, rate, sum, </>/<//>/).
• OTLP: delta and cumulative paths translate to native histograms.

What's left

• NHCB ergonomics — per-target conversion, ingestion warnings.
• Backwards-compatible exposition format conventions; some scrape targets still emit only classical histograms.
• Continued validation work in tsdb/chunkenc/histogram_meta.go for unusual layouts.

Service discovery slim-builds (3.10)

#17736 introduced the remove_all_sd and enable_<sd>_sd build tags so users can ship binaries with only the SDs they need.

Status

• All SDs implement the build-tag pattern via plugins/plugin_<name>.go.
• The release pipeline ships the all-SDs binary by default; users custom-build slim variants.

What's left

• Document the slim-build workflow in docs/installation.md.
• Maintain test coverage for the matrix — currently CI exercises only the default SD set.

Start timestamps (ST)

Renamed from "Created Timestamps (CT)" for consistency. Stable in 3.10, with --enable-feature=st-storage opting in to TSDB persistence (3.11, #18062).

Status

• Scrape: can ingest start timestamps from PrometheusProto and OpenMetrics 1.0.
• TSDB: behind feature flag (st-storage).
• Agent: same flag.
• RW2: carries ST per sample.
• PromQL: doesn't expose ST as a first-class concept yet — it's implicit in counters.

What's next

• Always-on storage in a future release.
• New PromQL functions to query "since when has this counter been counting?".

XOR2 chunk encoding

Behind --enable-feature=xor2-encoding (3.11). Eventually replaces XOR for scraped data.

Status

• Reader support is present in 3.10+ (so a downgrade after enabling is safe).
• Writer is opt-in via the feature flag.
• The format embeds an explicit chunk start timestamp that XOR doesn't carry.

What's next

• Default-on in a future minor (probably 3.13+).
• Older Prometheus instances cannot read XOR2 chunks; the upgrade path is one-way.