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.

DocumentInitial dateStatusPull requests
Secure Alertmanager cluster traffic2019‑02‑21Approvedalertmanager#2237
TSDB Head Improvements (part1 - part 2)2019‑12‑09Partially implemented
Persist Retroactive Rules2020‑06‑12Partially implemented#7675
topk/bottomk aggregation over time2020‑09‑30Implemented#8121 #8425
httpsd_configs2021‑02‑26Under review#8839
prometheus/client_java & micrometer2021‑02‑26Under review
First-class network monitoring support in the Prometheus & Grafana ecosystem2021‑02‑25Under review
Configuration handling in exporters and Prometheus 3.x2021‑03‑29Under review
Prometheus Agent2021‑01‑27Approved#8785
Sparse high-resolution histograms2021‑02‑10Approved
<a href=”https://docs.google.com/document/d/1xfw1Lb1GIRZB-4iFVGkgwnpwuBemWfxYqFdBm7APsE/edit”>Prometheus timezones support2021‑05‑29Proposed
Moving to goreleaser2021‑06‑05Proposed
Alertmanager Log Receiver2021‑06‑10Proposed
Extra HTTP parameters in the blackbox exporter2021‑06‑23Proposed
Making durations and number literals the same2021‑07‑26In progress#9138
MetadataTODO
OpenMetrics transitionTODO
Semantics of muting in AlertmanagerTODO
Extrapolation in range selectors (xrate)Under review
Serverless, MQTT, and IoT use cases in the Prometheus ecosystemTODO
Static arithmetic for timestamps and durationsTODO
Prometheus long-term supported releases2022-03-02Proposed
Support for out of order samples in the TSDB2022-04-13Proposed

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.

DocumentInitial date
Prometheus is not feature complete2020-05
Thoughts about timestamps and durations in PromQL2020-10
Prometheus, OpenMetrics & OTLP2021-03
Prometheus Sparse Histograms and PromQL2021-10