vm-client 1.0.0

data/lib/prometheus/client/data_stores/single_threaded.rb

@@ -0,0 +1,56 @@
+module Prometheus
+  module Client
+    module DataStores
+      # Stores all the data in a simple Hash for each Metric
+      #
+      # Has *no* synchronization primitives, making it the fastest store for single-threaded
+      # scenarios, but must absolutely not be used in multi-threaded scenarios.
+      class SingleThreaded
+        class InvalidStoreSettingsError < StandardError; end
+
+        def for_metric(metric_name, metric_type:, metric_settings: {})
+          # We don't need `metric_type` or `metric_settings` for this particular store
+          validate_metric_settings(metric_settings: metric_settings)
+          MetricStore.new
+        end
+
+        private
+
+        def validate_metric_settings(metric_settings:)
+          unless metric_settings.empty?
+            raise InvalidStoreSettingsError,
+                  "SingleThreaded doesn't allow any metric_settings"
+          end
+        end
+
+        class MetricStore
+          def initialize
+            @internal_store = Hash.new { |hash, key| hash[key] = 0.0 }
+          end
+
+          def synchronize
+            yield
+          end
+
+          def set(labels:, val:)
+            @internal_store[labels] = val.to_f
+          end
+
+          def increment(labels:, by: 1)
+            @internal_store[labels] += by
+          end
+
+          def get(labels:)
+            @internal_store[labels]
+          end
+
+          def all_values
+            @internal_store.dup
+          end
+        end
+
+        private_constant :MetricStore
+      end
+    end
+  end
+end

data/lib/prometheus/client/data_stores/synchronized.rb

@@ -0,0 +1,62 @@
+module Prometheus
+  module Client
+    module DataStores
+      # Stores all the data in simple hashes, one per metric. Each of these metrics
+      # synchronizes access to their hash, but multiple metrics can run observations
+      # concurrently.
+      class Synchronized
+        class InvalidStoreSettingsError < StandardError; end
+
+        def for_metric(metric_name, metric_type:, metric_settings: {})
+          # We don't need `metric_type` or `metric_settings` for this particular store
+          validate_metric_settings(metric_settings: metric_settings)
+          MetricStore.new
+        end
+
+        private
+
+        def validate_metric_settings(metric_settings:)
+          unless metric_settings.empty?
+            raise InvalidStoreSettingsError,
+                  "Synchronized doesn't allow any metric_settings"
+          end
+        end
+
+        class MetricStore
+          def initialize
+            @internal_store = Hash.new { |hash, key| hash[key] = 0.0 }
+            @lock = Monitor.new
+          end
+
+          def synchronize
+            @lock.synchronize { yield }
+          end
+
+          def set(labels:, val:)
+            synchronize do
+              @internal_store[labels] = val.to_f
+            end
+          end
+
+          def increment(labels:, by: 1)
+            synchronize do
+              @internal_store[labels] += by
+            end
+          end
+
+          def get(labels:)
+            synchronize do
+              @internal_store[labels]
+            end
+          end
+
+          def all_values
+            synchronize { @internal_store.dup }
+          end
+        end
+
+        private_constant :MetricStore
+      end
+    end
+  end
+end

data/lib/prometheus/client/formats/text.rb

