fast-prometheus 0.1.0

data/lib/fast/prometheus/histogram.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require_relative "metric"
+
+module Fast
+  module Prometheus
+    # Histogram samples observations and counts them in configurable buckets.
+    # Also provides total count and sum of all observed values.
+    #
+    # Storage: one slot per label series in the parent @store Hash. Each slot
+    # is a HistogramSlot holding sum (Float), count (Integer), and one Integer
+    # cell per boundary plus an overflow cell — stored NON-cumulatively.
+    class Histogram < Metric
+      DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10].freeze
+
+      # Small inner value object holding one series' data.
+      class HistogramSlot
+        attr_accessor :sum, :count
+        attr_reader :cells
+
+        def initialize(buckets:, sum: 0.0, count: 0)
+          @buckets = buckets
+          @sum = sum
+          @count = count
+          @cells = [0] * (buckets.size + 1)
+        end
+
+        # Cumulative bucket counts, ending with [Float::INFINITY, count].
+        def cumulative_buckets
+          cumulative = 0
+          result = @buckets.each_with_index.map do |boundary, i|
+            cumulative += @cells[i]
+            [boundary, cumulative]
+          end
+          cumulative += @cells.last # overflow cell
+          result << [Float::INFINITY, cumulative]
+        end
+      end
+
+      attr_reader :buckets
+
+      def initialize(name, docstring:, labels: [], preset_labels: {}, buckets: DEFAULT_BUCKETS, store: nil)
+        raise ArgumentError, "buckets must be a non-empty Array" unless buckets.is_a?(Array) && !buckets.empty?
+        raise ArgumentError, "buckets must contain only Numeric values" unless buckets.all? { |b| b.is_a?(Numeric) }
+        raise ArgumentError, "buckets must be strictly ascending" unless buckets.each_cons(2).all? { |a, b| a < b }
+
+        raise InvalidLabelName, "label :le is reserved" if labels.include?(:le)
+
+        @buckets = buckets
+        super(name, docstring: docstring, labels: labels, preset_labels: preset_labels, store: store)
+      end
+
+      def type
+        :histogram
+      end
+
+      # 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: {})
+        key = resolve(labels)
+        index = @buckets.bsearch_index { |boundary| boundary >= value } || @buckets.size
+
+        store.synchronize do
+          slot = store[key] ||= HistogramSlot.new(buckets: @buckets)
+
+          slot.sum += value
+          slot.count += 1
+          slot.cells[index] += 1
+        end
+      end
+
+      # Cumulative bucket counts for a specific series (delegates to slot).
+      def cumulative_buckets(labels: {})
+        store.synchronize { get(labels: labels)&.cumulative_buckets }
+      end
+
+      # Get the slot for a label set, or nil if no observations recorded.
+      def get(labels: {})
+        key = resolve(labels)
+        store.synchronize { store[key] }
+      end
+
+      # Reader for sum of a specific series.
+      def sum(labels: {})
+        store.synchronize { get(labels: labels)&.sum }
+      end
+
+      # Reader for count of a specific series.
+      def count(labels: {})
+        store.synchronize { get(labels: labels)&.count }
+      end
+
+      def self.linear_buckets(start:, width:, count:)
+        count.times.map { |i| start.to_f + i * width }
+      end
+
+      def self.exponential_buckets(start:, factor:, count:)
+        raise ArgumentError, "start must be > 0" unless start.positive?
+        raise ArgumentError, "factor must be > 1" unless factor > 1
+        raise ArgumentError, "count must be >= 1" unless count >= 1
+
+        count.times.map { |i| start.to_f * (factor**i) }
+      end
+
+      protected
+
+      def construction_options
+        { buckets: @buckets }
+      end
+    end
+  end
+end

