fast-prometheus 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf50aa0854cf98fd362294bd64ac2f07d04526428b6aa595c50c1058ffc82664
-  data.tar.gz: 66b21fc919d3913bdda5ae6b1aff7b661eb850981a43f54f5928d67aa0dbf16e
+  metadata.gz: d60578f0bebf141e385a3313c32792c5310dd048a242e8f7b901585b71ab43cb
+  data.tar.gz: cd38790e53ff5680b72e7773b79226fbb25768bf03e4eeeba14fccb280acee6d
 SHA512:
-  metadata.gz: cb355b90d7dd5dcc885ff0181d87611ef6c39120f613053ed9a95e15988cf04b33959c3289bec698e8c664720a85a567729c8547ad53c427aa88214ba0143868
-  data.tar.gz: 379b37ebbccda56a8c3c7975351f709e138c4928be30ff3a8ccdac991164285db35fe1ce0758630506e36bb68199a311273de47d477b9578dd643ab2a8bc0da7
+  metadata.gz: efb05ec4182f3564031b9997bc2ffe840a9846ac0d652a29d6d1f118188de58d6156c49e4db703a8ca65305041bd758406b6bfe56728d767c9850f44e9382d77
+  data.tar.gz: 1063c21987bc816e1e41821e21ca831a8576c69d07c823fc2da1488c5800712ac75aa4360bf69cf04cb0b0c1af708a05468b8ca9b17aec1e31e94e2bdeeb2186

data/CHANGELOG.md

@@ -7,6 +7,58 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-09-15
+
+### Added
+
+- `Registry#exist?(name)` — true iff a metric is registered under `name`.
+- `Metric#init_label_set(labels)` is now public: it resolves `labels` like any
+  mutator and creates that series at the type's zero value under the store
+  lock, only if it's absent — it never resets a live series.
+- Every metric now seeds a zero-valued series at construction when it's fully
+  bound (no declared labels, or `preset_labels:` covers every declared
+  label); a fully-bound `with_labels` child seeds its own series the same
+  way. A seeded series shows up in `values`, `Registry#collect`, and text/
+  protobuf exposition at zero — for example a freshly registered counter now
+  renders `requests_total 0.0` instead of being absent from scrapes until
+  first incremented. Partially-bound metrics and zero-valued
+  `increment`/`decrement` still seed nothing; `get` still never creates a
+  series.
+- `Gauge#set_to_current_time(labels: {})` — `set(Time.now.to_f, labels:
+  labels)`.
+- `Metric#snapshot_values` — every series' value in its frozen snapshot shape
+  (`HistogramValue`, `SummaryValue`, `NativeHistogramValue`, or the
+  already-frozen `Float` for `Counter`/`Gauge`), keyed by label hash, built
+  under the store lock.
+
+### Changed
+
+- **Breaking:** `Metric` names may now be given as a `String` or a `Symbol`
+  and are normalized to a `Symbol` on construction; `Metric#name` always
+  returns a `Symbol` where it previously echoed back whatever was passed in.
+  `Registry#unregister`, `#get`, `#exist?`, and `#fetch_or_register` accept
+  either form and symbolize it before lookup; `DuplicateMetric` now fires
+  across forms (registering `"requests_total"` after `:requests_total` is
+  already registered raises).
+- **Breaking:** `Metric#label_names` is renamed to `Metric#labels`; the old
+  name no longer exists (no alias). `MetricSnapshot#label_names` is
+  unaffected.
+- **Breaking:** `Histogram#get`/`#values` and `Summary#get`/`#values` now
+  return prometheus-client-shaped hashes instead of the internal
+  `HistogramSlot`/`Summary::Value` storage objects. `Histogram#get` returns a
+  fresh `Hash` keyed by each bucket boundary's `to_s` (ascending), then
+  `"+Inf"`, then `"sum"`, with cumulative `Integer` bucket counts and a
+  `Float` sum; `Summary#get` returns `{ "count" => Integer, "sum" => Float }`.
+  `Histogram#cumulative_buckets`, `#sum`, and `#count` now return zero-valued
+  results for an unobserved series instead of `nil`. `NativeHistogram#get`/
+  `#values` now return the frozen `NativeHistogramValue` snapshot type
+  (previously the internal `NativeHistogram::Slot`), including a zero-valued
+  value for an unobserved series. All of these are fresh copies per call;
+  mutating a returned `Hash` no longer affects the metric.
+- `Fast::Prometheus.registry=` now assigns under the same lock the reader
+  uses, closing a race between a writer and a concurrent reader/memoizing
+  first read.
+
 ## [0.1.0] - 2026-09-11
 
 ### Added

