fast-prometheus 0.1.0 → 0.3.0

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

@@ -7,6 +7,10 @@ module Fast
     module Formats
       # Prometheus text exposition format 0.0.4.
       # Consumes Snapshot value objects; never reads live metrics.
+      #
+      # Every piece is appended straight to the output buffer: no line, label
+      # or name is built as its own String first, so a render allocates one
+      # String per sample (the value's to_s) and nothing per label.
       module Text
         CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
 
@@ -20,69 +24,75 @@ module Fast
           snapshot.metrics.each_with_object(String.new) do |metric, output|
             next if metric.type == :native_histogram
 
-            output << "# HELP #{metric.name} #{escape_doc(metric.docstring)}\n"
-            output << "# TYPE #{metric.name} #{metric.type}\n"
+            name = metric.name.name
+            output << "# HELP " << name << " " << escape_doc(metric.docstring) << "\n"
+            output << "# TYPE " << name << " " << metric.type.name << "\n"
 
-            metric.series.each do |series|
-              render_series(output, metric.type, metric.name, series)
+            names = metric.label_names
+            metric.series.each_pair do |values, value|
+              render_series(output, metric.type, name, names, values, value)
             end
           end
         end
 
-        private_class_method def self.render_series(output, type, name, series)
+        private_class_method def self.render_series(output, type, name, names, values, value)
           case type
           when :counter, :gauge
-            metric_line(output, name, series.labels, series.value)
+            sample(output, name, nil, names, values, value)
           when :histogram
-            histogram_lines(output, name, series.labels, series.value)
+            histogram_lines(output, name, names, values, value)
           when :summary
-            summary_lines(output, name, series.labels, series.value)
+            sample(output, name, "_sum", names, values, value.sum)
+            sample(output, name, "_count", names, values, value.count)
           end
         end
 
-        private_class_method def self.escape_doc(string)
-          return string unless DOC_ESCAPE.match?(string)
-
-          string.gsub(DOC_ESCAPE, DOC_REPLACE)
+        # One sample line: name, optional suffix, labels (names and values
+        # side by side, plus an le label carrying +upper_bound+ for histogram
+        # buckets), value.
+        private_class_method def self.sample(output, name, suffix, names, values, value, upper_bound = nil)
+          output << name
+          output << suffix if suffix
+          append_labels(output, names, values, upper_bound)
+          output << " " << value.to_s << "\n"
         end
 
-        private_class_method def self.escape_label(string)
-          string = string.to_s
-          return string unless LABEL_ESCAPE.match?(string)
+        private_class_method def self.append_labels(output, names, values, upper_bound)
+          return if names.empty? && upper_bound.nil?
 
-          string.gsub(LABEL_ESCAPE, LABEL_REPLACE)
+          output << "{"
+          names.each_index { |i| output << label_name(names[i]) << "=\"" << escape_label(values[i]) << "\"," }
+          output << "le=\"" << upper_bound << "\"," if upper_bound
+          output.chop!
+          output << "}"
         end
 
-        private_class_method def self.format_labels(labels)
-          return "" if labels.empty?
-
-          output = String.new("{")
-          labels.each do |key, value|
-            output << "#{key}=\"#{escape_label(value)}\""
-            output << ","
+        private_class_method def self.histogram_lines(output, name, names, values, value)
+          value.cumulative_buckets.each do |boundary, count|
+            sample(output, name, "_bucket", names, values, count, boundary.infinite? ? "+Inf" : boundary.to_s)
           end
-          output.chop!
-          output << "}"
-          output
+
+          sample(output, name, "_sum", names, values, value.sum)
+          sample(output, name, "_count", names, values, value.count)
         end
 
-        private_class_method def self.metric_line(output, name, labels, value)
-          output << "#{name}#{format_labels(labels)} #{value}\n"
+        # Label names are Symbols (Symbol#name is frozen and shared); a
+        # String name is appended as is.
+        private_class_method def self.label_name(key)
+          key.is_a?(Symbol) ? key.name : key
         end
 
-        private_class_method def self.histogram_lines(output, name, labels, value)
-          value.cumulative_buckets.each do |boundary, count|
-            le = boundary.infinite? ? "+Inf" : boundary.to_s
-            metric_line(output, "#{name}_bucket", labels.merge("le" => le), count)
-          end
+        private_class_method def self.escape_doc(string)
+          return string unless DOC_ESCAPE.match?(string)
 
-          metric_line(output, "#{name}_sum", labels, value.sum)
-          metric_line(output, "#{name}_count", labels, value.count)
+          string.gsub(DOC_ESCAPE, DOC_REPLACE)
         end
 
