Implement Prometheus Counter type

Author: thdebay

src/MetricTypes/Counter.php

@@ -0,0 +1,140 @@
+<?php
+
+namespace Spatie\Prometheus\MetricTypes;
+
+use Closure;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Str;
+use Prometheus\CollectorRegistry;
+use Prometheus\Counter as PrometheusCounter;
+
+class Counter implements MetricType
+{
+    protected array $values = [];
+
+    public function __construct(
+        protected string $label,
+        null|float|Closure|array $initialValue,
+        protected ?string $name = null,
+        protected ?string $namespace = null,
+        protected ?string $helpText = null,
+        protected ?array $labelNames = [],
+        protected string $urlName = 'default',
+    ) {
+        $this->name = $name ?? Str::slug($this->label, '_');
+
+        if (! is_null($initialValue)) {
+            $this->setInitialValue($initialValue);
+        }
+
+        $this->namespace = Str::of(config('prometheus.default_namespace'))
+            ->slug('_')
+            ->lower();
+    }
+
+    public function namespace(string $namespace): self
+    {
+        $this->namespace = $namespace;
+
+        return $this;
+    }
+
+    public function urlName(string $urlName): self
+    {
+        $this->urlName = $urlName;
+
+        return $this;
+    }
+
+    public function getUrlName(): string
+    {
+        return $this->urlName;
+    }
+
+    public function label(string $label): self
+    {
+        $this->labelNames[] = $label;
+
+        return $this;
+    }
+
+    public function labels(array $labelNames): self
+    {
+        $this->labelNames = $labelNames;
+
+        return $this;
+    }
+
+    public function name(string $name): self
+    {
+        $this->name = $name;
+
+        return $this;
+    }
+
+    public function helpText(string $helpText): self
+    {
+        $this->helpText = $helpText;
+
+        return $this;
+    }
+
+    public function setInitialValue(array|float|Closure $value, array|string $labelValues = []): self
+    {
+        $labelValues = Arr::wrap($labelValues);
+
+        $this->values[] = [$value, $labelValues];
+
+        return $this;
+    }
+
+    public function inc(array|float|Closure $value = 1, array|string $labelValues = []): self
+    {
+        $labelValues = Arr::wrap($labelValues);
+
+        $this->values[] = [$value, $labelValues];
+
+        return $this;
+    }
+
+    public function register(CollectorRegistry $registry): self
+    {
+        $counter = $registry->getOrRegisterCounter(
+            namespace: $this->namespace,
+            name: $this->name,
+            help: $this->helpText ?? '',
+            labels: $this->labelNames,
+        );
+
+        collect($this->values)
+            ->each(function (array $valueAndLabels) use ($counter) {
+                $this->handleValueAndLabels(counter: $counter, valueAndLabels: $valueAndLabels);
+            });
+
+        return $this;
+    }
+
+    protected function handleValueAndLabels(PrometheusCounter $counter, array $valueAndLabels)
+    {
+        [$value, $labels] = $valueAndLabels;
+        $value = value($value);
+
+        if (is_array($value) && Arr::exists($value, 0) && is_array($value[0])) {
+            foreach ($value as $valueAndLabels) {
+                $this->handleValueAndLabels(counter: $counter, valueAndLabels: $valueAndLabels);
+            }
+
+            return;
+        }
+
+        if (is_array($value) && count($value) === 0) {
+            return;
+        }
+
+        if (is_array(($value))) {
+            [$value, $labels] = $value;
+        }
+
+        $counter->incBy(count: $value, labels: $labels);
+    }
+}

src/Prometheus.php

@@ -3,6 +3,7 @@
 namespace Spatie\Prometheus;
 
 use Spatie\Prometheus\Collectors\Collector;
+use Spatie\Prometheus\MetricTypes\Counter;
 use Spatie\Prometheus\MetricTypes\Gauge;
 use Spatie\Prometheus\MetricTypes\MetricType;
 
@@ -25,6 +26,20 @@ public function addGauge(
         return $collector;
     }
 
+    public function addCounter(
+        string $label,
+        int|callable|null $initialValue = null,
+        ?string $name = null,
+        ?string $namespace = null,
+        ?string $helpText = null,
+    ): Counter {
+        $collector = new Counter(label: $label, initialValue: $initialValue, name: $name, namespace: $namespace, helpText: $helpText);
+
+        $this->registerCollector($collector);
+
+        return $collector;
+    }
+
     public function registerCollector(MetricType $collector): self
     {
         $this->collectors[] = $collector;

tests/Http/Controllers/PrometheusMetricsControllerTest.php

@@ -124,3 +124,104 @@
 
     assertPrometheusResultsMatchesSnapshot();
 });
