From 50529b48041dd2104cc0d395d7f58e0cb64947e6 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Rabenstein?= <beorn@grafana.com>
Date: Fri, 14 Oct 2022 13:38:31 +0200
Subject: [PATCH] doc: Document the native histogram JSON format (#11454)

As used in the HTTP query API.

Signed-off-by: beorn7 <beorn@grafana.com>
---
 docs/querying/api.md | 39 +++++++++++++++++++++++++++++++++++++--
 1 file changed, 37 insertions(+), 2 deletions(-)

diff --git a/docs/querying/api.md b/docs/querying/api.md
index 8c3eb9d24..7ac761703 100644
--- a/docs/querying/api.md
+++ b/docs/querying/api.md
@@ -447,6 +447,12 @@ sample values. JSON does not support special float values such as `NaN`, `Inf`,
 and `-Inf`, so sample values are transferred as quoted JSON strings rather than
 raw numbers.
 
+The keys `"histogram"` and `"histograms"` only show up if the experimental
+native histograms are present in the response. Their placeholder `<histogram>`
+is explained in detail in its own section below. Any one object will only have
+the `"value"`/`"values"` key or the `"histogram"`/`"histograms"` key, but not
+both.
+
 ### Range vectors
 
 Range vectors are returned as result type `matrix`. The corresponding
@@ -456,7 +462,8 @@ Range vectors are returned as result type `matrix`. The corresponding
 [
   {
     "metric": { "<label_name>": "<label_value>", ... },
-    "values": [ [ <unix_time>, "<sample_value>" ], ... ]
+    "values": [ [ <unix_time>, "<sample_value>" ], ... ],
+    "histograms": [ [ <unix_time>, <histogram> ], ... ]
   },
   ...
 ]
@@ -471,7 +478,8 @@ Instant vectors are returned as result type `vector`. The corresponding
 [
   {
     "metric": { "<label_name>": "<label_value>", ... },
-    "value": [ <unix_time>, "<sample_value>" ]
+    "value": [ <unix_time>, "<sample_value>" ],
+    "histogram": [ <unix_time>, <histogram> ]
   },
   ...
 ]
@@ -495,6 +503,33 @@ String results are returned as result type `string`. The corresponding
 [ <unix_time>, "<string_value>" ]
 ```
 
+### Native histograms
+
+The `<histogram>` placeholder used above is formatted as follows.
+
+_Note that native histograms are an experimental feature, and the format below
+might still change._
+
+```
+{
+  "count": "<count_of_observations>",
+  "sum": "<sum_of_observations>",
+  "buckets": [ [ <boundary_rule>, "<left_boundary>", "<right_boundary>", "<count_in_bucket>" ], ... ]
+}
+```
+
+The `<boundary_rule>` placeholder is an integer between 0 and 3 with the
+following meaning:
+
+* 0: “open left” (left boundary is exclusive, right boundary in inclusive)
+* 1: “open right” (left boundary is inclusive, right boundary in exclusive)
+* 2: “open both” (both boundaries are exclusive)
+* 3: “closed both” (both boundaries are inclusive)
+
+Note that with the currently implemented bucket schemas, positive buckets are
+“open left”, negative buckets are “open right”, and the zero bucket (with a
+negative left boundary and a positive right boundary) is “closed both”.
+
 ## Targets
 
 The following endpoint returns an overview of the current state of the