Merge pull request #277 from prometheus/sinjo-loosen-reserved-labels

Allow use of `instance` and `job` labels

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