-        private_class_method def self.summary_lines(output, name, labels, value)
-          metric_line(output, "#{name}_sum", labels, value.sum)
-          metric_line(output, "#{name}_count", labels, value.count)
+        private_class_method def self.escape_label(string)
+          string = string.to_s
+          return string unless LABEL_ESCAPE.match?(string)
+
+          string.gsub(LABEL_ESCAPE, LABEL_REPLACE)
         end
       end
     end

data/lib/fast/prometheus/gauge.rb

@@ -10,14 +10,18 @@ module Fast
         :gauge
       end
 
-      def set(value, labels: {})
+      def set(value, labels: NO_LABELS)
         raise ArgumentError, "value must be a numeric" unless value.is_a?(Numeric)
 
         key = resolve(labels)
         store.synchronize { store[key] = value.to_f }
       end
 
-      def increment(by: 1, labels: {})
+      def set_to_current_time(labels: NO_LABELS)
+        set(Time.now.to_f, labels: labels)
+      end
+
+      def increment(by: 1, labels: NO_LABELS)
         raise ArgumentError, "by must be a numeric" unless by.is_a?(Numeric)
         return if by.zero?
 
@@ -25,7 +29,7 @@ module Fast
         store.synchronize { store[key] = (store[key] || 0.0) + by.to_f }
       end
 
-      def decrement(by: 1, labels: {})
+      def decrement(by: 1, labels: NO_LABELS)
         raise ArgumentError, "by must be a numeric" unless by.is_a?(Numeric)
         return if by.zero?
 

data/lib/fast/prometheus/histogram.rb

@@ -25,15 +25,19 @@ module Fast
           @cells = [0] * (buckets.size + 1)
         end
 
-        # Cumulative bucket counts, ending with [Float::INFINITY, count].
+        # Cumulative bucket counts as frozen [boundary, count] pairs, ending
+        # with [Float::INFINITY, count]. Frozen on the way out so a snapshot
+        # can hold it as is.
         def cumulative_buckets
           cumulative = 0
-          result = @buckets.each_with_index.map do |boundary, i|
+          result = Array.new(@buckets.size + 1)
+          @buckets.each_index do |i|
             cumulative += @cells[i]
-            [boundary, cumulative]
+            result[i] = [@buckets[i], cumulative].freeze
           end
           cumulative += @cells.last # overflow cell
-          result << [Float::INFINITY, cumulative]
+          result[@buckets.size] = [Float::INFINITY, cumulative].freeze
+          result.freeze
         end
       end
 
@@ -56,7 +60,7 @@ module Fast
 
       # Record an observation. Finds the first boundary >= value (inclusive le)
       # using bsearch_index. Values above the last boundary go to the overflow cell.
-      def observe(value, labels: {})
+      def observe(value, labels: NO_LABELS)
         key = resolve(labels)
         index = @buckets.bsearch_index { |boundary| boundary >= value } || @buckets.size
 
@@ -69,25 +73,35 @@ module Fast
         end
       end
 
-      # Cumulative bucket counts for a specific series (delegates to slot).
-      def cumulative_buckets(labels: {})
-        store.synchronize { get(labels: labels)&.cumulative_buckets }
+      # Cumulative bucket counts for a specific series, ending with
+      # [Float::INFINITY, count]. Zero-valued pairs for an unobserved series.
+      def cumulative_buckets(labels: NO_LABELS)
+        key = resolve(labels)
+        store.synchronize { slot_or_zero(key).cumulative_buckets }
       end
 
-      # Get the slot for a label set, or nil if no observations recorded.
-      def get(labels: {})
+      # Prometheus-client-shaped Hash: each bucket boundary's to_s => cumulative
+      # count, then "+Inf" => cumulative count, then "sum" => Float sum. A
+      # fresh Hash per call; zero-valued for an unobserved series.
+      def get(labels: NO_LABELS)
         key = resolve(labels)
-        store.synchronize { store[key] }
+        store.synchronize { hash_shape(slot_or_zero(key)) }
       end
 
-      # Reader for sum of a specific series.
-      def sum(labels: {})
-        store.synchronize { get(labels: labels)&.sum }
+      def values
+        series_map { |slot| hash_shape(slot) }
       end
 
