prometheus/docs/stability.md
Julius Volz 4a5aef0495
Merge release-2.28 back into main (#8975)
* Cut v2.28.0-rc.0 (#8954)

* Cut v2.28.0-rc.0

Signed-off-by: Julius Volz <julius.volz@gmail.com>

* Changelog fixup

Signed-off-by: Julius Volz <julius.volz@gmail.com>

* Address review comments

Signed-off-by: Julius Volz <julius.volz@gmail.com>

* Downgrade some features to enhancements

Signed-off-by: Julius Volz <julius.volz@gmail.com>

* Adjust release date to today

Signed-off-by: Julius Volz <julius.volz@gmail.com>

* Migrate HTTP SD docs from docs repo (#8972)

See discussion in https://github.com/prometheus/docs/pull/1975

Signed-off-by: Julius Volz <julius.volz@gmail.com>

* Cut Prometheus v2.28.0 (#8973)

Signed-off-by: Julius Volz <julius.volz@gmail.com>
2021-06-22 00:59:31 +02:00

1.6 KiB

title sort_rank
API Stability 10

API Stability Guarantees

Prometheus promises API stability within a major version, and strives to avoid breaking changes for key features. Some features, which are cosmetic, still under development, or depend on 3rd party services, are not covered by this.

Things considered stable for 2.x:

  • The query language and data model
  • Alerting and recording rules
  • The ingestion exposition format
  • v1 HTTP API (used by dashboards and UIs)
  • Configuration file format (minus the service discovery remote read/write, see below)
  • Rule/alert file format
  • Console template syntax and semantics

Things considered unstable for 2.x:

  • Any feature listed as experimental or subject to change, including:
  • Server-side HTTPS and basic authentication
  • Service discovery integrations, with the exception of static_configs and file_sd_configs
  • Go APIs of packages that are part of the server
  • HTML generated by the web UI
  • The metrics in the /metrics endpoint of Prometheus itself
  • Exact on-disk format. Potential changes however, will be forward compatible and transparently handled by Prometheus
  • The format of the logs

As long as you are not using any features marked as experimental/unstable, an upgrade within a major version can usually be performed without any operational adjustments and very little risk that anything will break. Any breaking changes will be marked as CHANGE in release notes.