fast-prometheus 0.3.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25cba069a74bd1f00499ff8d2c3a3feb84e9646b1447de704d2dff860dc5cea4
-  data.tar.gz: 533131b2461c719cb5525695a5abdc26b474bc6ce9fe35ba338855a698e887a3
+  metadata.gz: 4aaf85a067f816ee90dbc1fd3377a92945e537ea95f28488ca54ea6d91b5f29f
+  data.tar.gz: 456e78aadc75e798193304f29dff4ec06ed5eb228a38c58be81a949348e640cf
 SHA512:
-  metadata.gz: c0a779b8563993d01400a7587852f2ec65c65621facd1bd3e9c44d39404e44eff0656a137a12f6a8da1b60b902d6bfe897b35ab82627064c8238f005171d0623
-  data.tar.gz: 8b9c2ce522dc9360c40f1779b7e4240370e5a7dbe4e6b333f9c39583bf2ba5a43805aa4b523763322ca62716b23c619047291beff28cb5b33abe88ad7874f96c
+  metadata.gz: 1aa2448506788dc991aa7c0761c59122bb73a11a3929217aedad30e2bdb29f8129a1022ad5b6e8a74c43ad17524f4353b18cc374ae3ae70f7bc366d8ab97e581
+  data.tar.gz: edd4e3a049e6d6caafc80b1a3b77f54c074eb777b40c075acdb704707558669560c02356857c6ddc33d535096a3a67d125ec1c07d9001fc3a45cb3d90199daf1

data/CHANGELOG.md

