Merge pull request endclothing#32 from Jimdo/get_or_register

Add getOrRegister methods
joyparty · Dec 21, 2016 · 1c45edf · 1c45edf
2 parents 40259be + d77aff2
commit 1c45edf
Show file tree

Hide file tree

Showing 3 changed files with 105 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -19,24 +19,36 @@ While the former needs a separate binary running, the latter just needs the [APC
 A simple counter:
 ```php
 \Prometheus\CollectorRegistry::getDefault()
-    ->registerCounter('', 'some_quick_counter', 'just a quick measurement')
+    ->getOrRegisterCounter('', 'some_quick_counter', 'just a quick measurement')
     ->inc();
 ```
 
 Write some enhanced metrics:
 ```php
 $registry = \Prometheus\CollectorRegistry::getDefault();
 
-$counter = $registry->registerCounter('test', 'some_counter', 'it increases', ['type']);
+$counter = $registry->getOrRegisterCounter('test', 'some_counter', 'it increases', ['type']);
 $counter->incBy(3, ['blue']);
 
-$gauge = $registry->registerGauge('test', 'some_gauge', 'it sets', ['type']);
+$gauge = $registry->getOrRegisterGauge('test', 'some_gauge', 'it sets', ['type']);
 $gauge->set(2.5, ['blue']);
 
-$histogram = $registry->registerHistogram('test', 'some_histogram', 'it observes', ['type'], [0.1, 1, 2, 3.5, 4, 5, 6, 7, 8, 9]);
+$histogram = $registry->getOrRegisterHistogram('test', 'some_histogram', 'it observes', ['type'], [0.1, 1, 2, 3.5, 4, 5, 6, 7, 8, 9]);
 $histogram->observe(3.5, ['blue']);
 ```
 
+Manually register and retrieve metrics (these steps are combined in the `getOrRegister...` methods):
+```php
+$registry = \Prometheus\CollectorRegistry::getDefault();
+
+$counterA = $registry->registerCounter('test', 'some_counter', 'it increases', ['type']);
+$counterA->incBy(3, ['blue']);
+
+// once a metric is registered, it can be retrieved using e.g. getCounter:
+$counterB = $registry->getCounter('test', 'some_counter')
+$counterB->incBy(2, ['red']);
+```
+
 Expose the metrics:
 ```php
 $registry = \Prometheus\CollectorRegistry::getDefault();

diff --git a/src/Prometheus/CollectorRegistry.php b/src/Prometheus/CollectorRegistry.php
@@ -96,6 +96,23 @@ public function getGauge($namespace, $name)
         return $this->gauges[$metricIdentifier];
     }
 
+    /**
+     * @param string $namespace e.g. cms
+     * @param string $name e.g. duration_seconds
+     * @param string $help e.g. The duration something took in seconds.
+     * @param array $labels e.g. ['controller', 'action']
+     * @return Gauge
+     */
+    public function getOrRegisterGauge($namespace, $name, $help, $labels = array())
+    {
+        try {
+            $gauge = $this->getGauge($namespace, $name);
+        } catch (MetricNotFoundException $e) {
+            $gauge = $this->registerGauge($namespace, $name, $help, $labels);
+        }
+        return $gauge;
+    }
+
     /**
      * @param string $namespace e.g. cms
      * @param string $name e.g. requests
@@ -135,6 +152,23 @@ public function getCounter($namespace, $name)
         return $this->counters[self::metricIdentifier($namespace, $name)];
     }
 
+    /**
+     * @param string $namespace e.g. cms
+     * @param string $name e.g. requests
+     * @param string $help e.g. The number of requests made.
+     * @param array $labels e.g. ['controller', 'action']
+     * @return Counter
+     */
+    public function getOrRegisterCounter($namespace, $name, $help, $labels = array())
+    {
+        try {
+            $counter = $this->getCounter($namespace, $name);
+        } catch (MetricNotFoundException $e) {
+            $counter = $this->registerCounter($namespace, $name, $help, $labels);
+        }
+        return $counter;
+    }
+
     /**
      * @param string $namespace e.g. cms
      * @param string $name e.g. duration_seconds
@@ -176,6 +210,24 @@ public function getHistogram($namespace, $name)
         return $this->histograms[self::metricIdentifier($namespace, $name)];
     }
 
+    /**
+     * @param string $namespace e.g. cms
+     * @param string $name e.g. duration_seconds
+     * @param string $help e.g. A histogram of the duration in seconds.
+     * @param array $labels e.g. ['controller', 'action']
+     * @param array $buckets e.g. [100, 200, 300]
+     * @return Histogram
+     */
+    public function getOrRegisterHistogram($namespace, $name, $help, $labels = array(), $buckets = null)
+    {
+        try {
+            $histogram = $this->getHistogram($namespace, $name);
+        } catch (MetricNotFoundException $e) {
+            $histogram = $this->registerHistogram($namespace, $name, $help, $labels, $buckets);
+        }
+        return $histogram;
+    }
+
     private static function metricIdentifier($namespace, $name)
     {
         return $namespace . ":" . $name;

diff --git a/tests/Test/Prometheus/AbstractCollectorRegistryTest.php b/tests/Test/Prometheus/AbstractCollectorRegistryTest.php
@@ -269,5 +269,42 @@ public function itShouldThrowAnExceptionWhenGettingANonExistentMetric()
         $registry->getGauge("not_here", "go_away");
     }
 
+    /**
+     * @test
+     */
+    public function itShouldNotRegisterACounterTwice()
+    {
+        $registry = new CollectorRegistry($this->adapter);
+        $counterA = $registry->getOrRegisterCounter("foo", "bar", "Help text");
+        $counterB = $registry->getOrRegisterCounter("foo", "bar", "Help text");
+
+        $this->assertSame($counterA, $counterB);
+    }
+
+    /**
+     * @test
+     */
+    public function itShouldNotRegisterAGaugeTwice()
+    {
+        $registry = new CollectorRegistry($this->adapter);
+        $gaugeA = $registry->getOrRegisterGauge("foo", "bar", "Help text");
+        $gaugeB = $registry->getOrRegisterGauge("foo", "bar", "Help text");
+
+        $this->assertSame($gaugeA, $gaugeB);
+    }
+
+    /**
+     * @test
+     */
+    public function itShouldNotRegisterAHistogramTwice()
+    {
+        $registry = new CollectorRegistry($this->adapter);
+        $histogramA = $registry->getOrRegisterHistogram("foo", "bar", "Help text");
+        $histogramB = $registry->getOrRegisterHistogram("foo", "bar", "Help text");
+
+        $this->assertSame($histogramA, $histogramB);
+    }
+
+
     public abstract function configureAdapter();
 }