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..b8cf288a 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,11 +55,11 @@ 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="100"} 1 -mynamespace_histogram_bucket{label1="bob",label2="alice",le="+Inf"} 1 -mynamespace_histogram_count{label1="bob",label2="alice"} 1 -mynamespace_histogram_sum{label1="bob",label2="alice"} 5 +mynamespace_histogram_bucket{label1="bob",label2="alice",le="10"} 2 # {trace_id="my-trace-id"} 1.337 1619827200 +mynamespace_histogram_bucket{label1="bob",label2="alice",le="100"} 2 +mynamespace_histogram_bucket{label1="bob",label2="alice",le="+Inf"} 2 +mynamespace_histogram_count{label1="bob",label2="alice"} 2 +mynamespace_histogram_sum{label1="bob",label2="alice"} 6.337 TEXTPLAIN; }