Improve histogram documentation

Signed-off-by: beorn7 <beorn@grafana.com>
prometheus · Jul 10, 2024 · 472bd39 · 472bd39
1 parent 4a68a11
commit 472bd39
Showing 1 changed file with 39 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -82,9 +82,11 @@ Example input from stdin:
 Note that all numbers are encoded as strings. Some parsers want it
 that way. Also, Prometheus allows sample values like `NaN` or `+Inf`,
 which cannot be encoded as JSON numbers.
-Native histograms are formated similarly as [the query 
-API](https://prometheus.io/docs/prometheus/latest/querying/api/#native-histograms) 
-would return.
+
+A histogram is formatted as a native histogram if it has at least one span. It
+is then formatted in a similar way as [the Prometehus query
+API](https://prometheus.io/docs/prometheus/latest/querying/api/#native-histograms)
+does it.
 
 ```json
 [
@@ -136,7 +138,7 @@ would return.
   {
     "name": "http_request_duration_seconds",
     "type": "HISTOGRAM",
-    "help": "More HTTP request latencies in seconds.",
+    "help": "This is a native histogram.",
     "metrics": [
       {
         "labels": {
@@ -166,6 +168,39 @@ would return.
         "sum": "29969.50000000001"
       }
     ]
+  },
+  {
+    "name": "some_weird_normal_distribution",
+    "type": "HISTOGRAM",
+    "help": "This is a classic histogram.",
+    "metrics": [
+      {
+        "buckets": {
+          "-0.0001899999999999998": "17",
+          "-0.0002899999999999998": "6",
+          "-0.0003899999999999998": "2",
+          "-0.0004899999999999998": "2",
+          "-0.0005899999999999998": "0",
+          "-0.0006899999999999999": "0",
+          "-0.0007899999999999999": "0",
+          "-0.00089": "0",
+          "-0.00099": "0",
+          "-8.999999999999979e-05": "33",
+          "0.00011000000000000022": "75",
+          "0.00021000000000000023": "92",
+          "0.0003100000000000002": "100",
+          "0.0004100000000000002": "103",
+          "0.0005100000000000003": "105",
+          "0.0006100000000000003": "106",
+          "0.0007100000000000003": "107",
+          "0.0008100000000000004": "107",
+          "0.0009100000000000004": "107",
+          "1.0000000000000216e-05": "50"
+        },
+        "count": "107",
+        "sum": "0.001792103516591124"
+      }
+    ]
   }
 ]
 ```