Merge 85c6081 into 367cbff

README.md

@@ -254,6 +254,49 @@ class MyComponent
 end
 ```
 
+### `init_label_set`
+
+The time series of a metric are not initialiazed until something happens. For counters, for example, this means that the time series do not exist until the counter is increamented for the first time.
+
+This can lead to cases that are hard to handle:
+
+```ruby
+counter =
+  Counter.new(
+    :http_requests_total,
+    docstring: '...',
+    labels: [:app, :env, :version],
+  )
+
+# After declaring the counter nothing is exported because the time series have not been initialized
+
+# We call increment for the first time and the time serie for the label set provided is initialiazed
+counter.increment(labels: {app: "frontend", env: "production", version: "v1"})
+
+# Client starts exporting
+# http_requests_total{app="frontend", env="production", version="v1"} 1
+
+# We call increment again
+counter.increment(labels: {app: "frontend", env: "production", version: "v1"})
+
+# Client exports
+# http_requests_total{app="frontend", env="production", version="v1"} 2
+
+# In the server when we calculate the increase of the counter, increase([1, 2]), we get 1 as a result although we increased the counter twice
+```
+
+To get around this problem the client provides the `init_label_set` method that can be used to initialises the time serie of a metric for a given label set. In the example above we would use it like so:
+
+```ruby
+# After declaring the counter we can initiliaze the metric by calling the #init_label_set method
+counter.init_label_set(app: "frontend", env: "production", version: "v1")
+
+# The client starts exporting the metric right away
+# http_requests_total{app="frontend", env="production", version="v1"} 0
+
+After two increments we can calculate the increase, increase([0, 1, 2]), and get 2 as a result (the correct result)
+```
+
 ### Reserved labels
 
 The following labels are reserved by the client library, and attempting to use them in a

lib/prometheus/client/histogram.rb

@@ -94,6 +94,16 @@ def values
         end
       end
 
+      def init_label_set(labels)
+        base_label_set = label_set_for(labels)
+
+        @store.synchronize do
+          [*@buckets, "+Inf", "sum"].each do |bucket|
+            @store.set(labels: base_label_set.merge(le: bucket.to_s), val: 0)
+          end
+        end
+      end
+
       private
 
       # Modifies the passed in parameter

lib/prometheus/client/metric.rb

@@ -55,6 +55,10 @@ def with_labels(labels)
                        store_settings: @store_settings)
       end
 
+      def init_label_set(labels)
+        @store.set(labels: label_set_for(labels), val: 0)
+      end
+
       # Returns all label sets with their values
       def values
         @store.all_values

lib/prometheus/client/summary.rb

@@ -45,6 +45,15 @@ def values
         end
       end
 
+      def init_label_set(labels)
+        base_label_set = label_set_for(labels)
+
+        @store.synchronize do
+          @store.set(labels: base_label_set.merge(quantile: "count"), val: 0)
+          @store.set(labels: base_label_set.merge(quantile: "sum"), val: 0)
+        end
+      end
+
       private
 
       def reserved_labels

spec/prometheus/client/counter_spec.rb

@@ -102,4 +102,16 @@
       end
     end
   end
+
+  describe '#init_label_set' do
+    let(:expected_labels) { [:test] }
+
+    it 'initializes the metric for a given label set' do
+      expect(counter.values).to eql({})
+
+      counter.init_label_set(test: 'value')
+
+      expect(counter.values).to eql({test: 'value'} => 0.0)
+    end
+  end
 end

spec/prometheus/client/gauge_spec.rb

@@ -184,4 +184,16 @@
       end.to change { gauge.get }.by(-100.0)
     end
   end
+
+  describe '#init_label_set' do
+    let(:expected_labels) { [:test] }
+
+    it 'initializes the metric for a given label set' do
+      expect(gauge.values).to eql({})
+
+      gauge.init_label_set(test: 'value')
+
+      expect(gauge.values).to eql({test: 'value'} => 0.0)
+    end
+  end
 end

spec/prometheus/client/histogram_spec.rb

@@ -147,4 +147,20 @@
       )
     end
   end
+
+  describe '#init_label_set' do
+    let(:expected_labels) { [:status] }
+
+    it 'initializes the metric for a given label set' do
+      expect(histogram.values).to eql({})
+
+      histogram.init_label_set(status: 'bar')
+      histogram.init_label_set(status: 'foo')
+
+      expect(histogram.values).to eql(
+        { status: 'bar' } => { "2.5" => 0.0, "5" => 0.0, "10" => 0.0, "+Inf" => 0.0, "sum" => 0.0 },
+        { status: 'foo' } => { "2.5" => 0.0, "5" => 0.0, "10" => 0.0, "+Inf" => 0.0, "sum" => 0.0 },
+      )
+    end
+  end
 end

spec/prometheus/client/summary_spec.rb

@@ -126,4 +126,20 @@
       )
     end
   end
+
+  describe '#init_label_set' do
+    let(:expected_labels) { [:status] }
+
+    it 'initializes the metric for a given label set' do
+      expect(summary.values).to eql({})
+
+      summary.init_label_set(status: 'bar')
+      summary.init_label_set(status: 'foo')
+
+      expect(summary.values).to eql(
+        { status: 'bar' } => { "count" => 0.0, "sum" => 0.0 },
+        { status: 'foo' } => { "count" => 0.0, "sum" => 0.0 },
+      )
+    end
+  end
 end