Add a design docs page

[roidelapluie]

Signed-off-by: Julien Pivotto roidelapluie@inuits.eu

[roidelapluie]

I will add more design docs once we agree on the principle.

[RichiH]

I think the thing is good, just those nits. Sent by mobile; please excuse my brevity.

…

On Sat, May 29, 2021, 01:09 Julien Pivotto ***@***.***> wrote: I will add more design docs once we agree on the principle. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#1961 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFYII4ZC2UTYMHSW3FSO33TQAPDPANCNFSM45XTOQTQ> .

[beorn7]

Looks great in general.

Do you want to fill in more design docs here right now? Or do that in later PRs?

[beorn7]

In case it's useful, here my brainstorm:

• prometheus/client_java & micrometer (status: under review, I guess): https://docs.google.com/document/d/1vROky2aIw3kAllfi95gwDJy5P2DyWnCihsjPXGpLwwo/edit#
• Configuration handling in exporters and Prometheus 3.x (status: under review): https://docs.google.com/document/d/1BK_Gc3ixoWyxr9F5qGC07HEcfDPtb6z96mfqoGyz52Y/edit#heading=h.zcana55kzmxi
• http_sd_configs (status: under review, being implemented): https://docs.google.com/document/d/1tVeuzjpU4-TiYPNWJXKmcyIuZF6A2tUq270RbBT5zho/edit
• Prom Agent (status: approved, more or less, and being implemented): https://docs.google.com/document/d/1cCcoFgjDFwU2n823tKuMvrIhzHty4UDyn0IcfUHiyyI/edit
• Sparse high-resolution histograms (status: approved): https://docs.google.com/document/d/1cLNv3aufPZb3fNfaJgdaRBZsInZKKIHo9E6HinJVbpM/edit
• OpenMetrics transition (status: TODO): (as per dev-summit consensus: "We will create a design document exploring upgrade paths.")
• Metadata (status: empty, oops): https://docs.google.com/document/d/1XiZePSjwU4X5iaIgCIvLzljJzl8lRAdvputuborUcaQ/edit
• topk/bottomk aggregation over time (status: implemented): https://docs.google.com/document/d/1uSbD3T2beM-iX4-Hp7V074bzBRiRNlqUdcWP6JTDQSs/edit
• Semantics of muting in Alertmanager (status: TODO): (as per dev-summit consensus: "We will create a document for the community to collect current pain points and desired behaviour"
• First-class network monitoring support in the Prometheus & Grafana ecosystem (status: under review): https://docs.google.com/document/d/1oEpjiWfTHF352NCAOGolwij3EIkrprCkdQmaQMpjg4M/edit
• Persist Retroactive Rules (status: approved, partially implemented): https://docs.google.com/document/d/16s_-RxYwQYcb4G4mvpmjPolEbD24o54a1LPqJ538Vhc/edit
• TSDB Head Improvements (status: implemented, at least partially, or all? paging @codesome ): https://docs.google.com/document/d/184urkLQnM7rqLmGvS66I15jU2pyPk_qwd8v_qDlXczo/edit# and https://docs.google.com/document/d/1pnEsxB0CDLOxQipGw_vhkJpoDZfZPs_KjqCriumDAXQ/edit

(This is not meant to be a complete list. ;)

[beorn7]

• Secure Alertmanager cluster traffic (status: being implemented in Secure cluster traffic via mutual TLS alertmanager#2237): https://github.com/prometheus/alertmanager/blob/master/doc/design/secure-cluster-traffic.md

[codesome]

TSDB Head Improvements (status: implemented, at least partially, or all? paging @codesome ): https://docs.google.com/document/d/184urkLQnM7rqLmGvS66I15jU2pyPk_qwd8v_qDlXczo/edit# and https://docs.google.com/document/d/1pnEsxB0CDLOxQipGw_vhkJpoDZfZPs_KjqCriumDAXQ/edit

Only the m-mapping of "full" chunks is done among them. The idea about "partial chunks" is in-progress (the snapshot PR).

Plus, everything in that doc is not planned to be implemented (for example the number 5 in second doc about series and tombstones). And the doc might/will not be 100% in sync with what was finally implemented or being implemented.

[beorn7]

Thanks @codesome .

I guess a certain degree of "we did this differently after all" is inherent to most design docs. So I don't think we have to call that out explicitly (but perhaps it's worth mentioning in the preamble on this page?).

[beorn7]

Thanks for adding all those links to the table.

I found a few syntax issues, see comments.

In different news: Are you aware that we can use markdown tables on the site? See https://github.com/prometheus/docs/blob/master/content/docs/practices/histograms.md .

[beorn7]

Design doc dot not… → Design docs do not…

[beorn7]

Link text and URL are switched here. (URL needs to be the href and "document 1/2" needs to be the text content of the tag.)

[beorn7]

The </a> has to be moved after the title.

[beorn7]

An now there is the goreleaser design doc.

List is growing quickly. I guess it makes sense to merge this rather sooner than later so that we all can iterate on it easily.

(But see my syntax remarks above. And my question if we can't just use markdown tables, which would avoid those syntax quirks altogether.)

[beorn7]

I guess we should also add a TODO entry for reconsidering extrapolation with range selectors (rate/increase/delta) AKA "the (x)rate controversy". At the dev summit 2020/2, we stated: "We want to rethink this from first principles. We will collect our research, thoughts, considerations, and results in 'Prometheus is not feature complete' and discuss at a future dev summit."

I think the topic deserves a fully fledged design doc. I guess we just hadn't developed the habit back then and thought, we could shove it in that existing "Prometheus is not feature complete" document.

[beorn7]

Looks great.

I'd say, let's merge and iron out any other nits incrementally later.

[RichiH]

Minor nits; looks good otherwise, thanks!

[RichiH]

Suggested change

	Design doc do not always reflect exactly what has been implemented, and
	Design docs do not always reflect exactly what has been implemented, and

[RichiH]

Thanks!

[roidelapluie]

Note: in my last push, I have used "unbreakable dashes" instead of "dashes" for the dated. It keeps them on the same line in the page, I think it renders better.