@@ -0,0 +1,106 @@
+# encoding: UTF-8
+
+module Prometheus
+  module Client
+    module Formats
+      # Text format is human readable mainly used for manual inspection.
+      module Text
+        MEDIA_TYPE   = 'text/plain'.freeze
+        VERSION      = '0.0.4'.freeze
+        CONTENT_TYPE = "#{MEDIA_TYPE}; version=#{VERSION}".freeze
+
+        METRIC_LINE = '%s%s %s'.freeze
+        TYPE_LINE   = '# TYPE %s %s'.freeze
+        HELP_LINE   = '# HELP %s %s'.freeze
+
+        LABEL     = '%s="%s"'.freeze
+        SEPARATOR = ','.freeze
+        DELIMITER = "\n".freeze
+
+        REGEX   = { doc: /[\n\\]/, label: /[\n\\"]/ }.freeze
+        REPLACE = { "\n" => '\n', '\\' => '\\\\', '"' => '\"' }.freeze
+
+        def self.marshal(registry)
+          lines = []
+
+          registry.metrics.each do |metric|
+            lines << format(TYPE_LINE, metric.name, metric.type)
+            lines << format(HELP_LINE, metric.name, escape(metric.docstring))
+
+            metric.values.each do |label_set, value|
+              representation(metric, label_set, value) { |l| lines << l }
+            end
+          end
+
+          # there must be a trailing delimiter
+          (lines << nil).join(DELIMITER)
+        end
+
+        class << self
+          private
+
+          def representation(metric, label_set, value, &block)
+            if metric.type == :summary
+              summary(metric.name, label_set, value, &block)
+            elsif metric.type == :histogram
+              histogram(metric.name, label_set, value, &block)
+            elsif metric.type == :vm_histogram
+              vm_histogram(metric.name, label_set, value, &block)
+            else
+              yield metric(metric.name, labels(label_set), value)
+            end
+          end
+
+          def summary(name, set, value)
+            l = labels(set)
+            yield metric("#{name}_sum", l, value["sum"])
+            yield metric("#{name}_count", l, value["count"])
+          end
+
+          def histogram(name, set, value)
+            bucket = "#{name}_bucket"
+            value.each do |q, v|
+              next if q == "sum"
+              yield metric(bucket, labels(set.merge(le: q)), v)
+            end
+
+            l = labels(set)
+            yield metric("#{name}_sum", l, value["sum"])
+            yield metric("#{name}_count", l, value["+Inf"])
+          end
+
+          def vm_histogram(name, set, value)
+            bucket = "#{name}_bucket"
+            value.each do |q, v|
+              next if ["count", "sum"].include? q
+
+              yield metric(bucket, labels(set.merge(vmrange: q)), v)
+            end
+
+            l = labels(set)
+            yield metric("#{name}_sum", l, value["sum"])
+            yield metric("#{name}_count", l, value["count"])
+          end
+
+          def metric(name, labels, value)
+            format(METRIC_LINE, name, labels, value)
+          end
+
+          def labels(set)
+            return if set.empty?
+
+            strings = set.each_with_object([]) do |(key, value), memo|
+              memo << format(LABEL, key, escape(value, :label))
+            end
+
+            "{#{strings.join(SEPARATOR)}}"
+          end
+
+          def escape(string, format = :doc)
+            string.to_s.gsub(REGEX[format], REPLACE)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/prometheus/client/gauge.rb

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+
+require 'prometheus/client/metric'
+
+module Prometheus
+  module Client
+    # A Gauge is a metric that exposes merely an instantaneous value or some
+    # snapshot thereof.
+    class Gauge < Metric
+      def type
+        :gauge
+      end
+
+      # Sets the value for the given label set
+      def set(value, labels: {})
+        unless value.is_a?(Numeric)
+          raise ArgumentError, 'value must be a number'
+        end
+
+        @store.set(labels: label_set_for(labels), val: value)
+      end
+
+      def set_to_current_time(labels: {})
+        @store.set(labels: label_set_for(labels), val: Time.now.to_f)
+      end
+
+      # Increments Gauge value by 1 or adds the given value to the Gauge.
+      # (The value can be negative, resulting in a decrease of the Gauge.)
+      def increment(by: 1, labels: {})
+        label_set = label_set_for(labels)
+        @store.increment(labels: label_set, by: by)
+      end
+
+      # Decrements Gauge value by 1 or subtracts the given value from the Gauge.
+      # (The value can be negative, resulting in a increase of the Gauge.)
+      def decrement(by: 1, labels: {})
+        label_set = label_set_for(labels)
+        @store.increment(labels: label_set, by: -by)
+      end
+    end
+  end
+end

data/lib/prometheus/client/histogram.rb

@@ -0,0 +1,151 @@
+# encoding: UTF-8
+
+require 'prometheus/client/metric'
+
+module Prometheus
+  module Client
+    # A histogram samples observations (usually things like request durations
+    # or response sizes) and counts them in configurable buckets. It also
+    # provides a total count and sum of all observed values.
+    class Histogram < Metric
+      # DEFAULT_BUCKETS are the default Histogram buckets. The default buckets
+      # are tailored to broadly measure the response time (in seconds) of a
+      # network service. (From DefBuckets client_golang)
+      DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1,
+                         2.5, 5, 10].freeze
+
+      attr_reader :buckets
+
+      # Offer a way to manually specify buckets
+      def initialize(name,
+                     docstring:,
+                     labels: [],
+                     preset_labels: {},
+                     buckets: DEFAULT_BUCKETS,
+                     store_settings: {})
+        raise ArgumentError, 'Unsorted buckets, typo?' unless sorted?(buckets)
+
+        @buckets = buckets
+        super(name,
+              docstring: docstring,
+              labels: labels,
+              preset_labels: preset_labels,
+              store_settings: store_settings)
+      end
+
+      def self.linear_buckets(start:, width:, count:)
+        count.times.map { |idx| start.to_f + idx * width }
+      end
+
+      def self.exponential_buckets(start:, factor: 2, count:)
+        count.times.map { |idx| start.to_f * factor ** idx }
+      end
+
+      def with_labels(labels)
+        new_metric = self.class.new(name,
+                                    docstring: docstring,
+                                    labels: @labels,
+                                    preset_labels: preset_labels.merge(labels),
+                                    buckets: @buckets,
+                                    store_settings: @store_settings)
+
+        # The new metric needs to use the same store as the "main" declared one, otherwise
+        # any observations on that copy with the pre-set labels won't actually be exported.
+        new_metric.replace_internal_store(@store)
+
+        new_metric
+      end
+
+      def type
+        :histogram
+      end
+
+      # Records a given value. The recorded value is usually positive
+      # or zero. A negative value is accepted but prevents current
+      # versions of Prometheus from properly detecting counter resets
+      # in the sum of observations. See
+      # https://prometheus.io/docs/practices/histograms/#count-and-sum-of-observations
+      # for details.
+      def observe(value, labels: {})
+        bucket = buckets.find {|upper_limit| upper_limit >= value  }
+        bucket = "+Inf" if bucket.nil?
+
+        base_label_set = label_set_for(labels)
+
+        # This is basically faster than doing `.merge`
+        bucket_label_set = base_label_set.dup
+        bucket_label_set[:le] = bucket.to_s
+        sum_label_set = base_label_set.dup
+        sum_label_set[:le] = "sum"
+
+        @store.synchronize do
+          @store.increment(labels: bucket_label_set, by: 1)
+          @store.increment(labels: sum_label_set, by: value)
+        end
+      end
+
+      # Returns a hash with all the buckets plus +Inf (count) plus Sum for the given label set
+      def get(labels: {})
+        base_label_set = label_set_for(labels)
+
+        all_buckets = buckets + ["+Inf", "sum"]
+
+        @store.synchronize do
+          all_buckets.each_with_object({}) do |upper_limit, acc|
+            acc[upper_limit.to_s] = @store.get(labels: base_label_set.merge(le: upper_limit.to_s))
+          end.tap do |acc|
+            accumulate_buckets(acc)
+          end
+        end
+      end
+
+      # Returns all label sets with their values expressed as hashes with their buckets
+      def values
+        values = @store.all_values
+
+        result = values.each_with_object({}) do |(label_set, v), acc|
+          actual_label_set = label_set.reject{|l| l == :le }
+          acc[actual_label_set] ||= @buckets.map{|b| [b.to_s, 0.0]}.to_h
+          acc[actual_label_set][label_set[:le].to_s] = v
+        end
+
+        result.each do |(_label_set, v)|
+          accumulate_buckets(v)
+        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
+      def accumulate_buckets(h)
+        bucket_acc = 0
+        buckets.each do |upper_limit|
+          bucket_value = h[upper_limit.to_s]
+          h[upper_limit.to_s] += bucket_acc
+          bucket_acc += bucket_value
+        end
+
+        inf_value = h["+Inf"] || 0.0
+        h["+Inf"] = inf_value + bucket_acc
+      end
+
+      def reserved_labels
+        [:le]
+      end
+
+      def sorted?(bucket)
+        bucket.each_cons(2).all? { |i, j| i <= j }
+      end
+    end
+  end
+end

data/lib/prometheus/client/label_set_validator.rb

@@ -0,0 +1,80 @@
+# encoding: UTF-8
+
+module Prometheus
+  module Client
+    # LabelSetValidator ensures that all used label sets comply with the
+    # Prometheus specification.
+    class LabelSetValidator
+      BASE_RESERVED_LABELS = [:pid].freeze
+      LABEL_NAME_REGEX = /\A[a-zA-Z_][a-zA-Z0-9_]*\Z/
+
+      class LabelSetError < StandardError; end
+      class InvalidLabelSetError < LabelSetError; end
+      class InvalidLabelError < LabelSetError; end
+      class ReservedLabelError < LabelSetError; end
+
+      attr_reader :expected_labels, :reserved_labels
+
+      def initialize(expected_labels:, reserved_labels: [])
+        @expected_labels = expected_labels.sort
+        @reserved_labels = BASE_RESERVED_LABELS + reserved_labels
+      end
+
+      def validate_symbols!(labels)
+        unless labels.respond_to?(:all?)
+          raise InvalidLabelSetError, "#{labels} is not a valid label set"
+        end
+
+        labels.all? do |key, _|
+          validate_symbol(key)
+          validate_name(key)
+          validate_reserved_key(key)
+        end
+      end
+
+      def validate_labelset!(labelset)
+        begin
+          return labelset if keys_match?(labelset)
+        rescue ArgumentError
+          # If labelset contains keys that are a mixture of strings and symbols, this will
+          # raise when trying to sort them, but the error should be the same:
+          # InvalidLabelSetError
+        end
+
+        raise InvalidLabelSetError, "labels must have the same signature " \
+                                    "(keys given: #{labelset.keys} vs." \
+                                    " keys expected: #{expected_labels}"
+      end
+
+      private
+
+      def keys_match?(labelset)
+        labelset.keys.sort == expected_labels
+      end
+
+      def validate_symbol(key)
+        return true if key.is_a?(Symbol)
+
+        raise InvalidLabelError, "label #{key} is not a symbol"
+      end
+
+      def validate_name(key)
+        if key.to_s.start_with?('__')
+          raise ReservedLabelError, "label #{key} must not start with __"
+        end
+
+        unless key.to_s =~ LABEL_NAME_REGEX
+          raise InvalidLabelError, "label name must match /#{LABEL_NAME_REGEX}/"
+        end
+
+        true
+      end
+
+      def validate_reserved_key(key)
+        return true unless reserved_labels.include?(key)
+
+        raise ReservedLabelError, "#{key} is reserved"
+      end
+    end
+  end
+end

data/lib/prometheus/client/metric.rb

@@ -0,0 +1,120 @@
+# encoding: UTF-8
+
+require 'thread'
+require 'prometheus/client/label_set_validator'
+
+module Prometheus
+  module Client
+    # Metric
+    class Metric
+      attr_reader :name, :docstring, :labels, :preset_labels
+
+      def initialize(name,
+                     docstring:,
+                     labels: [],
+                     preset_labels: {},
+                     store_settings: {})
+
+        validate_name(name)
+        validate_docstring(docstring)
+        @validator = LabelSetValidator.new(expected_labels: labels,
+                                           reserved_labels: reserved_labels)
+        @validator.validate_symbols!(labels)
+        @validator.validate_symbols!(preset_labels)
+
+        @labels = labels
+        @store_settings = store_settings
+
+        @name = name
+        @docstring = docstring
+        @preset_labels = stringify_values(preset_labels)
+
+        @all_labels_preset = false
+        if preset_labels.keys.length == labels.length
+          @validator.validate_labelset!(preset_labels)
+          @all_labels_preset = true
+        end
+
+        @store = Prometheus::Client.config.data_store.for_metric(
+          name,
+          metric_type: type,
+          metric_settings: store_settings
+        )
+
+        # WARNING: Our internal store can be replaced later by `with_labels`
+        # Everything we do after this point needs to still work if @store gets replaced
+        init_label_set({}) if labels.empty?
+      end
+
+      protected def replace_internal_store(new_store)
+        @store = new_store
+      end
+
+
+      # Returns the value for the given label set
+      def get(labels: {})
+        label_set = label_set_for(labels)
+        @store.get(labels: label_set)
+      end
+
+      def with_labels(labels)
+        new_metric = self.class.new(name,
+                                     docstring: docstring,
+                                     labels: @labels,
+                                     preset_labels: preset_labels.merge(labels),
+                                     store_settings: @store_settings)
+
+        # The new metric needs to use the same store as the "main" declared one, otherwise
+        # any observations on that copy with the pre-set labels won't actually be exported.
+        new_metric.replace_internal_store(@store)
+
+        new_metric
+      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
+      end
+
+      private
+
+      def reserved_labels
+        []
+      end
+
+      def validate_name(name)
+        unless name.is_a?(Symbol)
+          raise ArgumentError, 'metric name must be a symbol'
+        end
+        unless name.to_s =~ /\A[a-zA-Z_:][a-zA-Z0-9_:]*\Z/
+          msg = 'metric name must match /[a-zA-Z_:][a-zA-Z0-9_:]*/'
+          raise ArgumentError, msg
+        end
+      end
+
+      def validate_docstring(docstring)
+        return true if docstring.respond_to?(:empty?) && !docstring.empty?
+
+        raise ArgumentError, 'docstring must be given'
+      end
+
+      def label_set_for(labels)
+        # We've already validated, and there's nothing to merge. Save some cycles
+        return preset_labels if @all_labels_preset && labels.empty?
+        labels = stringify_values(labels)
+        @validator.validate_labelset!(preset_labels.merge(labels))
+      end
+
+      def stringify_values(labels)
+        stringified = {}
+        labels.each { |k,v| stringified[k] = v.to_s }
+
+        stringified
+      end
+    end
+  end
+end