@@ -7,6 +7,137 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-19
+
+### Added
+
+- `fast/prometheus/instrumentation/completions` — an opt-in telemetry
+  adapter for the [fast-completions](https://github.com/jetpks/fast-llm)
+  gem: `Fast::Prometheus::Instrumentation::Completions` includes
+  `Fast::Completions::Telemetry::Sink` and turns the completion hooks into
+  five metrics on a registry — `llm_completions_total`
+  (`provider`/`model`/`stop_reason`), `llm_completions_errors_total`
+  (`error`), `llm_completions_duration_seconds` and
+  `llm_completions_ttfb_seconds` (`provider`/`model` and unlabeled
+  respectively, default buckets), and `llm_completions_tokens_total`
+  (`provider`/`model`/`kind`). Labels come from the live assistant Message
+  (`provider`/`model`, nil collapsed to `"unknown"` — never
+  `response_model`/`response_id`), the hook Symbols (`stop_reason`,
+  `error`), and the frozen `kind` values `"input"`/`"output"`; a nil
+  `usage` skips the token counters. A warm notification-to-metric dispatch
+  allocates nothing: chained Hash lookups into metrics pre-bound once per
+  series via `with_labels`. fast-completions stays a runtime peer — the
+  require path fails loud with `LoadError` when the peer gem is absent —
+  and a metric pre-registered under one of the five names is validated
+  (type and labels) at construction, the `RequestMetrics` pattern. See
+  [the how-to](docs/how-to/instrument-completions.md).
+
+## [0.4.0] - 2026-09-19
+
+### Changed
+
+- **Breaking:** declared label names are normalized to `Symbol`s at
+  construction. `labels: ["method"]` and `labels: [:method]` now declare the
+  same metric and `Metric#labels` reports `[:method]` for both, so a `String`
+  key at observe time — `increment(labels: { "method" => "GET" })` — is an
+  unknown label and raises `InvalidLabelSet` where it used to resolve. Two
+  names that normalize to the same `Symbol` (`%i[x x]`, `[:x, "x"]`) are a
+  duplicate and raise `InvalidLabelName`, as do the reserved names now that
+  they are checked after normalization: `"le"` on a `Histogram` and
+  `"quantile"` on a `Summary` raise where only `:le` and `:quantile` did. The
+  `labels:` and `buckets:` Arrays are copied and frozen, so mutating the Array
+  you passed no longer reaches into the metric.
+- Label values and docstrings are normalized to valid UTF-8 at the boundary
+  where they enter the store, so no reader, renderer or exporter downstream can
+  meet a mixed or an invalid encoding. An ASCII-only String is kept exactly as
+  it is whatever its encoding tag (`"GET".b` out of a Rack env, `US-ASCII` out
+  of `200.to_s`); invalid UTF-8 is scrubbed; `BINARY` is reinterpreted as UTF-8
+  bytes and scrubbed, never transcoded; any other encoding is transcoded with
+  replacement. A registry holding label values in two encodings no longer fails
+  its scrape with `Encoding::CompatibilityError`, and `Formats::Text.render`
+  builds its body in UTF-8 from the first byte, matching the `charset=utf-8` it
+  advertises. Bytes that are not valid UTF-8 are replaced, not preserved — see
+  Normalization in the metrics reference. The cost is on the labeled write
+  path: about 5–10% fewer iterations per second in `benchmark/observe.rb`
+  against 0.3.2 in a paired run, with bound and unlabeled calls and every
+  allocation budget unchanged.
+- The `method` label on `Middleware::Instrumentation` and
+  `Rack::Instrumentation` is allowlisted to the RFC 9110 methods plus `PATCH`;
+  every other token is counted as `method="_OTHER"`, the value OpenTelemetry's
+  HTTP semantic conventions collapse an unrecognized method to. An HTTP method
+  is any token both `Protocol::HTTP` and Rack accept, and nothing reclaims a
+  series once it exists, so the two RED metrics now hold at most ten `method`
+  values however many a client invents. Matching is case-sensitive, so `get` is
+  `_OTHER`.
+- `Accept` and `Accept-Encoding` are parsed as RFC 9110 lists rather than
+  searched for a substring: the token is matched whole and case-insensitively,
+  `q=0` is a refusal, the higher `q` wins between
+  `application/vnd.google.protobuf` and `text/plain`, and a tie is protobuf.
+  `Accept: text/plain;version=0.0.4` no longer selects protobuf because the
+  word appears in a parameter, and `gzip;q=0` is honoured as the refusal it is.
+  Text remains the fallback for a request accepting neither format.
+- `Middleware::Instrumentation` and `Rack::Instrumentation` validate a metric
+  already registered under either of their names before reusing it: it must
+  declare `labels: %i[method status]` and be a kind `record` can drive — a
+  counter under the counter name, something observable under the duration name.
+  A mismatch raises `InvalidMetricType` (kind) or `InvalidLabelSet` (labels)
+  from the constructor, at boot where the mistaken declaration is, instead of
+  once per request from inside the app's request path.
+- **Breaking:** `OTLP::Mapper.new(start_time:)` takes a `Time`, and both it and
+  `snapshot.taken_at` are carried as exact nanoseconds (`tv_sec`/`tv_nsec`)
+  rather than through a `Float`, which lost the low ~256 ns at epoch
+  magnitudes. A `Float` start time no longer works.
+- OTLP resource attributes keep their Ruby type — `String` to `string_value`,
+  `Integer` to `int_value`, `Float` to `double_value`, `true`/`false` to
+  `bool_value`, anything else its `to_s` — and their keys may be `Symbol`s,
+  which makes the `resource_attributes: { service: "my-app" }` in the
+  export-otlp how-to run as written. Data point label attributes stay
+  `string_value`.
+- `Formats::Protobuf.render` omits a label whose value is the empty String,
+  which is implicit presence for a proto3 `string` and what `google-protobuf`
+  writes: a series carrying an empty label value is now byte-identical to the
+  reference encoder's output instead of a byte longer.
+- `NativeHistogram#observe` raises `ArgumentError` unless its value is
+  `Numeric`, as every other metric type does; `NaN` and `±Infinity` are still
+  accepted and still never raise.
+- `Histogram.new` rejects a non-finite bucket bound with `ArgumentError`. The
+  `+Inf` bucket is implicit and always rendered, so an explicit
+  `Float::INFINITY` (or `Float::NAN`) bound was a silent mistake, not a second
+  `+Inf`.
+- Benchmarks re-taken on this tree against fast-protowire 0.3.0 and
+  republished on the benchmarks page and in the README.
+
+### Fixed
+
+- `OTLP::Mapper` no longer sizes a bucket array by the distance between two
+  observations. A `:native_histogram` series clamps a `±Infinity` observation
+  to bucket index `2**31 - 1`, and OTLP carries one contiguous bucket-count
+  array per side, so exporting such a series allocated an Array of billions of
+  slots. An `ExponentialHistogram` data point now carries the series' finite
+  observations only — the clamp bucket and `NaN`s are left out of the bucket
+  arrays and out of `count`, and `sum` is omitted, as the field is `optional`,
+  once the accumulated sum is no longer finite, which is what the OTel SDKs do
+  — and a series needing more than 1024 dense slots on either side is merged to
+  a coarser exported `scale` until it fits. The Prometheus-side value is
+  untouched; `Formats::Protobuf` still exposes every observation.
+- `NativeHistogram` puts a subnormal observation (under `Float::MIN`) in the
+  right bucket. The bucket bounds down there are subnormal too and the `2.0**x`
+  the index search compares against underflows to zero among them, so a
+  subnormal landed in a neighbouring bucket; it is now scaled into the normal
+  range by a power of two first, which is exact, and its index shifted back.
+- `Middleware::Exporter` serves `/metrics?x=1`. A `Protocol::HTTP` request
+  target carries its query string, unlike Rack's `PATH_INFO`, so the exact
+  match on the path meant a Prometheus scrape config with `params:` fell
+  through to the wrapped app. The path component is now matched; `/metrics/`,
+  `/METRICS` and `/metricsx` still delegate.
+- Content negotiation is a function of the request header's bytes, whatever
+  encoding the String is tagged with, and never raises. A UTF-8-tagged header
+  holding invalid bytes — what a client can send and a Rack harness hands over
+  as it arrived — used to raise `ArgumentError` out of `Exposition.render` and
+  fail the scrape; a header that cannot be made sense of now simply scores
+  nothing, which is text and no compression, and a well-formed member beside
+  garbage still selects.
+
 ## [0.3.2] - 2026-09-19
 
 ### Changed

data/README.md

@@ -62,6 +62,7 @@ under Falcon and scraping it with a real Prometheus, see
 - [How to scrape native histograms](docs/how-to/scrape-native-histograms.md) — configure Prometheus to negotiate protobuf so native histograms aren't dropped.
 - [How to share one registry across boot paths](docs/how-to/share-a-registry.md) — use `fetch_or_register` so multiple boot paths can construct the same metric safely.
 - [How to export over OTLP](docs/how-to/export-otlp.md) — push metrics to an OTLP collector over gRPC or HTTP.
+- [How to instrument LLM completions](docs/how-to/instrument-completions.md) — record the fast-completions telemetry metrics from a `Fast::Completions` client.
 - [How to verify a release build](docs/how-to/verify-a-release.md) — run the integration harness against a packaged gem before tagging.
 
 ### Reference
@@ -98,10 +99,10 @@ comparisons against `prometheus-client` and `google-protobuf`; see
   `google-protobuf` encoder needed 3.5 million Ruby objects and 504k native arenas, and
   in a hundredth of the GC time; taking the snapshot it reads is 1 ms and one Hash per metric
 - The text renderer allocates **66x fewer objects** than prometheus-client's formatter
-  for the same body, and renders it 3.2x faster at 36,000 series
+  for the same body, and renders it 3.1x faster at 36,000 series
 - Bound counter and gauge writes allocate nothing and are **1.45x** faster than
-  prometheus-client's; histogram observe is **3.1x** faster and summary observe **3.3x**
-- Native histogram observe runs at **1.32M i/s** with no prometheus-client equivalent
+  prometheus-client's; histogram observe is **2.9x** faster and summary observe **3.1x**
+- Native histogram observe runs at **1.2M i/s** with no prometheus-client equivalent
 
 ## Development
 

data/lib/fast/prometheus/errors.rb

@@ -6,6 +6,7 @@ module Fast
     class InvalidMetricName < Error; end
     class InvalidLabelName < Error; end
     class InvalidLabelSet < Error; end
+    class InvalidMetricType < Error; end
     class DuplicateMetric < Error; end
   end
 end

data/lib/fast/prometheus/exposition.rb

@@ -12,8 +12,17 @@ module Fast
     # negotiating format (text vs protobuf) and gzip from Accept / Accept-Encoding
     # header values. Shared by Middleware::Exporter and Rack::Exporter so
     # negotiation and compression exist exactly once.
+    #
+    # Both headers are read as RFC 9110 lists over their bytes: comma-separated
+    # members, each a token with optional ";"-parameters. The token is matched
+    # whole and case-insensitively, parameters other than "q" are ignored, and
+    # "q=0" is a refusal. Nothing here raises: a header we cannot make sense of
+    # — invalid bytes included — simply scores nothing, which is the text
+    # format and no compression.
     module Exposition
       PROTOBUF_ACCEPT = "application/vnd.google.protobuf"
+      TEXT_ACCEPT = "text/plain"
+      GZIP_CODING = "gzip"
 
       FORMAT_MAP = {
         true => [Formats::Protobuf, Formats::Protobuf::CONTENT_TYPE],
@@ -22,11 +31,11 @@ module Fast
       private_constant :FORMAT_MAP
 
       def self.render(registry, accept:, accept_encoding:)
-        format, content_type = FORMAT_MAP[protobuf?(accept)]
+        format, content_type = FORMAT_MAP[protobuf?(byte_view(accept))]
         body = format.render(registry.collect)
         headers = { "content-type" => content_type }
 
-        if gzip?(accept_encoding)
+        if gzip?(byte_view(accept_encoding))
           body = Zlib.gzip(body)
           headers["content-encoding"] = "gzip"
         end
@@ -34,12 +43,51 @@ module Fast
         [body, headers]
       end
 
+      # Protobuf wins when it is acceptable and no less acceptable than text —
+      # on a tie, the order Prometheus itself lists the two in.
       private_class_method def self.protobuf?(accept)
-        accept.to_s.include?(PROTOBUF_ACCEPT)
+        quality = quality_of(accept, PROTOBUF_ACCEPT)
+        quality.positive? && quality >= quality_of(accept, TEXT_ACCEPT)
       end
 
       private_class_method def self.gzip?(accept_encoding)
-        accept_encoding.to_s.include?("gzip")
+        quality_of(accept_encoding, GZIP_CODING).positive?
+      end
+
+      # The header's bytes, whatever String the server handed us: negotiation
+      # answers the bytes and nothing else. #strip and #casecmp? raise on a
+      # UTF-8-tagged String holding invalid ones — and io-stream, Puma and a
+      # test harness tag the same bytes BINARY, BINARY and UTF-8 — while BINARY
+      # bytes are always valid, so nothing below can raise. One String per
+      # header on a path that renders the whole registry anyway.
+      private_class_method def self.byte_view(header)
+        header.to_s.b
+      end
+
+      # The highest q value +token+ carries across the members of a list header:
+      # 0.0 when it is absent or refused with q=0, 1.0 when it is listed without
+      # one. #split with a block keeps a long header's members out of an Array.
+      private_class_method def self.quality_of(header, token)
+        best = 0.0
+        header.split(",") do |member|
+          name, _, parameters = member.partition(";")
+          next unless name.strip.casecmp?(token)
+
+          quality = quality_parameter(parameters)
+          best = quality if quality > best
+        end
+        best
+      end
+
+      # One member's q parameter, 1.0 when it has none. A quoted parameter value
+      # holding ";" or "=" can only hide a q from us, never fake one, and a
+      # hidden q is the default anyway.
+      private_class_method def self.quality_parameter(parameters)
+        parameters.split(";") do |parameter|
+          name, _, value = parameter.partition("=")
+          return value.strip.to_f if name.strip.casecmp?("q")
+        end
+        1.0
       end
     end
   end

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

@@ -105,16 +105,20 @@ module Fast
           end
         end
 
-        # LabelPair { string name = 1; string value = 2 }.
+        # LabelPair { string name = 1; string value = 2 }. Implicit presence:
+        # an empty value is the field's default and is not sent, as the
+        # declared Proto::LabelPair (and google-protobuf) leave it out.
         private_class_method def self.append_label_pair(out, name, value)
           name = name.name if name.is_a?(Symbol)
           value = value.to_s
           name_size = name.bytesize
           value_size = value.bytesize
+          size = 1 + varint_size(name_size) + name_size
+          size += 1 + varint_size(value_size) + value_size unless value.empty?
           out << METRIC_LABEL
-          append_varint(out, 2 + varint_size(name_size) + name_size + varint_size(value_size) + value_size)
+          append_varint(out, size)
           Fast::Protowire::Wire.append_length_delimited(out, LABEL_NAME, name)
-          Fast::Protowire::Wire.append_length_delimited(out, LABEL_VALUE, value)
+          Fast::Protowire::Wire.append_length_delimited(out, LABEL_VALUE, value) unless value.empty?
         end
 
         # Counter / Gauge { double value = 1 }: empty when the value is the

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

@@ -11,6 +11,10 @@ module Fast
       # 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.
+      #
+      # The buffer is UTF-8 from the start and the snapshot's docstrings and
+      # label values are already valid UTF-8 (see Metric), so the body is
+      # always a UTF-8-tagged, valid String whatever it holds.
       module Text
         CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
 
@@ -21,7 +25,7 @@ module Fast
         LABEL_REPLACE = { "\\" => "\\\\", '"' => '\\"', "\n" => "\\n" }.freeze
 
         def self.render(snapshot)
-          snapshot.metrics.each_with_object(String.new) do |metric, output|
+          snapshot.metrics.each_with_object(String.new(encoding: Encoding::UTF_8)) do |metric, output|
             next if metric.type == :native_histogram
 
             name = metric.name.name

data/lib/fast/prometheus/histogram.rb

@@ -46,11 +46,10 @@ module Fast
       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 contain only finite values" unless buckets.all?(&:finite?)
         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
+        @buckets = buckets.dup.freeze
         super(name, docstring: docstring, labels: labels, preset_labels: preset_labels, store: store)
       end
 
@@ -143,6 +142,12 @@ module Fast
         hash["sum"] = slot.sum
         hash
       end
+
+      def validate_label_names(labels)
+        raise InvalidLabelName, "reserved label name: :le" if labels.include?(:le)
+
+        super
+      end
     end
   end
 end

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

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+
+# The documented soft require: fast-completions is a runtime peer, never a
+# gemspec dependency of this gem, so an app without it fails loud here — at
+# require time, where the missing peer belongs — instead of half-loading a
+# sink that can never fire. See docs/how-to/instrument-completions.md.
+require "fast/completions/telemetry"
+
+module Fast
+  module Prometheus
+    module Instrumentation
+      # The fast-completions telemetry adapter: one sink object that turns
+      # the Telemetry::Sink observation points into five metric families on
+      # a registry. Construct it and hand it to Fast::Completions::Client:
+      #
+      #   sink = Fast::Prometheus::Instrumentation::Completions.new
+      #   client = Fast::Completions::Client.new(..., telemetry: [sink])
+      #
+      # Metric table (frozen):
+      #   llm_completions_total           Counter   provider, model, stop_reason
+      #   llm_completions_errors_total    Counter   error
+      #   llm_completions_duration_seconds Histogram provider, model
+      #   llm_completions_ttfb_seconds    Histogram (none)
+      #   llm_completions_tokens_total    Counter   provider, model, kind
+      #
+      # Label values come from the hook arguments and the LIVE assistant
+      # Message — provider is message.provider, model is message.model
+      # (never response_model/response_id, which are wire metadata, not
+      # series identity), stop_reason/error are the hook Symbols, kind is
+      # the frozen "input"/"output". The Message contract allows a nil
+      # provider or model; those become the "unknown" sentinel so one nil
+      # is one series, not a raise.
+      #
+      # A warm dispatch allocates NOTHING: every hook is chained Hash
+      # lookups over existing refs into a pre-bound metric — no label Hash,
+      # no Array key, no String is built. A cold series binds once through
+      # #with_labels and is cached under the raw hook values, so the miss
+      # cost is paid once per (provider, model, stop_reason/kind) triple.
+      class Completions
+        include Fast::Completions::Telemetry::Sink
+
+        END_LABELS = %i[provider model stop_reason].freeze
+        ERROR_LABELS = %i[error].freeze
+        DURATION_LABELS = %i[provider model].freeze
+        TOKEN_LABELS = %i[provider model kind].freeze
+
+        # nil provider/model collapse here (the Message contract allows
+        # both to be nil) rather than minting an exception series.
+        UNKNOWN = "unknown"
+
+        COUNTER_TYPES = %i[counter].freeze
+        HISTOGRAM_TYPES = %i[histogram].freeze
+
+        private_constant :END_LABELS, :ERROR_LABELS, :DURATION_LABELS, :TOKEN_LABELS,
+                         :COUNTER_TYPES, :HISTOGRAM_TYPES
+
+        # +registry+ defaults to the module-level registry, so a second
+        # adapter constructed anywhere reuses the same five metrics
+        # (Registry#fetch_or_register) and shares their series.
+        def initialize(registry: Fast::Prometheus.registry)
+          @registry = registry
+
+          # Series caches, one level per label: provider → model →
+          # stop_reason/kind (or plain model for the duration histogram)
+          # → the bound metric itself. The ttfb histogram is unlabeled and
+          # dispatched directly. Keyed by the raw hook values, so a hit is
+          # Hash lookups with existing refs and nothing else.
+          @ends = {}
+          @durations = {}
+          @tokens = {}
+          @errors = {}
+
+          @completions_total = ensure_counter(:llm_completions_total, END_LABELS,
+                                              "Total LLM completions by stop reason")
+          @errors_total = ensure_counter(:llm_completions_errors_total, ERROR_LABELS,
+                                         "Total LLM completions that raised out of the client")
+          @duration_seconds = ensure_histogram(:llm_completions_duration_seconds, DURATION_LABELS,
+                                               "LLM completion duration in seconds")
+          @ttfb_seconds = ensure_histogram(:llm_completions_ttfb_seconds, [].freeze,
+                                           "LLM completion time to first byte in seconds")
+          @tokens_total = ensure_counter(:llm_completions_tokens_total, TOKEN_LABELS,
+                                         "LLM completion token usage by kind")
+        end
+
+        # on_completion_start and on_event stay the Sink's no-ops: the
+        # metric table is scoped to ttfb and the two terminal hooks — the
+        # per-event surface belongs to whoever reads the Message.
+
+        def on_completion_ttfb(seconds)
+          @ttfb_seconds.observe(seconds)
+        end
+
+        def on_completion_end(stop_reason, duration, message)
+          provider = message.provider
+          model = message.model
+
+          # Warm: chained lookups into existing bound metrics. Cold: the
+          # bind helpers below run once per series and cache the binding.
+          counter = ((@ends[provider] ||= {})[model] ||= {})[stop_reason]
+          counter ||= bind_end(provider, model, stop_reason)
+          counter.increment
+
+          histogram = (@durations[provider] ||= {})[model]
+          histogram ||= bind_duration(provider, model)
+          histogram.observe(duration)
+
+          # The Message contract allows nil usage (and the read-only
+          # convention says nil-check without allocating): a completion
+          # without accounting skips the token counters entirely.
+          usage = message.usage
+          return unless usage
+
+          kinds = (@tokens[provider] ||= {})[model]
+          kinds ||= bind_tokens(provider, model)
+          kinds[:input].increment(by: usage.input)
+          kinds[:output].increment(by: usage.output)
+        end
+
+        # Errored completions get the errors counter and no duration: the
+        # histogram observes only completions that returned.
+        def on_completion_error(error, _duration)
+          counter = @errors[error]
+          counter ||= bind_error(error)
+          counter.increment
+        end
+
+        private
+
+        def ensure_counter(name, labels, docstring)
+          metric = @registry.fetch_or_register(name) do
+            Counter.new(name, docstring: docstring, labels: labels)
+          end
+
+          validate(metric, COUNTER_TYPES, labels)
+        end
+
+        def ensure_histogram(name, labels, docstring)
+          metric = @registry.fetch_or_register(name) do
+            Histogram.new(name, docstring: docstring, labels: labels)
+          end
+
+          validate(metric, HISTOGRAM_TYPES, labels)
+        end
+
+        # A metric already registered under one of these names is reused
+        # only if it is the table's type and declares the table's labels.
+        # Otherwise every completion would raise from inside the client's
+        # dispatch; raise here instead, once, at construction, where the
+        # mistaken declaration is (the RequestMetrics pattern).
+        def validate(metric, types, labels)
+          unless types.include?(metric.type)
+            raise InvalidMetricType, "#{metric.name} declares type #{metric.type.inspect}, not #{types.inspect}"
+          end
+
+          unless metric.labels == labels
+            raise InvalidLabelSet, "#{metric.name} declares labels #{metric.labels.inspect}, not #{labels.inspect}"
+          end
+
+          metric
+        end
+
+        def bind_end(provider, model, stop_reason)
+          @ends[provider][model][stop_reason] = @completions_total.with_labels(
+            provider: label_value(provider), model: label_value(model), stop_reason: stop_reason
+          )
+        end
+
+        def bind_duration(provider, model)
+          @durations[provider][model] = @duration_seconds.with_labels(
+            provider: label_value(provider), model: label_value(model)
+          )
+        end
+
+        def bind_tokens(provider, model)
+          kinds = @tokens[provider][model] = {}
+          kinds[:input] = @tokens_total.with_labels(
+            provider: label_value(provider), model: label_value(model), kind: "input"
+          )
+          kinds[:output] = @tokens_total.with_labels(
+            provider: label_value(provider), model: label_value(model), kind: "output"
+          )
+          kinds
+        end
+
+        def bind_error(error)
+          @errors[error] = @errors_total.with_labels(error: error)
+        end
+
+        # with_labels normalizes label values to frozen UTF-8 Strings, so
+        # passing the hook Symbol binds its to_s and passing a String
+        # binds the ref — nothing here runs on a warm dispatch.
+        def label_value(value)
+          value || UNKNOWN
+        end
+      end
+    end
+  end
+end

data/lib/fast/prometheus/metric.rb

@@ -7,6 +7,10 @@ module Fast
   module Prometheus
     # Metric is the abstract base class for all metric types.
     #
+    # Declared label names are normalized to Symbols and label values (and the
+    # docstring) to valid UTF-8 here, where they enter the store, so no reader
+    # or renderer downstream can meet a mixed encoding or an invalid one.
+    #
     # 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
@@ -21,13 +25,14 @@ module Fast
       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.to_s.to_sym
-        @docstring = docstring
-        @labels = labels
-        @preset_labels = preset_labels.transform_values { |v| v.to_s.freeze }
+        @docstring = normalize_text(docstring)
+
+        @labels = labels.map { |label| label.to_s.to_sym }.freeze
+        validate_label_names(@labels)
+        @preset_labels = preset_labels.to_h { |key, value| [key.to_s.to_sym, normalize_text(value).freeze] }
+        validate_preset_labels(@labels, @preset_labels)
+
         @store = store || Store.new
 
         return unless fully_bound?
@@ -59,7 +64,7 @@ module Fast
 
       def with_labels(**labels)
         validate_label_keys(labels)
-        merged = @preset_labels.merge(labels.transform_values { |v| v.to_s.freeze })
+        merged = @preset_labels.merge(labels.transform_values { |v| normalize_text(v).freeze })
         self.class.new(
           @name,
           docstring: @docstring,
@@ -109,7 +114,7 @@ module Fast
 
         @labels.map do |n|
           if labels.key?(n)
-            labels[n].to_s
+            normalize_text(labels[n])
           else
             value = @preset_labels[n]
             raise InvalidLabelSet, "missing labels: #{n.inspect}" unless value
@@ -164,6 +169,29 @@ module Fast
         @preset_labels.size == @labels.size
       end
 
+      # Label values and docstrings are stored as valid UTF-8 bytes. An
+      # ASCII-only String already is one, whatever encoding it is tagged with
+      # (US-ASCII from Integer#to_s or Symbol#to_s, BINARY from a Rack env),
+      # so it is returned as is: #ascii_only? is coderange-cached, and the hot
+      # path allocates nothing per value. Only a non-ASCII String pays for the
+      # tag check, and valid UTF-8 is still returned as is — String#scrub
+      # would copy.
+      def normalize_text(value)
+        string = value.is_a?(String) ? value : value.to_s
+        return string if string.ascii_only?
+
+        case string.encoding
+        when Encoding::UTF_8
+          string.valid_encoding? ? string : string.scrub
+        when Encoding::BINARY
+          # Reinterpreted, never transcoded: BINARY is bytes, not a charset.
+          # #scrub! returns self, so the dup is the only object either way.
+          string.dup.force_encoding(Encoding::UTF_8).scrub!
+        else
+          string.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+        end
+      end
+
       def validate_metric_name(name)
         return if name.to_s.match?(METRIC_NAME)
 
@@ -176,12 +204,18 @@ module Fast
         raise ArgumentError, "docstring must be a non-empty string"
       end
 
+      # Validates the already-normalized Symbol names as a set: each one a
+      # legal, unreserved label name, and no two of them the same.
       def validate_label_names(labels)
         labels.each do |label|
-          name = label.to_s
+          name = label.name
           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
+
+        return if labels.uniq.size == labels.size
+
+        raise InvalidLabelName, "duplicate label names: #{labels.inspect}"
       end
 
       def validate_preset_labels(labels, preset_labels)

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

@@ -14,16 +14,24 @@ module Fast
           super(delegate)
           @registry = registry
           @path = path
+          @query_prefix = "#{path}?".freeze
         end
 
         def call(request)
-          return serve_metrics(request) if request.method == "GET" && request.path == @path
+          return serve_metrics(request) if request.method == "GET" && metrics_target?(request.path)
 
           super
         end
 
         private
 
+        # A Protocol::HTTP request target carries its query string ("/metrics?x=1"),
+        # unlike Rack's PATH_INFO, so match the path component: the path itself,
+        # or the path followed by any query.
+        def metrics_target?(target)
+          target == @path || target.start_with?(@query_prefix)
+        end
+
         def serve_metrics(request)
           body, headers = Exposition.render(
             @registry,

data/lib/fast/prometheus/native_histogram.rb

@@ -39,6 +39,12 @@ module Fast
       # client_golang math.MaxInt32 convention for clamped ±Inf bucket index.
       MAX_BUCKET_INDEX = (2**31) - 1
 
+      # Powers of two a subnormal is scaled up by before its bucket is found —
+      # enough to bring the smallest of them (2**-1074) well into the normal
+      # range, and a multiple of 2**4 so the index shifts by a whole bucket at
+      # every schema.
+      SUBNORMAL_SHIFT = 64
+
       attr_reader :schema, :zero_threshold, :max_buckets
 
       def initialize(name, docstring:, labels: [], preset_labels: {}, schema: 3, zero_threshold: 2.0**-128,
@@ -63,8 +69,11 @@ module Fast
         :native_histogram
       end
 
-      # Record an observation. Never raises — NaN/±Inf are handled gracefully.
+      # Record an observation. A non-Numeric is an ArgumentError, as it is on
+      # every other type; NaN and ±Inf are handled gracefully and never raise.
       def observe(value, labels: NO_LABELS)
+        raise ArgumentError, "value must be a numeric" unless value.is_a?(Numeric)
+
         v = value.to_f
         key = resolve(labels)
 
@@ -135,7 +144,19 @@ module Fast
                                  slot.positive_buckets, slot.negative_buckets).freeze
       end
 
+      # ceil(log2(value) * 2**schema), the log2 estimate corrected against the
+      # bucket bounds either side of it.
+      #
+      # A subnormal value is scaled into the normal range first: its bounds
+      # are subnormal too, and the 2.0**x below underflows to zero among them,
+      # which puts the smallest values in the wrong bucket. Scaling by a power
+      # of two is exact, and moves every index by that power times the schema.
       def index_for(value, schema)
+        if value < Float::MIN
+          shift = schema.positive? ? SUBNORMAL_SHIFT << schema : SUBNORMAL_SHIFT >> -schema
+          return index_for(Math.ldexp(value, SUBNORMAL_SHIFT), schema) - shift
+        end
+
         factor = 2.0**schema
         idx = (Math.log2(value) * factor).ceil
         idx -= 1 while 2.0**((idx - 1) / factor) >= value

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

@@ -11,12 +11,20 @@ module Fast
         CUMULATIVE = :AGGREGATION_TEMPORALITY_CUMULATIVE
         private_constant :CUMULATIVE
 
+        # OTLP carries one contiguous bucket-count array per side, so an export
+        # must never size an Array by the distance between two observations:
+        # past this many slots a data point drops to a coarser scale instead.
+        MAX_DENSE_BUCKETS = 1024
+        private_constant :MAX_DENSE_BUCKETS
+
         def initialize(resource_attributes: {}, start_time: Time.now)
-          @resource_attributes = resource_attributes.map { |k, v| kv(k, v) }
-          @start_time_unix_nano = (start_time.to_f * 1_000_000_000).to_i
+          @resource_attributes = resource_attributes.map { |key, value| kv(key, any_value(value)) }
+          @start_time_unix_nano = unix_nano(start_time)
         end
 
         def request(snapshot)
+          time_unix_nano = unix_nano(snapshot.taken_at)
+
           Proto::ExportMetricsServiceRequest.new(
             resource_metrics: [
               Proto::ResourceMetrics.new(
@@ -29,7 +37,7 @@ module Fast
                       name: "fast-prometheus",
                       version: Fast::Prometheus::VERSION
                     ),
-                    metrics: snapshot.metrics.map { |ms| build_metric(ms, snapshot.taken_at) }
+                    metrics: snapshot.metrics.map { |ms| build_metric(ms, time_unix_nano) }
                   )
                 ]
               )
@@ -39,9 +47,12 @@ module Fast
 
         private
 
-        def build_metric(metric_snapshot, taken_at)
-          time_unix_nano = (taken_at.to_f * 1_000_000_000).to_i
+        # Exact nanoseconds: at epoch magnitudes a Float loses the low ~256ns.
+        def unix_nano(time)
+          (time.tv_sec * 1_000_000_000) + time.tv_nsec
+        end
 
+        def build_metric(metric_snapshot, time_unix_nano)
           Proto::Metric.new(
             name: metric_snapshot.name.to_s,
             description: metric_snapshot.docstring,
@@ -154,21 +165,79 @@ module Fast
           )
         end
 
+        # A data point carries only the series' finite observations: OTLP has no
+        # bucket for an infinity and no count for a NaN, so both are dropped —
+        # from the buckets, from +count+, and from +sum+, which is left absent
+        # when the series' accumulated sum is no longer finite.
         def exponential_histogram_data_point(attributes, value, time_unix_nano)
+          positive = finite_buckets(value.positive_buckets, value.schema)
+          negative = finite_buckets(value.negative_buckets, value.schema)
+          reduction = scale_reduction(positive, negative)
+          positive = merge_buckets(positive, reduction)
+          negative = merge_buckets(negative, reduction)
+
           Proto::ExponentialHistogramDataPoint.new(
             attributes: attributes,
             start_time_unix_nano: @start_time_unix_nano,
             time_unix_nano: time_unix_nano,
-            count: value.count,
-            sum: value.sum,
-            scale: value.schema,
+            count: value.zero_count + bucket_total(positive) + bucket_total(negative),
+            sum: (value.sum if value.sum.finite?),
+            scale: value.schema - reduction,
             zero_count: value.zero_count,
             zero_threshold: value.zero_threshold,
-            positive: dense_buckets(value.positive_buckets),
-            negative: dense_buckets(value.negative_buckets)
+            positive: dense_buckets(positive),
+            negative: dense_buckets(negative)
           )
         end
 
+        # NativeHistogram clamps a ±Inf observation to MAX_BUCKET_INDEX, and
+        # downscaling halves that index along with every other one. Either way
+        # it stays above the index of any finite observation, which |value| <=
+        # Float::MAX puts at 1024 * 2**schema at the most, so it sorts last and
+        # is the only pair up there.
+        def finite_buckets(buckets, schema)
+          return buckets if buckets.empty? || buckets.last.first <= 1024 * (2.0**schema)
+
+          buckets[0..-2]
+        end
+
+        def bucket_total(buckets)
+          buckets.sum { |_, count| count }
+        end
+
+        # How many times both sides' resolution has to halve for each dense
+        # array to fit MAX_DENSE_BUCKETS. A data point carries one scale, so the
+        # two sides reduce together.
+        def scale_reduction(positive, negative)
+          reduction = 0
+          reduction += 1 while dense_length(positive, reduction) > MAX_DENSE_BUCKETS ||
+                               dense_length(negative, reduction) > MAX_DENSE_BUCKETS
+          reduction
+        end
+
+        def dense_length(buckets, reduction)
+          return 0 if buckets.empty?
+
+          coarse_index(buckets.last.first, reduction) - coarse_index(buckets.first.first, reduction) + 1
+        end
+
+        # Merge each run of 2**reduction adjacent buckets into one, as
+        # NativeHistogram#downscale does for the schema it reports.
+        def merge_buckets(buckets, reduction)
+          return buckets if reduction.zero?
+
+          buckets.each_with_object({}) do |(index, count), merged|
+            key = coarse_index(index, reduction)
+            merged[key] = (merged[key] || 0) + count
+          end.to_a
+        end
+
+        # The bucket +index+ falls into after halving resolution +reduction+
+        # times: rounded toward the wider bucket, as downscaling rounds.
+        def coarse_index(index, reduction)
+          -(-index / (1 << reduction))
+        end
+
         # Convert sparse [[prom_idx, count], ...] to OTLP Buckets{offset, bucket_counts}.
         # OTLP index = prom index - 1. Offset = min OTLP index.
         # Buckets are always sorted (from NativeHistogram::Slot#positive_buckets / #negative_buckets).
@@ -190,14 +259,23 @@ module Fast
         end
 
         def build_attributes(labels)
-          labels.map { |k, v| kv(k.to_s, v.to_s) }
+          labels.map { |name, value| kv(name, Proto::AnyValue.new(string_value: value.to_s)) }
         end
 
-        def kv(key, value)
-          Proto::KeyValue.new(
-            key: key,
-            value: Proto::AnyValue.new(string_value: value)
-          )
+        def kv(key, any_value)
+          Proto::KeyValue.new(key: key.to_s, value: any_value)
+        end
+
+        # A resource attribute keeps its Ruby type where OTLP has a member for
+        # it; anything else goes over as its +to_s+.
+        def any_value(value)
+          case value
+          when String then Proto::AnyValue.new(string_value: value)
+          when Integer then Proto::AnyValue.new(int_value: value)
+          when Float then Proto::AnyValue.new(double_value: value)
+          when true, false then Proto::AnyValue.new(bool_value: value)
+          else Proto::AnyValue.new(string_value: value.to_s)
+          end
         end
       end
     end

data/lib/fast/prometheus/request_metrics.rb

@@ -7,15 +7,41 @@ module Fast
     # Owns the RED metrics (request count + duration) recorded for every HTTP
     # request. Shared by Middleware::Instrumentation and Rack::Instrumentation
     # so registration and recording exist exactly once.
+    #
+    # The method label is allowlisted, so the two metrics hold at most ten
+    # method values however many tokens clients invent — nothing reclaims a
+    # series once it exists.
     class RequestMetrics
+      LABELS = %i[method status].freeze
+
+      # The RFC 9110 methods plus PATCH, each mapped to the frozen String the
+      # store keeps, so an allowlisted method costs a lookup and no object.
+      # Matching is case-sensitive (RFC 9110 section 9.1) and finds a
+      # BINARY-tagged token from a Rack env: ASCII-only Strings hash and
+      # compare equal whatever their encoding tag.
+      METHODS = %w[GET HEAD POST PUT DELETE CONNECT OPTIONS TRACE PATCH].to_h { |name| [name, name] }.freeze
+
+      # What every other token is counted as, the value OpenTelemetry's HTTP
+      # semantic conventions collapse an unrecognized method to.
+      OTHER_METHOD = "_OTHER"
+
+      # The kinds #record can drive under each name, and that each name
+      # promises whoever scrapes it. A Gauge answers #increment, but a gauge
+      # under "_total" is not a counter to a scraper; everything that answers
+      # #observe is a duration metric.
+      COUNTER_TYPES = %i[counter].freeze
+      DURATION_TYPES = %i[histogram native_histogram summary].freeze
+
+      private_constant :LABELS, :METHODS, :OTHER_METHOD, :COUNTER_TYPES, :DURATION_TYPES
+
       def initialize(registry:, native: false, prefix: "http_server")
         @registry = registry
-        @counter = ensure_counter(prefix)
-        @histogram = ensure_histogram(prefix, native)
+        @counter = validate(ensure_counter(prefix), COUNTER_TYPES)
+        @histogram = validate(ensure_histogram(prefix, native), DURATION_TYPES)
       end
 
       def record(method, status, started_at)
-        labels = { method: method, status: status }
+        labels = { method: METHODS[method] || OTHER_METHOD, status: status }
         duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
         @counter.increment(labels: labels)
         @histogram.observe(duration, labels: labels)
@@ -26,7 +52,7 @@ module Fast
       def ensure_counter(prefix)
         name = :"#{prefix}_requests_total"
         @registry.fetch_or_register(name) do
-          Counter.new(name, docstring: "Total HTTP requests", labels: %i[method status])
+          Counter.new(name, docstring: "Total HTTP requests", labels: LABELS)
         end
       end
 
@@ -34,12 +60,28 @@ module Fast
         name = :"#{prefix}_request_duration_seconds"
         @registry.fetch_or_register(name) do
           if native
-            NativeHistogram.new(name, docstring: "HTTP request duration in seconds", labels: %i[method status])
+            NativeHistogram.new(name, docstring: "HTTP request duration in seconds", labels: LABELS)
           else
-            Histogram.new(name, docstring: "HTTP request duration in seconds", labels: %i[method status])
+            Histogram.new(name, docstring: "HTTP request duration in seconds", labels: LABELS)
           end
         end
       end
+
+      # A metric already registered under one of these names is reused only if
+      # it is one of +types+ and declares this label set. Otherwise every
+      # request would raise from inside the app's request path; raise here
+      # instead, once, where the mistaken declaration is.
+      def validate(metric, types)
+        unless types.include?(metric.type)
+          raise InvalidMetricType, "#{metric.name} declares type #{metric.type.inspect}, not #{types.inspect}"
+        end
+
+        unless metric.labels == LABELS
+          raise InvalidLabelSet, "#{metric.name} declares labels #{metric.labels.inspect}, not #{LABELS.inspect}"
+        end
+
+        metric
+      end
     end
   end
 end

data/lib/fast/prometheus/summary.rb

@@ -40,17 +40,6 @@ module Fast
         series_map { |slot| hash_shape(slot) }
       end
 
-      protected
-
-      def validate_label_names(labels)
-        labels.each do |label|
-          name = label.to_s
-          raise InvalidLabelName, "reserved label name: :quantile" if name == "quantile"
-        end
-
-        super
-      end
-
       private
 
       def zero_value
@@ -64,6 +53,12 @@ module Fast
       def hash_shape(slot)
         { "count" => slot.count, "sum" => slot.sum }
       end
+
+      def validate_label_names(labels)
+        raise InvalidLabelName, "reserved label name: :quantile" if labels.include?(:quantile)
+
+        super
+      end
     end
   end
 end

data/lib/fast/prometheus/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Prometheus
-    VERSION = "0.3.2"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-prometheus
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Eric Jacobs
@@ -109,6 +109,7 @@ files:
 - lib/fast/prometheus/formats/text.rb
 - lib/fast/prometheus/gauge.rb
 - lib/fast/prometheus/histogram.rb
+- lib/fast/prometheus/instrumentation/completions.rb
 - lib/fast/prometheus/metric.rb
 - lib/fast/prometheus/middleware/exporter.rb
 - lib/fast/prometheus/middleware/instrumentation.rb