Design documents

When contributing large changes or features to the Prometheus ecosystem, design documents are written by individuals or groups. Those documents are proposed for review and approval to the community.

This page is a list of the design documents we know of. If you create a new design document, or some documents are not listed, please open a pull request to add it to this list.

Design docs do not always reflect exactly what has been implemented, and implementation details might have changed since a feature was merged. Design docs are not considered documentation and can not define a standard.

If you want to pick a design doc in TODO or implement a proposed design doc, please reach out to the developers mailing list first to make sure no one else has picked that task already, and the design doc is approved and still relevant.

Document Initial date Status Pull requests
Secure Alertmanager cluster traffic 2019‑02‑21 Approved alertmanager#2237
TSDB Head Improvements (part1 - part 2) 2019‑12‑09 Partially implemented
Persist Retroactive Rules 2020‑06‑12 Partially implemented #7675
topk/bottomk aggregation over time 2020‑09‑30 Implemented #8121 #8425
http_sd_configs 2021‑02‑26 Under review #8839
prometheus/client_java & micrometer 2021‑02‑26 Under review
First-class network monitoring support in the Prometheus & Grafana ecosystem 2021‑02‑25 Under review
Configuration handling in exporters and Prometheus 3.x 2021‑03‑29 Under review
Prometheus Agent 2021‑01‑27 Approved #8785
Sparse high-resolution histograms 2021‑02‑10 Approved
Prometheus timezones support 2021‑05‑29 Proposed
Moving to goreleaser 2021‑06‑05 Proposed
Alertmanager Log Receiver 2021‑06‑10 Proposed
Extra HTTP parameters in the blackbox exporter 2021‑06‑23 Proposed
Making durations and number literals the same 2021‑07‑26 In progress #9138
Metadata TODO
OpenMetrics transition TODO
Semantics of muting in Alertmanager TODO
Extrapolation in range selectors (xrange) TODO
Serverless, MQTT, and IoT use cases in the Prometheus ecosystem TODO
Static arithmetic for timestamps and durations TODO

Problem statements and exploratory documents

Sometimes we're looking even further into potential futures. The documents in this section are largely exploratory. They should be taken as informing our collective thoughts, not as anything concrete or specific.

Document Initial date
Prometheus is not feature complete 2020-05
Thoughts about timestamps and durations in PromQL 2020-10
Prometheus, OpenMetrics & OTLP 2021-03
Prometheus Sparse Histograms and PromQL 2021-10

This documentation is open-source. Please help improve it by filing issues or pull requests.