data/lib/fast/prometheus/gauge.rb

@@ -17,6 +17,10 @@ module Fast
         store.synchronize { store[key] = value.to_f }
       end
 
+      def set_to_current_time(labels: {})
+        set(Time.now.to_f, labels: labels)
+      end
+
       def increment(by: 1, labels: {})
         raise ArgumentError, "by must be a numeric" unless by.is_a?(Numeric)
         return if by.zero?

data/lib/fast/prometheus/histogram.rb

@@ -69,25 +69,35 @@ module Fast
         end
       end
 
-      # Cumulative bucket counts for a specific series (delegates to slot).
+      # Cumulative bucket counts for a specific series, ending with
+      # [Float::INFINITY, count]. Zero-valued pairs for an unobserved series.
       def cumulative_buckets(labels: {})
-        store.synchronize { get(labels: labels)&.cumulative_buckets }
+        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.
+      # 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: {})
         key = resolve(labels)
-        store.synchronize { store[key] }
+        store.synchronize { hash_shape(slot_or_zero(key)) }
+      end
+
+      def values
+        series_map { |slot| hash_shape(slot) }
       end
 
-      # Reader for sum of a specific series.
+      # Reader for sum of a specific series; 0.0 when unobserved.
       def sum(labels: {})
-        store.synchronize { get(labels: labels)&.sum }
+        key = resolve(labels)
+        store.synchronize { slot_or_zero(key).sum }
       end
 
-      # Reader for count of a specific series.
+      # Reader for count of a specific series; 0 when unobserved.
       def count(labels: {})
-        store.synchronize { get(labels: labels)&.count }
+        key = resolve(labels)
+        store.synchronize { slot_or_zero(key).count }
       end
 
       def self.linear_buckets(start:, width:, count:)
@@ -107,6 +117,32 @@ 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(
+          sum: slot.sum,
+          count: slot.count,
+          cumulative_buckets: slot.cumulative_buckets.map { |pair| pair.dup.freeze }.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

@@ -21,27 +21,35 @@ module Fast
         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.
+      # 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: {})
         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 = {})
+        seed(resolve(labels))
+      end
+
       def type
         raise NotImplementedError, "subclasses must implement #type"
       end
