Allow use of instance and job labels

These labels were previously reserved under all circumstances, but
Prometheus server handles them just fine in the metric data it scrapes.

The reason we'd reserved them is that Prometheus automatically generates
values for them when it scrapes a target, and we didn't want to cause a
collision. It turns out Prometheus handles that collision just fine.

By default, Prometheus server will prepend `exported_` to them if
they're present in the scraped data (i.e. `exported_instance` and
`exported_job`). Users can set `honor_labels` in their Prometheus server
config if they prefer the labels from the scraped metric data to take
precedence over the labels generated by the server.

Signed-off-by: Chris Sinjakli <chris@sinjakli.co.uk>

Author: Sinjo

CHANGELOG.md

@@ -2,7 +2,22 @@
 
 # Unreleased changes
 
-_None outstanding_
+## Small improvements
+
+- [#277](https://github.com/prometheus/client_ruby/pull/277) Allow use of `instance` and
+    `job` labels:
+    It's now possible to set the `instance` and `job` labels on metrics, where previously
+    they had been reserved.
+
+    The reason we'd reserved them is that Prometheus automatically generates values
+    for them when it scrapes a target, and we didn't want to cause a collision. It
+    turns out Prometheus handles that collision just fine.
+
+    By default, Prometheus server will prepend `exported_` to them if they're present
+    in the scraped data (i.e. `exported_instance` and `exported_job`). Users can set
+    `honor_labels` in their Prometheus server config if they prefer the labels from
+    the scraped metric data to take precedence over the labels generated by the
+    server.
 
 # 4.0.0 / 2022-03-27
 

lib/prometheus/client/label_set_validator.rb

@@ -5,8 +5,7 @@ module Client
     # LabelSetValidator ensures that all used label sets comply with the
     # Prometheus specification.
     class LabelSetValidator
-      # TODO: we might allow setting :instance in the future
-      BASE_RESERVED_LABELS = [:job, :instance, :pid].freeze
+      BASE_RESERVED_LABELS = [:pid].freeze
       LABEL_NAME_REGEX = /\A[a-zA-Z_][a-zA-Z0-9_]*\Z/
 
       class LabelSetError < StandardError; end

spec/prometheus/client/label_set_validator_spec.rb

@@ -4,7 +4,10 @@
 
 describe Prometheus::Client::LabelSetValidator do
   let(:expected_labels) { [] }
-  let(:validator) { Prometheus::Client::LabelSetValidator.new(expected_labels: expected_labels) }
+  let(:additional_reserved_labels) { [] }
+  let(:validator) do
+    Prometheus::Client::LabelSetValidator.new(expected_labels: expected_labels, reserved_labels: additional_reserved_labels)
+  end
   let(:invalid) { Prometheus::Client::LabelSetValidator::InvalidLabelSetError }
 
   describe '.new' do
@@ -42,11 +45,27 @@
       end.to raise_exception(described_class::InvalidLabelError)
     end
 
-    it 'raises ReservedLabelError if a label key is reserved' do
-      [:job, :instance, :pid].each do |label|
-        expect do
-          validator.validate_symbols!(label => 'value')
-        end.to raise_exception(described_class::ReservedLabelError)
+    context "with only the base set of reserved labels" do
+      it "doesn't raise ReservedLabelError for the additional reserved label" do
+        expect { validator.validate_symbols!(additional: 'value') }.
+          to_not raise_exception
+      end
+
+      it 'raises ReservedLabelError if a label key is reserved' do
+        expect { validator.validate_symbols!(pid: 'value') }.
+          to raise_exception(described_class::ReservedLabelError)
+      end
+    end
+
+    context "with an additional reserved label" do
+      let(:additional_reserved_labels) { [:additional] }
+
+      it 'raises ReservedLabelError if a label key is reserved' do
+        [:additional, :pid].each do |label|
+          expect do
+            validator.validate_symbols!(label => 'value')
+          end.to raise_exception(described_class::ReservedLabelError)
+        end
       end
     end
   end