From 91851b42caf8969a53e03eff3b6cf59ec5c57597 Mon Sep 17 00:00:00 2001
From: hrodic <hrodic@protonmail.com>
Date: Mon, 3 May 2021 11:30:31 +0200
Subject: [PATCH] wip

---
 src/Prometheus/Histogram.php                  | 21 +++++++++++++++++++
 .../Test/Prometheus/RenderTextFormatTest.php  |  7 ++++---
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/Prometheus/Histogram.php b/src/Prometheus/Histogram.php
index 0e8fc926..fda1a1a1 100644
--- a/src/Prometheus/Histogram.php
+++ b/src/Prometheus/Histogram.php
@@ -16,6 +16,11 @@ class Histogram extends Collector
      */
     private $buckets;
 
+    /**
+     * @var array e.g [1.1 => Exemplar]
+     */
+    protected $bucketExemplars;
+
     /**
      * @param Adapter    $adapter
      * @param string     $namespace
@@ -129,10 +134,26 @@ public function observe(float $value, array $labels = []): void
                 'labelNames'  => $this->getLabelNames(),
                 'labelValues' => $labels,
                 'buckets'     => $this->buckets,
+                'bucketExemplars' => $this->bucketExemplars,
             ]
         );
     }
 
+    /**
+     * @see https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#exemplars-1
+     * @param float $value
+     * @param array $labels
+     * @param array $exemplarLabels e.g ['traceID' => 'my-trace-id, 'otherLabel' => 'value]
+     * @param int $timestamp e.g 1619827200
+     */
+    public function observeWithExemplar(float $value, array $labels = [], array $exemplarLabels = [], int $timestamp = null): void
+    {
+        foreach ($exemplarLabels as $exemplarLabelKey => $exemplarLabelValue) {
+            self::assertValidLabel($exemplarLabelKey);
+        }
+        $this->observe($value, $labels);
+    }
+
     /**
      * @return string
      */
diff --git a/tests/Test/Prometheus/RenderTextFormatTest.php b/tests/Test/Prometheus/RenderTextFormatTest.php
index 5fa00048..c9a7950e 100644
--- a/tests/Test/Prometheus/RenderTextFormatTest.php
+++ b/tests/Test/Prometheus/RenderTextFormatTest.php
@@ -36,8 +36,9 @@ private function buildSamples(): array
                  ->inc(['bob', 'al\ice']);
         $registry->getOrRegisterGauge($namespace, 'gauge', 'counter-help-text', ['label1', 'label2'])
                  ->inc(["bo\nb", 'ali\"ce']);
-        $registry->getOrRegisterHistogram($namespace, 'histogram', 'counter-help-text', ['label1', 'label2'], [0, 10, 100])
-                 ->observe(5, ['bob', 'alice']);
+        $histogram = $registry->getOrRegisterHistogram($namespace, 'histogram', 'counter-help-text', ['label1', 'label2'], [0, 10, 100]);
+        $histogram->observe(5, ['bob', 'alice']);
+        $histogram->observeWithExemplar(1.337, ['bob', 'alice'], ['traceID' => 'my-trace-id'], 1619827200);
 
         return $registry->getMetricFamilySamples();
     }
@@ -54,7 +55,7 @@ private function getExpectedOutput(): string
 # HELP mynamespace_histogram counter-help-text
 # TYPE mynamespace_histogram histogram
 mynamespace_histogram_bucket{label1="bob",label2="alice",le="0"} 0
-mynamespace_histogram_bucket{label1="bob",label2="alice",le="10"} 1
+mynamespace_histogram_bucket{label1="bob",label2="alice",le="10"} 1 # {trace_id="my-trace-id"} 1.337 1619827200
 mynamespace_histogram_bucket{label1="bob",label2="alice",le="100"} 1
 mynamespace_histogram_bucket{label1="bob",label2="alice",le="+Inf"} 1
 mynamespace_histogram_count{label1="bob",label2="alice"} 1