fast-prometheus 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0421a8eb55a0265588296f0cdac33f1028cf6785c629a85f192f354bcec7d55a
-  data.tar.gz: bd02dcbb69a4a0f5bd5f592f36b9e984a3fc3cd74f2023fcb95c21f0d9662f10
+  metadata.gz: 4aaf85a067f816ee90dbc1fd3377a92945e537ea95f28488ca54ea6d91b5f29f
+  data.tar.gz: 456e78aadc75e798193304f29dff4ec06ed5eb228a38c58be81a949348e640cf
 SHA512:
-  metadata.gz: bfb624426fc812ea430544cdc0f9d1690a2cde91d65949e77765730bde6ebc264cbb1e8c774c7faad6cb1da8202543f36f26e4bc987c7836aea1ec506bcc0763
-  data.tar.gz: 30dfdebab4860d83532092fa969298f8b38d79b18573980baaca8430b9a910e3aad4e541b6a71da0e41cca8a291d41ab0c28115e10abbaef0adc35caeca5241e
+  metadata.gz: 1aa2448506788dc991aa7c0761c59122bb73a11a3929217aedad30e2bdb29f8129a1022ad5b6e8a74c43ad17524f4353b18cc374ae3ae70f7bc366d8ab97e581
+  data.tar.gz: edd4e3a049e6d6caafc80b1a3b77f54c074eb777b40c075acdb704707558669560c02356857c6ddc33d535096a3a67d125ec1c07d9001fc3a45cb3d90199daf1

data/CHANGELOG.md

@@ -7,6 +7,31 @@ 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

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

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/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Prometheus
-    VERSION = "0.4.0"
+    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.4.0
+  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