+
+it('can render a simple counter with initial value', function () {
+    /** @var \Spatie\Prometheus\MetricTypes\Counter $counter */
+    Prometheus::addCounter('my counter');
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('can render a counter with all options', function () {
+    /** @var \Spatie\Prometheus\MetricTypes\Counter $counter */
+    Prometheus::addCounter('my counter')
+        ->namespace('other_namespace')
+        ->helpText('This is the help text')
+        ->name('alternative_name')
+        ->setInitialValue(123);
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('can increment a counter by one as default', function () {
+    /** @var \Spatie\Prometheus\MetricTypes\Counter $counter */
+    Prometheus::addCounter('my counter')
+        ->setInitialValue(1)
+        ->inc();
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('can increment a counter by a custom value', function () {
+    /** @var \Spatie\Prometheus\MetricTypes\Counter $counter */
+    $counter = Prometheus::addCounter('my counter');
+    $counter->inc(2);
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('can render a counter that returns a single result with labels in the closure', closure: function () {
+    Prometheus::addCounter('my counter', function () {
+        return [1, ['label_value']];
+    })->label('label_name');
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('can render a counter that returns a multiple results with labels in the closure', closure: function () {
+    Prometheus::addCounter('my counter', function () {
+        return [
+            [123, ['label_value']],
+            [456, ['label_value_2']],
+        ];
+    })->label('label_name');
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('can render a counter with labels', function () {
+    /** @var \Spatie\Prometheus\MetricTypes\Gauge $counter */
+    $counter = Prometheus::addCounter('my counter');
+
+    $counter
+        ->namespace('other_namespace')
+        ->labels(['label_name_1', 'label_name_2'])
+        ->setInitialValue(123, ['label_value_1', 'label_value_2'])
+        ->setInitialValue(124, ['label_value_3', 'label_value_4']);
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('will render the counters on the default url', closure: function () {
+    config()->set('prometheus.urls', [
+        'default' => '/prometheus',
+        'alternative' => '/my-alternative-route',
+    ]);
+
+    $this->reloadServiceProvider();
+
+    Prometheus::addCounter('my default counter', 123);
+    Prometheus::addCounter('my alternative counter', 123)->urlName('alternative');
+
+    assertPrometheusResultsMatchesSnapshot();
+});
+
+it('will render the counters on the alternative url', closure: function () {
+    config()->set('prometheus.urls', [
+        'default' => '/prometheus',
+        'alternative' => '/my-alternative-route',
+    ]);
+
+    $this->reloadServiceProvider();
+
+    Prometheus::addCounter('my default counter', 123);
+    Prometheus::addCounter('my alternative counter', 123)->urlName('alternative');
+
+    assertPrometheusResultsMatchesSnapshot('alternative');
+});
+
+it('will convert the counter name to snake case', closure: function () {
+    Prometheus::addCounter('My Counter', 123);
+
+    assertPrometheusResultsMatchesSnapshot();
+});

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_increment_a_counter_by_a_custom_value__1.txt

@@ -0,0 +1,3 @@
+# HELP app_my_counter 
+# TYPE app_my_counter counter
+app_my_counter 2

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_increment_a_counter_by_one_as_default__1.txt

@@ -0,0 +1,3 @@
+# HELP app_my_counter 
+# TYPE app_my_counter counter
+app_my_counter 2

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_render_a_counter_that_returns_a_multiple_results_with_labels_in_the_closure__1.txt

@@ -0,0 +1,4 @@
+# HELP app_my_counter 
+# TYPE app_my_counter counter
+app_my_counter{label_name="label_value"} 123
+app_my_counter{label_name="label_value_2"} 456

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_render_a_counter_that_returns_a_single_result_with_labels_in_the_closure__1.txt

@@ -0,0 +1,3 @@
+# HELP app_my_counter 
+# TYPE app_my_counter counter
+app_my_counter{label_name="label_value"} 1

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_render_a_counter_with_all_options__1.txt

@@ -0,0 +1,3 @@
+# HELP other_namespace_alternative_name This is the help text
+# TYPE other_namespace_alternative_name counter
+other_namespace_alternative_name 123

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_render_a_counter_with_labels__1.txt

@@ -0,0 +1,4 @@
+# HELP other_namespace_my_counter 
+# TYPE other_namespace_my_counter counter
+other_namespace_my_counter{label_name_1="label_value_1",label_name_2="label_value_2"} 123
+other_namespace_my_counter{label_name_1="label_value_3",label_name_2="label_value_4"} 124

tests/__snapshots__/PrometheusMetricsControllerTest__it_can_render_a_simple_counter_with_initial_value__1.txt

@@ -0,0 +1 @@
+