data/lib/fast/prometheus/metric.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "store"
+
+module Fast
+  module Prometheus
+    # Metric is the abstract base class for all metric types.
+    #
+    # Every metric's per-series storage is a Store, guarded by its own lock.
+    # Metrics produced by #with_labels share their parent's Store (and thus
+    # its lock), so a mutation on a bound metric and a mutation on its parent
+    # are mutually exclusive. Safe to share across OS threads and fibers.
+    class Metric
+      METRIC_NAME = /\A[a-zA-Z_:][a-zA-Z0-9_:]*\z/
+      LABEL_NAME = /\A[a-zA-Z_][a-zA-Z0-9_]*\z/
+
+      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
+        @docstring = docstring
+        @label_names = 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)
+      end
+
+      attr_reader :name, :docstring, :label_names, :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: {})
+        key = resolve(labels)
+        store.synchronize { store[key] || 0.0 }
+      end
+
+      def type
+        raise NotImplementedError, "subclasses must implement #type"
+      end
+
+      def with_labels(**labels)
+        validate_label_keys(labels)
+        merged = @preset_labels.merge(labels.transform_values { |v| v.to_s.freeze })
+        self.class.new(
+          @name,
+          docstring: @docstring,
+          labels: @label_names,
+          preset_labels: merged,
+          store: @store,
+          **construction_options
+        )
+      end
+
+      def values
+        store.synchronize { store.to_h.transform_keys { |key| @label_names.zip(key).to_h } }
+      end
+
+      # Runs +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)
+      end
+
+      protected
+
+      attr_reader :store
+
+      # Subclasses override to forward their own configuration (e.g. buckets,
+      # schema) through #with_labels. See Histogram, NativeHistogram.
+      def construction_options
+        {}
+      end
+
+      def resolve(labels)
+        return @resolved_key if @resolved_key && labels.empty?
+
+        validate_label_keys(labels)
+
+        @label_names.map do |n|
+          if labels.key?(n)
+            labels[n].to_s
+          else
+            value = @preset_labels[n]
+            raise InvalidLabelSet, "missing labels: #{n.inspect}" unless value
+
+            value
+          end
+        end.freeze
+      end
+
+      private
+
+      def fully_bound?
+        @preset_labels.size == @label_names.size
+      end
+
+      def validate_metric_name(name)
+        return if name.to_s.match?(METRIC_NAME)
+
+        raise InvalidMetricName, "invalid metric name: #{name.inspect}"
+      end
+
+      def validate_docstring(docstring)
+        return if docstring.is_a?(String) && !docstring.empty?
+
+        raise ArgumentError, "docstring must be a non-empty string"
+      end
+
+      def validate_label_names(labels)
+        labels.each do |label|
+          name = label.to_s
+          raise InvalidLabelName, "label name must not start with __: #{label.inspect}" if name.start_with?("__")
+          raise InvalidLabelName, "invalid label name: #{label.inspect}" unless name.match?(LABEL_NAME)
+        end
+      end
+
+      def validate_preset_labels(labels, preset_labels)
+        preset_labels.each_key do |key|
+          raise InvalidLabelSet, "preset label not in declared labels: #{key.inspect}" unless labels.include?(key)
+        end
+      end
+
+      def validate_label_keys(labels)
+        labels.each_key do |key|
+          raise InvalidLabelSet, "unknown label name: #{key.inspect}" unless @label_names.include?(key)
+        end
+      end
+
+      def resolve_internal(merged)
+        @label_names.map { |n| merged.fetch(n) }.freeze
+      end
+    end
+  end
+end

data/lib/fast/prometheus/middleware/exporter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+require "protocol/http/middleware"
+require "fast/prometheus/exposition"
+
+module Fast
+  module Prometheus
+    module Middleware
+      # Protocol::HTTP middleware that serves metrics at a configurable path.
+      # Handles content negotiation (text vs protobuf) and gzip compression.
+      class Exporter < Protocol::HTTP::Middleware
+        def initialize(delegate, registry: Fast::Prometheus.registry, path: "/metrics")
+          super(delegate)
+          @registry = registry
+          @path = path
+        end
+
+        def call(request)
+          return serve_metrics(request) if request.method == "GET" && request.path == @path
+
+          super
+        end
+
+        private
+
+        def serve_metrics(request)
+          body, headers = Exposition.render(
+            @registry,
+            accept: request.headers["accept"],
+            accept_encoding: request.headers["accept-encoding"]
+          )
+
+          Protocol::HTTP::Response[200, Protocol::HTTP::Headers[headers], [body]]
+        end
+      end
+    end
+  end
+end