-      # Reader for count of a specific series.
-      def count(labels: {})
-        store.synchronize { get(labels: labels)&.count }
+      # Reader for sum of a specific series; 0.0 when unobserved.
+      def sum(labels: NO_LABELS)
+        key = resolve(labels)
+        store.synchronize { slot_or_zero(key).sum }
+      end
+
+      # Reader for count of a specific series; 0 when unobserved.
+      def count(labels: NO_LABELS)
+        key = resolve(labels)
+        store.synchronize { slot_or_zero(key).count }
       end
 
       def self.linear_buckets(start:, width:, count:)
@@ -107,6 +121,28 @@ module Fast
       def construction_options
         { buckets: @buckets }
       end
+
+      private
+
+      def zero_value
+        HistogramSlot.new(buckets: @buckets)
+      end
+
+      def slot_or_zero(key)
+        store[key] || zero_value
+      end
+
+      def snapshot_value(slot)
+        HistogramValue.new(slot.sum, slot.count, slot.cumulative_buckets).freeze
+      end
+
+      def hash_shape(slot)
+        pairs = slot.cumulative_buckets
+        hash = pairs[0..-2].to_h { |boundary, count| [boundary.to_s, count] }
+        hash["+Inf"] = pairs.last.last
+        hash["sum"] = slot.sum
+        hash
+      end
     end
   end
 end

data/lib/fast/prometheus/metric.rb

@@ -15,33 +15,44 @@ module Fast
       METRIC_NAME = /\A[a-zA-Z_:][a-zA-Z0-9_:]*\z/
       LABEL_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
 
+      # The default label set, shared so an unlabeled call allocates nothing.
+      NO_LABELS = {}.freeze
+
       def initialize(name, docstring:, labels: [], preset_labels: {}, store: nil)
         validate_metric_name(name)
         validate_docstring(docstring)
         validate_label_names(labels)
         validate_preset_labels(labels, preset_labels)
 
-        @name = name
+        @name = name.to_s.to_sym
         @docstring = docstring
-        @label_names = labels
+        @labels = labels
         @preset_labels = preset_labels.transform_values { |v| v.to_s.freeze }
         @store = store || Store.new
 
         return unless fully_bound?
 
         @resolved_key = resolve_internal(@preset_labels)
+        seed(@resolved_key)
       end
 
-      attr_reader :name, :docstring, :label_names, :preset_labels
+      attr_reader :name, :docstring, :labels, :preset_labels
 
-      # Returns the current value for the given label set.
-      # Scalar types (Counter, Gauge) return 0.0 for unobserved series.
-      # Slot-based types (Histogram, Summary, NativeHistogram) override to return nil.
-      def get(labels: {})
+      # Returns the current value for the given label set. Scalar types
+      # (Counter, Gauge) return 0.0 for unobserved series. Histogram, Summary,
+      # and NativeHistogram override this with their own zero-valued shapes.
+      def get(labels: NO_LABELS)
         key = resolve(labels)
         store.synchronize { store[key] || 0.0 }
       end
 
+      # Creates the series for +labels+ at its zero value if absent. Never
+      # resets a series that already exists. Raises InvalidLabelSet on an
+      # unknown or incomplete label set, same as any mutator.
+      def init_label_set(labels = NO_LABELS)
+        seed(resolve(labels))
+      end
+
       def type
         raise NotImplementedError, "subclasses must implement #type"
       end