@@ -52,7 +60,7 @@ module Fast
         self.class.new(
           @name,
           docstring: @docstring,
-          labels: @label_names,
+          labels: @labels,
           preset_labels: merged,
           store: @store,
           **construction_options
@@ -60,7 +68,15 @@ module Fast
       end
 
       def values
-        store.synchronize { store.to_h.transform_keys { |key| @label_names.zip(key).to_h } }
+        snapshot_values
+      end
+
+      # Every series' value in its frozen snapshot shape (see HistogramValue,
+      # SummaryValue, NativeHistogramValue; Counter/Gauge use the already-
+      # frozen Float), keyed by label hash, built under the store lock. The
+      # seam MetricSnapshot uses to build a consistent view of every series.
+      def snapshot_values
+        series_map { |slot| snapshot_value(slot) }
       end
 
       # Runs +block+ exclusively with respect to every other mutation or read
@@ -86,7 +102,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 +116,35 @@ 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 +block+, keyed by label hash, under the lock.
+      def series_map(&block)
+        store.synchronize { store.to_h.transform_keys { |key| @labels.zip(key).to_h }.transform_values(&block) }
+      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 +175,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

@@ -107,10 +107,15 @@ module Fast
         end
       end
 
-      # Get the slot for a label set, or nil if no observations recorded.
+      # A frozen NativeHistogramValue for a label set; zero-valued at this
+      # metric's schema/zero_threshold for an unobserved series.
       def get(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,22 @@ module Fast
 
       private
 
+      def zero_value
+        Slot.new(schema: @schema, zero_threshold: @zero_threshold)
+      end
+
+      def snapshot_value(slot)
+        NativeHistogramValue.new(
+          schema: slot.schema,
+          zero_threshold: slot.zero_threshold,
+          zero_count: slot.zero_count,
+          sum: slot.sum,
+          count: slot.count,
+          positive_buckets: slot.positive_buckets.map { |pair| pair.dup.freeze }.freeze,
+          negative_buckets: slot.negative_buckets.map { |pair| pair.dup.freeze }.freeze
+        ).freeze
+      end
+
       def index_for(value, schema)
         factor = 2.0**schema
         idx = (Math.log2(value) * factor).ceil

data/lib/fast/prometheus/registry.rb

@@ -28,14 +28,19 @@ module Fast
         end
       end
 
-      # Remove a metric by name.
+      # Remove a metric by name (String or Symbol).
       def unregister(name)
-        @lock.synchronize { @by_name.delete(name) }
+        @lock.synchronize { @by_name.delete(normalize(name)) }
       end
 
-      # Look up a metric by name, or nil.
+      # Look up a metric by name (String or Symbol), or nil.
       def get(name)
-        @lock.synchronize { @by_name[name] }
+        @lock.synchronize { @by_name[normalize(name)] }
+      end
+
+      # True iff a metric is registered under +name+ (String or Symbol).
+      def exist?(name)
+        @lock.synchronize { @by_name.key?(normalize(name)) }
       end
 
       # Atomic fetch-or-register: returns the metric already registered under
@@ -45,15 +50,16 @@ module Fast
       # DuplicateMetric. Raises ArgumentError if the block's metric is not
       # named +name+.
       def fetch_or_register(name)
+        key = normalize(name)
         @lock.synchronize do
-          next @by_name[name] if @by_name.key?(name)
+          next @by_name[key] if @by_name.key?(key)
 
           metric = yield
-          unless metric.name == name
-            raise ArgumentError, "fetch_or_register(#{name.inspect}) block built #{metric.name.inspect}"
+          unless metric.name == key
+            raise ArgumentError, "fetch_or_register(#{key.inspect}) block built #{metric.name.inspect}"
           end
 
-          @by_name[name] = metric
+          @by_name[key] = metric
         end
       end
 
@@ -93,6 +99,12 @@ module Fast
       def collect
         Snapshot.of(metrics)
       end
+
+      private
+
+      def normalize(name)
+        name.to_s.to_sym
+      end
     end
 
     @registry_lock = Mutex.new
@@ -105,7 +117,7 @@ module Fast
     end
 
     def self.registry=(registry)
-      @registry = registry
+      @registry_lock.synchronize { @registry = registry }
     end
   end
 end

data/lib/fast/prometheus/snapshot.rb

@@ -24,43 +24,15 @@ module Fast
             metric.name,
             metric.docstring,
             metric.type,
-            metric.label_names.dup.freeze,
+            metric.labels.dup.freeze,
             build_series(metric).freeze
           )
         end
       end
 
       def self.build_series(metric)
-        metric.values.map do |labels, value|
-          Series.new(
-            labels: labels.dup.freeze,
-            value: build_value(metric.type, value)
-          )
-        end
-      end
-
-      private_class_method def self.build_value(type, value)
-        case type
-        when :counter, :gauge
-          value
-        when :histogram
-          HistogramValue.new(
-            sum: value.sum,
-            count: value.count,
-            cumulative_buckets: value.cumulative_buckets.map { |pair| pair.dup.freeze }.freeze
-          )
-        when :summary
-          SummaryValue.new(sum: value.sum, count: value.count)
-        when :native_histogram
-          NativeHistogramValue.new(
-            schema: value.schema,
-            zero_threshold: value.zero_threshold,
-            zero_count: value.zero_count,
-            sum: value.sum,
-            count: value.count,
-            positive_buckets: value.positive_buckets.map { |pair| pair.dup.freeze }.freeze,
-            negative_buckets: value.negative_buckets.map { |pair| pair.dup.freeze }.freeze
-          )
+        metric.snapshot_values.map do |labels, value|
+          Series.new(labels: labels.dup.freeze, value: value)
         end
       end
     end

data/lib/fast/prometheus/summary.rb

@@ -30,9 +30,14 @@ module Fast
         end
       end
 
+      # {"count" => Integer, "sum" => Float}. Zero-valued for an unobserved series.
       def get(labels: {})
         key = resolve(labels)
-        store.synchronize { store[key] }
+        store.synchronize { hash_shape(store[key] || zero_value) }
+      end
+
+      def values
+        series_map { |slot| hash_shape(slot) }
       end
 
       protected
@@ -45,6 +50,20 @@ module Fast
 
         super
       end
+
+      private
+
+      def zero_value
+        Value.new
+      end
+
+      def snapshot_value(slot)
+        SummaryValue.new(sum: slot.sum, count: slot.count)
+      end
+
+      def hash_shape(slot)
+        { "count" => slot.count, "sum" => slot.sum }
+      end
     end
   end
 end

data/lib/fast/prometheus/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Prometheus
-    VERSION = "0.1.0"
+    VERSION = "0.2.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-prometheus
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Eric Jacobs