data/lib/fast/prometheus/middleware/instrumentation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+require "protocol/http/middleware"
+require "fast/prometheus/request_metrics"
+
+module Fast
+  module Prometheus
+    module Middleware
+      # Protocol::HTTP middleware that records RED metrics for every request.
+      # Drop one line into a Falcon app and get request counts and durations.
+      class Instrumentation < Protocol::HTTP::Middleware
+        def initialize(delegate, registry: Fast::Prometheus.registry, native: false, prefix: "http_server")
+          super(delegate)
+          @metrics = RequestMetrics.new(registry: registry, native: native, prefix: prefix)
+        end
+
+        def call(request)
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          response = super
+          @metrics.record(request.method, response.status.to_s, start)
+          response
+        rescue StandardError => e
+          begin
+            @metrics.record(request.method, "500", start)
+          rescue StandardError
+            nil
+          end
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/fast/prometheus/native_histogram.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require_relative "metric"
+
+module Fast
+  module Prometheus
+    # Native (sparse exponential) histogram.
+    #
+    # Covers the full float range with sparse base-2 exponential buckets.
+    # Bucket layout matches the Prometheus native histogram model exactly.
+    class NativeHistogram < Metric
+      # Inner value object holding one label series' histogram data.
+      # Per-series because downscaling is independent per series.
+      class Slot
+        attr_reader :zero_threshold
+        attr_accessor :schema, :sum, :count, :zero_count, :positive, :negative
+
+        def initialize(schema:, zero_threshold:)
+          @schema = schema
+          @zero_threshold = zero_threshold
+          @sum = 0.0
+          @count = 0
+          @zero_count = 0
+          @positive = {}
+          @negative = {}
+        end
+
+        # Sorted array of [index, count] pairs for positive side.
+        def positive_buckets
+          @positive.sort
+        end
+
+        # Sorted array of [index, count] pairs for negative side.
+        def negative_buckets
+          @negative.sort
+        end
+      end
+
+      # client_golang math.MaxInt32 convention for clamped ±Inf bucket index.
+      MAX_BUCKET_INDEX = (2**31) - 1
+
+      attr_reader :schema, :zero_threshold, :max_buckets
+
+      def initialize(name, docstring:, labels: [], preset_labels: {}, schema: 3, zero_threshold: 2.0**-128,
+                     max_buckets: 160, store: nil)
+        valid_schema = schema.is_a?(Integer) && (-4..8).include?(schema)
+        raise ArgumentError, "schema must be an Integer in -4..8" unless valid_schema
+
+        valid_zero_threshold = zero_threshold.is_a?(Float) && zero_threshold >= 0
+        raise ArgumentError, "zero_threshold must be a Float >= 0" unless valid_zero_threshold
+
+        valid_max_buckets = max_buckets.is_a?(Integer) && max_buckets.positive?
+        raise ArgumentError, "max_buckets must be an Integer > 0" unless valid_max_buckets
+
+        @schema = schema
+        @zero_threshold = zero_threshold
+        @max_buckets = max_buckets
+
+        super(name, docstring: docstring, labels: labels, preset_labels: preset_labels, store: store)
+      end
+
+      def type
+        :native_histogram
+      end
+
+      # Record an observation. Never raises — NaN/±Inf are handled gracefully.
+      def observe(value, labels: {})
+        v = value.to_f
+        key = resolve(labels)
+
+        store.synchronize do
+          slot = store[key] ||= Slot.new(schema: @schema, zero_threshold: @zero_threshold)
+
+          # Determine bucket placement BEFORE mutating count/sum (no partial mutation).
+          if v.nan?
+            # NaN: count/sum only, no bucket.
+            side = nil
+            idx = nil
+          elsif v.infinite?
+            # ±Inf: clamp to MAX_BUCKET_INDEX.
+            side = v.positive? ? :positive : :negative
+            idx = MAX_BUCKET_INDEX
+          elsif v.abs <= slot.zero_threshold
+            side = :zero
+            idx = nil
+          elsif v.positive?
+            side = :positive
+            idx = index_for(v, slot.schema)
+          else
+            side = :negative
+            idx = index_for(-v, slot.schema)
+          end
+
+          slot.sum += v
+          slot.count += 1
+
+          case side
+          when :zero
+            slot.zero_count += 1
+          when :positive
+            slot.positive[idx] = (slot.positive[idx] || 0) + 1
+          when :negative
+            slot.negative[idx] = (slot.negative[idx] || 0) + 1
+          end
+
+          downscale(slot) while slot.positive.size + slot.negative.size > @max_buckets && slot.schema > -4
+        end
+      end
+
+      # Get the slot for a label set, or nil if no observations recorded.
+      def get(labels: {})
+        key = resolve(labels)
+        store.synchronize { store[key] }
+      end
+
+      protected
+
+      def construction_options
+        { schema: @schema, zero_threshold: @zero_threshold, max_buckets: @max_buckets }
+      end
+
+      private
+
+      def index_for(value, schema)
+        factor = 2.0**schema
+        idx = (Math.log2(value) * factor).ceil
+        idx -= 1 while 2.0**((idx - 1) / factor) >= value
+        idx += 1 while 2.0**(idx / factor) < value
+        idx
+      end
+
+      def downscale(slot)
+        delta = 1
+        shift = 1 << delta
+        slot.positive = slot.positive.each_with_object({}) do |(idx, count), hash|
+          hash[-(-idx / shift)] = (hash[-(-idx / shift)] || 0) + count
+        end
+        slot.negative = slot.negative.each_with_object({}) do |(idx, count), hash|
+          hash[-(-idx / shift)] = (hash[-(-idx / shift)] || 0) + count
+        end
+        slot.schema -= delta
+      end
+    end
+  end
+end