@@ -52,7 +63,7 @@ module Fast
         self.class.new(
           @name,
           docstring: @docstring,
-          labels: @label_names,
+          labels: @labels,
           preset_labels: merged,
           store: @store,
           **construction_options
@@ -60,15 +71,25 @@ module Fast
       end
 
       def values
-        store.synchronize { store.to_h.transform_keys { |key| @label_names.zip(key).to_h } }
+        series_map { |slot| snapshot_value(slot) }
+      end
+
+      # Every series' value in its frozen snapshot shape (see HistogramValue,
+      # SummaryValue, NativeHistogramValue; Counter/Gauge use the already-
+      # frozen Float), keyed by the series' label values in #labels order,
+      # the store's own key. The store is copied and its slots frozen under
+      # the lock, so this is a consistent view of every series at one
+      # instant that costs one Hash. The seam MetricSnapshot uses.
+      def snapshot_values
+        store.synchronize { store.to_h.transform_values! { |slot| snapshot_value(slot) } }
       end
 
-      # Runs +block+ exclusively with respect to every other mutation or read
+      # Runs the block exclusively with respect to every other mutation or read
       # of this metric's store (including on metrics sharing it via
       # #with_labels). Reentrant on the same thread. This is the seam
       # MetricSnapshot uses to build a consistent snapshot of every series.
-      def synchronize(&block)
-        store.synchronize(&block)
+      def synchronize
+        store.synchronize { yield } # rubocop:disable Style/ExplicitBlockArgument
       end
 
       protected
@@ -86,7 +107,7 @@ module Fast
 
         validate_label_keys(labels)
 
-        @label_names.map do |n|
+        @labels.map do |n|
           if labels.key?(n)
             labels[n].to_s
           else
@@ -100,8 +121,47 @@ module Fast
 
       private
 
+      # Zero value for a fresh series. Counter/Gauge share this Float
+      # default; Histogram, Summary, and NativeHistogram override it with
+      # their own empty slot.
+      def zero_value
+        0.0
+      end
+
+      # Turns one slot into its frozen snapshot value. Counter/Gauge slots
+      # are already-frozen Floats; Histogram, Summary, and NativeHistogram
+      # override this to build their own snapshot value type.
+      def snapshot_value(slot)
+        slot
+      end
+
+      # Shared shape behind #values and #snapshot_values: every series'
+      # storage transformed by the block, keyed by a fresh frozen label hash,
+      # under the lock. yield, not &block: a captured block is a Proc
+      # allocation on every call.
+      def series_map
+        store.synchronize do
+          store.to_h.transform_keys { |key| label_hash(key) }.transform_values { |slot| yield slot } # rubocop:disable Style/ExplicitBlockArgument
+        end
+      end
+
+      # {name => value} for a resolved key, built without the per-pair Arrays
+      # Array#zip would make (or the iterator object each_with_index would).
+      def label_hash(key)
+        hash = {}
+        @labels.each_index { |i| hash[@labels[i]] = key[i] }
+        hash.freeze
+      end
+
+      # Creates the series at +key+ at its zero value if absent. Never resets
+      # a series that already exists. Shared by #initialize (auto-seeding a
+      # fully-bound metric) and #init_label_set.
+      def seed(key)
+        store.synchronize { store[key] ||= zero_value }
+      end
+
       def fully_bound?
-        @preset_labels.size == @label_names.size
+        @preset_labels.size == @labels.size
       end
 
       def validate_metric_name(name)
@@ -132,12 +192,12 @@ module Fast
 
       def validate_label_keys(labels)
         labels.each_key do |key|
-          raise InvalidLabelSet, "unknown label name: #{key.inspect}" unless @label_names.include?(key)
+          raise InvalidLabelSet, "unknown label name: #{key.inspect}" unless @labels.include?(key)
         end
       end
 
       def resolve_internal(merged)
-        @label_names.map { |n| merged.fetch(n) }.freeze
+        @labels.map { |n| merged.fetch(n) }.freeze
       end
     end
   end

data/lib/fast/prometheus/native_histogram.rb

@@ -25,14 +25,14 @@ module Fast
           @negative = {}
         end
 
-        # Sorted array of [index, count] pairs for positive side.
+        # Sorted frozen [index, count] pairs for the positive side.
         def positive_buckets
-          @positive.sort
+          @positive.sort.each(&:freeze).freeze
         end
 
-        # Sorted array of [index, count] pairs for negative side.
+        # Sorted frozen [index, count] pairs for the negative side.
         def negative_buckets
-          @negative.sort
+          @negative.sort.each(&:freeze).freeze
         end
       end
 
@@ -64,7 +64,7 @@ module Fast
       end
 
       # Record an observation. Never raises — NaN/±Inf are handled gracefully.
-      def observe(value, labels: {})
+      def observe(value, labels: NO_LABELS)
         v = value.to_f
         key = resolve(labels)
 
@@ -107,10 +107,15 @@ module Fast
         end
       end
 
-      # Get the slot for a label set, or nil if no observations recorded.
-      def get(labels: {})
+      # A frozen NativeHistogramValue for a label set; zero-valued at this
+      # metric's schema/zero_threshold for an unobserved series.
+      def get(labels: NO_LABELS)
         key = resolve(labels)
-        store.synchronize { store[key] }
+        store.synchronize { snapshot_value(store[key] || zero_value) }
+      end
+
+      def values
+        series_map { |slot| snapshot_value(slot) }
       end
 
       protected
@@ -121,6 +126,15 @@ module Fast
 
       private
 
+      def zero_value
+        Slot.new(schema: @schema, zero_threshold: @zero_threshold)
+      end
+
+      def snapshot_value(slot)
+        NativeHistogramValue.new(slot.schema, slot.zero_threshold, slot.zero_count, slot.sum, slot.count,
+                                 slot.positive_buckets, slot.negative_buckets).freeze
+      end
+
       def index_for(value, schema)
         factor = 2.0**schema
         idx = (Math.log2(value) * factor).ceil