data/lib/fast/prometheus/otlp/grpc_exporter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+require "async/grpc"
+require "async/http/endpoint"
+require "async/http/protocol"
+require "protocol/http"
+require_relative "mapper"
+require_relative "service_interface"
+
+module Fast
+  module Prometheus
+    module OTLP
+      # Pushes metrics over gRPC using socketry/async-grpc.
+      class GRPCExporter
+        SERVICE_NAME = "opentelemetry.proto.collector.metrics.v1.MetricsService"
+        private_constant :SERVICE_NAME
+
+        def initialize(endpoint:, registry: Fast::Prometheus.registry, resource_attributes: {}, headers: {})
+          @http_endpoint = Async::HTTP::Endpoint.parse(endpoint, protocol: Async::HTTP::Protocol::HTTP2)
+          @registry = registry
+          @mapper = Mapper.new(resource_attributes: resource_attributes)
+          @http_client = Async::HTTP::Client.new(@http_endpoint)
+          grpc_headers = Protocol::HTTP::Headers[headers]
+          @grpc_client = Async::GRPC::Client.new(@http_client, headers: grpc_headers)
+          @stub = @grpc_client.stub(MetricsServiceInterface, SERVICE_NAME)
+        end
+
+        def export(snapshot = @registry.collect)
+          @stub.export(@mapper.request(snapshot))
+        end
+
+        def close
+          @http_client.close
+        end
+      end
+    end
+  end
+end

data/lib/fast/prometheus/otlp/http_exporter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+require "async/http/internet"
+require_relative "mapper"
+
+module Fast
+  module Prometheus
+    module OTLP
+      # Exports metrics over HTTP to an OTLP receiver (e.g. Prometheus --web.enable-otlp-receiver).
+      class HTTPExporter
+        def initialize(endpoint:, registry: Fast::Prometheus.registry, resource_attributes: {}, headers: {})
+          @registry = registry
+          @url = "#{endpoint}/v1/metrics"
+          @headers = [["content-type", "application/x-protobuf"]].concat(
+            headers.map { |k, v| [k.to_s, v.to_s] }
+          ).tap do |a|
+            a.freeze
+            a.each(&:freeze)
+          end
+          @mapper = Mapper.new(resource_attributes: resource_attributes)
+          @internet = Async::HTTP::Internet.new
+        end
+
+        # Export a snapshot (or collect one from the registry) via HTTP POST.
+        # Raises Error on non-2xx responses.
+        def export(snapshot = @registry.collect)
+          request = @mapper.request(snapshot)
+
+          @internet.post(@url, @headers, request.to_proto) do |response|
+            body = response.read
+            raise Error, "OTLP export failed: #{response.status} #{body}" unless (200..299).cover?(response.status)
+          end
+        end
+
+        # Close the underlying HTTP client.
+        def close
+          @internet.close
+        end
+      end
+    end
+  end
+end