fast-prometheus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bf50aa0854cf98fd362294bd64ac2f07d04526428b6aa595c50c1058ffc82664
+  data.tar.gz: 66b21fc919d3913bdda5ae6b1aff7b661eb850981a43f54f5928d67aa0dbf16e
+SHA512:
+  metadata.gz: cb355b90d7dd5dcc885ff0181d87611ef6c39120f613053ed9a95e15988cf04b33959c3289bec698e8c664720a85a567729c8547ad53c427aa88214ba0143868
+  data.tar.gz: 379b37ebbccda56a8c3c7975351f709e138c4928be30ff3a8ccdac991164285db35fe1ce0758630506e36bb68199a311273de47d477b9578dd643ab2a8bc0da7

data/AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md
+
+Standing context for agents working in this repository.
+
+## Commands
+
+```bash
+bundle install
+bundle exec sus
+bundle exec rubocop
+bundle exec ruby script/e2e_prometheus_scrape.rb
+BENCH_QUICK=1 bundle exec ruby benchmark/observe.rb
+```
+
+## Style Rules
+
+- 2-space indentation
+- `# frozen_string_literal: true` on every source file
+- Double-quoted strings (`"..."`)
+- Fibers remain the IO concurrency model. `Thread::Mutex`/`Monitor` are permitted only where shared mutable state is guarded — metric stores and the registry. `Thread` is permitted only in tests and scripts that verify cross-thread behavior.
+
+## Test Rules
+
+- Use `sus` as the test framework
+- Tests are terse, exercising public interfaces only
+- No mock/stub of the class under test
+
+## Local Reference Sources
+
+- `~/architect/src/github.com/socketry/async`
+- `~/architect/src/github.com/socketry/async-http`
+- `~/architect/src/github.com/socketry/async-grpc`
+- `~/architect/src/github.com/socketry/protocol-grpc`
+- `~/architect/src/github.com/socketry/protocol-http`
+- `~/architect/src/github.com/socketry/sus`
+- `~/architect/src/github.com/socketry/sus-fixtures-async`
+- `/Users/eric/architect/spaces/20260715-fast-prometheus-client/repos/client_ruby`
+- `/Users/eric/architect/spaces/20260715-fast-prometheus-client/repos/prometheus`

data/CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-11
+
+### Added
+
+- `Registry#fetch_or_register(name, &block)` — an atomic fetch-or-register:
+  returns the metric already registered under `name`, else registers and
+  returns the block's metric, in one lock hold.
+- `Metric#synchronize` — runs a block atomically with respect to every other
+  mutation or read of that metric's store, including its `with_labels`-bound
+  children.
+- `Fast::Prometheus::Rack::Exporter` and `Fast::Prometheus::Rack::Instrumentation` —
+  plain Rack middleware for `config.ru`, Rails, Puma and any other Rack host,
+  built on the same content-negotiation and RED-recording core as the
+  Falcon-native `Middleware::Exporter`/`Middleware::Instrumentation`.
+
+### Fixed
+
+- `Instrumentation` middleware: concurrent construction of the middleware
+  against one registry could race two `get`/register check-then-act calls
+  and raise `DuplicateMetric`; it now registers its counter and histogram
+  through `Registry#fetch_or_register`.
+- `Instrumentation` middleware: when the delegate raised and recording the
+  failed request also raised, the recording exception replaced the
+  delegate's; the delegate's exception now always propagates.
+
+### Changed
+
+- Minimum Ruby lowered from 3.4 to 3.3 (`required_ruby_version >= 3.3`); the
+  test suite, RuboCop, the integration harness and the thread-safety stress
+  harness all pass on 3.3.12 and 4.0.5, and CI now runs the suite on both.
+- `Registry` and every metric type are now safe to share across OS threads by
+  default: each metric's per-series store is guarded by its own lock (shared
+  by `with_labels`-bound metrics), snapshot construction observes every
+  series at one consistent point, and registry operations are serialized on
+  a registry-owned lock. This retires the zero-lock hot-path invariant —
+  cross-thread use is now in contract, not out of it.
+- Documentation reorganized: `README.md` is now a front door, and the
+  tutorials, how-to guides, reference, and explanation live under `docs/`
+  per the Diátaxis framework.
+- `Formats::Text` and `Formats::Protobuf` expose only `.render`; the
+  rendering helpers they used to leak as public singleton methods are private.
+
+## [0.1.0.pre.1] - 2026-07-19
+
+### Added
+
+- Fiber-native Prometheus client built on `async`.
+- Native histograms via protobuf scrape.
+- OTLP export over gRPC and HTTP.
+- `Fast::Prometheus` namespace.

data/README.md

@@ -0,0 +1,109 @@
+# fast-prometheus
+
+A fiber-native Prometheus client for modern Ruby, built on the socketry/async
+ecosystem: HTTP middleware for `Protocol::HTTP` (Falcon-native) and Rack, safe
+to share one `Registry` across OS threads and fibers by default, native
+histograms as a first-class metric type, protobuf scrape exposition, and OTLP
+export over gRPC (async-grpc) and HTTP.
+
+Not a fork of `prometheus/client_ruby` — a new gem that uses it as the
+reference for supported surface.
+
+## Installation
+
+```bash
+gem install fast-prometheus
+```
+
+Or add to your `Gemfile`:
+
+```ruby
+gem "fast-prometheus"
+```
+
+`require "fast/prometheus"` loads only the core, with no IO dependencies. The
+opt-in surfaces and what each pulls in are listed in
+[the require-path reference](docs/reference/require-paths.md).
+
+## Quickstart
+
+```ruby
+require "fast/prometheus"
+require "fast/prometheus/formats/text"
+
+registry = Fast::Prometheus::Registry.new
+
+requests = registry.counter(:http_requests_total, docstring: "Total HTTP requests", labels: %i[method path])
+duration = registry.histogram(:request_duration_seconds, docstring: "Request duration", labels: [:method])
+
+requests.increment(labels: { method: "GET", path: "/" })
+requests.increment(by: 5, labels: { method: "POST", path: "/api" })
+duration.observe(0.042, labels: { method: "GET" })
+duration.observe(0.018, labels: { method: "GET" })
+
+puts Fast::Prometheus::Formats::Text.render(registry.collect)
+```
+
+Run with `bundle exec ruby -I lib` from the repo root. For running this
+under Falcon and scraping it with a real Prometheus, see
+[the Falcon tutorial](docs/tutorials/falcon-app.md).
+
+## Documentation
+
+### Tutorials
+
+- [Tutorial: instrument a Falcon app](docs/tutorials/falcon-app.md) — build a Falcon app instrumented with fast-prometheus and scrape it with Prometheus.
+
+### How-to guides
+
+- [How to instrument a Rack app](docs/how-to/instrument-a-rack-app.md) — add the two Rack middleware to a `config.ru`, Rails app or Puma host.
+- [How to instrument a falcon.rb service](docs/how-to/instrument-a-falcon-service.md) — run the Falcon-native middleware under `falcon host` or a threaded launcher.
+- [How to serve metrics on a separate port](docs/how-to/serve-metrics-on-a-separate-port.md) — run `/metrics` on its own `Async::HTTP::Server`, off the app's port.
+- [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 verify a release build](docs/how-to/verify-a-release.md) — run the integration harness against a packaged gem before tagging.
+
+### Reference
+
+- [Reference: registry and metrics](docs/reference/metrics.md) — every public class and method on `Registry` and the five metric types.
+- [Reference: exposition formats and HTTP middleware](docs/reference/exposition.md) — `Formats::Text`, `Formats::Protobuf`, `Middleware::Exporter`, `Middleware::Instrumentation`.
+- [Reference: OTLP export](docs/reference/otlp.md) — `OTLP::HTTPExporter`, `OTLP::GRPCExporter`, `OTLP::Push`, `OTLP::Mapper`.
+- [Reference: require paths and dependencies](docs/reference/require-paths.md) — what each require path loads and what it pulls in.
+
+### Explanation
+
+- [Concurrency model](docs/explanation/concurrency.md) — the locking contract and what it guarantees under threads and fibers.
+- [Native histograms](docs/explanation/native-histograms.md) — what a native histogram is and why it's protobuf-only.
+- [Design: why a new gem](docs/explanation/design.md) — why fast-prometheus exists instead of a `client_ruby` fork.
+- [Benchmarks](docs/explanation/benchmarks.md) — the full benchmark-ips run and how to reproduce it.
+
+## Concurrency
+
+A `Registry` is safe to share across every OS thread of a process, and
+remains safe across fibers within a thread — correct under Falcon
+`--threaded --count N`, where the N OS threads share one module-level
+`Fast::Prometheus.registry`. Falcon `--forked` mode gives each process its
+own registry, so a single scrape only sees the metrics of the process that
+handled it; aggregating across processes is out of scope. See
+[the concurrency model](docs/explanation/concurrency.md) for the full guarantee.
+
+## Performance
+
+Single process, locked, thread-safe by default (`benchmark-ips` comparisons
+against `prometheus-client`; see [the benchmarks page](docs/explanation/benchmarks.md) for the
+full run and conditions):
+
+- Bound counter (fast) is on par with prometheus-client's bound counter (1.04x)
+- Classic histogram observe is **3.0x** faster (1.71M vs 566K i/s)
+- Native histogram observe runs at **1.35M i/s** with no prometheus-client equivalent
+
+## Development
+
+```bash
+bundle exec sus
+bundle exec rubocop
+E2E_REQUIRED=1 ./integration/run
+```
+
+See [how to verify a release build](docs/how-to/verify-a-release.md) for the pre-release rule.

data/lib/fast/prometheus/counter.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative "metric"
+
+module Fast
+  module Prometheus
+    # Counter — a monotonically increasing metric.
+    class Counter < Metric
+      def type
+        :counter
+      end
+
+      def increment(by: 1, labels: {})
+        raise ArgumentError, "by must be a non-negative numeric" unless by.is_a?(Numeric) && by >= 0
+        return if by.zero?
+
+        key = resolve(labels)
+        store.synchronize { store[key] = (store[key] || 0.0) + by.to_f }
+      end
+    end
+  end
+end

data/lib/fast/prometheus/errors.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Fast
+  module Prometheus
+    class Error < StandardError; end
+    class InvalidMetricName < Error; end
+    class InvalidLabelName < Error; end
+    class InvalidLabelSet < Error; end
+    class DuplicateMetric < Error; end
+  end
+end

data/lib/fast/prometheus/exposition.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+require "fast/prometheus"
+require "fast/prometheus/formats/text"
+require "fast/prometheus/formats/protobuf"
+
+module Fast
+  module Prometheus
+    # Renders a registry snapshot into an exposition body and response headers,
+    # 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.
+    module Exposition
+      PROTOBUF_ACCEPT = "application/vnd.google.protobuf"
+
+      FORMAT_MAP = {
+        true => [Formats::Protobuf, Formats::Protobuf::CONTENT_TYPE],
+        false => [Formats::Text, Formats::Text::CONTENT_TYPE]
+      }.freeze
+      private_constant :FORMAT_MAP
+
+      def self.render(registry, accept:, accept_encoding:)
+        format, content_type = FORMAT_MAP[protobuf?(accept)]
+        body = format.render(registry.collect)
+        headers = { "content-type" => content_type }
+
+        if gzip?(accept_encoding)
+          body = Zlib.gzip(body)
+          headers["content-encoding"] = "gzip"
+        end
+
+        [body, headers]
+      end
+
+      private_class_method def self.protobuf?(accept)
+        accept.to_s.include?(PROTOBUF_ACCEPT)
+      end
+
+      private_class_method def self.gzip?(accept_encoding)
+        accept_encoding.to_s.include?("gzip")
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: metrics.proto
+
+require 'google/protobuf'
+
+require 'google/protobuf/timestamp_pb'
+
+
+descriptor_data = "\n\rmetrics.proto\x12\x14io.prometheus.client\x1a\x1fgoogle/protobuf/timestamp.proto\"(\n\tLabelPair\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\r\n\x05value\x18\x02 \x01(\t\"\x16\n\x05Gauge\x12\r\n\x05value\x18\x01 \x01(\x01\"\x7f\n\x07\x43ounter\x12\r\n\x05value\x18\x01 \x01(\x01\x12\x30\n\x08\x65xemplar\x18\x02 \x01(\x0b\x32\x1e.io.prometheus.client.Exemplar\x12\x33\n\x0fstart_timestamp\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"+\n\x08Quantile\x12\x10\n\x08quantile\x18\x01 \x01(\x01\x12\r\n\x05value\x18\x02 \x01(\x01\"\x9a\x01\n\x07Summary\x12\x14\n\x0csample_count\x18\x01 \x01(\x04\x12\x12\n\nsample_sum\x18\x02 \x01(\x01\x12\x30\n\x08quantile\x18\x03 \x03(\x0b\x32\x1e.io.prometheus.client.Quantile\x12\x33\n\x0fstart_timestamp\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x18\n\x07Untyped\x12\r\n\x05value\x18\x01 \x01(\x01\"\x8f\x04\n\tHistogram\x12\x14\n\x0csample_count\x18\x01 \x01(\x04\x12\x1a\n\x12sample_count_float\x18\x04 \x01(\x01\x12\x12\n\nsample_sum\x18\x02 \x01(\x01\x12,\n\x06\x62ucket\x18\x03 \x03(\x0b\x32\x1c.io.prometheus.client.Bucket\x12\x33\n\x0fstart_timestamp\x18\x0f \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x0e\n\x06schema\x18\x05 \x01(\x11\x12\x16\n\x0ezero_threshold\x18\x06 \x01(\x01\x12\x12\n\nzero_count\x18\x07 \x01(\x04\x12\x18\n\x10zero_count_float\x18\x08 \x01(\x01\x12\x37\n\rnegative_span\x18\t \x03(\x0b\x32 .io.prometheus.client.BucketSpan\x12\x16\n\x0enegative_delta\x18\n \x03(\x12\x12\x16\n\x0enegative_count\x18\x0b \x03(\x01\x12\x37\n\rpositive_span\x18\x0c \x03(\x0b\x32 .io.prometheus.client.BucketSpan\x12\x16\n\x0epositive_delta\x18\r \x03(\x12\x12\x16\n\x0epositive_count\x18\x0e \x03(\x01\x12\x31\n\texemplars\x18\x10 \x03(\x0b\x32\x1e.io.prometheus.client.Exemplar\"\x89\x01\n\x06\x42ucket\x12\x18\n\x10\x63umulative_count\x18\x01 \x01(\x04\x12\x1e\n\x16\x63umulative_count_float\x18\x04 \x01(\x01\x12\x13\n\x0bupper_bound\x18\x02 \x01(\x01\x12\x30\n\x08\x65xemplar\x18\x03 \x01(\x0b\x32\x1e.io.prometheus.client.Exemplar\",\n\nBucketSpan\x12\x0e\n\x06offset\x18\x01 \x01(\x11\x12\x0e\n\x06length\x18\x02 \x01(\r\"x\n\x08\x45xemplar\x12.\n\x05label\x18\x01 \x03(\x0b\x32\x1f.io.prometheus.client.LabelPair\x12\r\n\x05value\x18\x02 \x01(\x01\x12-\n\ttimestamp\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\xbe\x02\n\x06Metric\x12.\n\x05label\x18\x01 \x03(\x0b\x32\x1f.io.prometheus.client.LabelPair\x12*\n\x05gauge\x18\x02 \x01(\x0b\x32\x1b.io.prometheus.client.Gauge\x12.\n\x07\x63ounter\x18\x03 \x01(\x0b\x32\x1d.io.prometheus.client.Counter\x12.\n\x07summary\x18\x04 \x01(\x0b\x32\x1d.io.prometheus.client.Summary\x12.\n\x07untyped\x18\x05 \x01(\x0b\x32\x1d.io.prometheus.client.Untyped\x12\x32\n\thistogram\x18\x07 \x01(\x0b\x32\x1f.io.prometheus.client.Histogram\x12\x14\n\x0ctimestamp_ms\x18\x06 \x01(\x03\"\x96\x01\n\x0cMetricFamily\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0c\n\x04help\x18\x02 \x01(\t\x12.\n\x04type\x18\x03 \x01(\x0e\x32 .io.prometheus.client.MetricType\x12,\n\x06metric\x18\x04 \x03(\x0b\x32\x1c.io.prometheus.client.Metric\x12\x0c\n\x04unit\x18\x05 \x01(\t*b\n\nMetricType\x12\x0b\n\x07\x43OUNTER\x10\x00\x12\t\n\x05GAUGE\x10\x01\x12\x0b\n\x07SUMMARY\x10\x02\x12\x0b\n\x07UNTYPED\x10\x03\x12\r\n\tHISTOGRAM\x10\x04\x12\x13\n\x0fGAUGE_HISTOGRAM\x10\x05\x42\x16Z\x14io_prometheus_clientb\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Io
+  module Prometheus
+    module Client
+      LabelPair = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.LabelPair").msgclass
+      Gauge = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Gauge").msgclass
+      Counter = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Counter").msgclass
+      Quantile = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Quantile").msgclass
+      Summary = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Summary").msgclass
+      Untyped = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Untyped").msgclass
+      Histogram = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Histogram").msgclass
+      Bucket = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Bucket").msgclass
+      BucketSpan = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.BucketSpan").msgclass
+      Exemplar = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Exemplar").msgclass
+      Metric = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.Metric").msgclass
+      MetricFamily = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.MetricFamily").msgclass
+      MetricType = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("io.prometheus.client.MetricType").enummodule
+    end
+  end
+end

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

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+require_relative "metrics_pb"
+
+module Fast
+  module Prometheus
+    module Formats
+      module Protobuf
+        CONTENT_TYPE = "application/vnd.google.protobuf; proto=io.prometheus.client.MetricFamily; encoding=delimited"
+
+        TYPE_MAP = {
+          counter: Io::Prometheus::Client::MetricType::COUNTER,
+          gauge: Io::Prometheus::Client::MetricType::GAUGE,
+          summary: Io::Prometheus::Client::MetricType::SUMMARY,
+          histogram: Io::Prometheus::Client::MetricType::HISTOGRAM,
+          native_histogram: Io::Prometheus::Client::MetricType::HISTOGRAM
+        }.freeze
+        private_constant :TYPE_MAP
+
+        def self.render(snapshot)
+          snapshot.metrics.each_with_object(String.new) do |ms, buffer|
+            buffer << encode_frame(build_metric_family(ms))
+          end
+        end
+
+        private_class_method def self.build_metric_family(metric_snapshot)
+          Io::Prometheus::Client::MetricFamily.new(
+            name: metric_snapshot.name.to_s,
+            help: metric_snapshot.docstring,
+            type: TYPE_MAP.fetch(metric_snapshot.type),
+            metric: metric_snapshot.series.map { |s| build_metric(s, metric_snapshot.type) }
+          )
+        end
+
+        private_class_method def self.build_metric(series, type)
+          labels = series.labels.map do |name, value|
+            Io::Prometheus::Client::LabelPair.new(name: name.to_s, value: value)
+          end
+
+          case type
+          when :counter
+            Io::Prometheus::Client::Metric.new(
+              label: labels,
+              counter: Io::Prometheus::Client::Counter.new(value: series.value)
+            )
+          when :gauge
+            Io::Prometheus::Client::Metric.new(
+              label: labels,
+              gauge: Io::Prometheus::Client::Gauge.new(value: series.value)
+            )
+          when :summary
+            Io::Prometheus::Client::Metric.new(
+              label: labels,
+              summary: Io::Prometheus::Client::Summary.new(
+                sample_count: series.value.count,
+                sample_sum: series.value.sum
+              )
+            )
+          when :histogram
+            buckets = series.value.cumulative_buckets.map do |bound, count|
+              Io::Prometheus::Client::Bucket.new(
+                upper_bound: bound,
+                cumulative_count: count
+              )
+            end
+            Io::Prometheus::Client::Metric.new(
+              label: labels,
+              histogram: Io::Prometheus::Client::Histogram.new(
+                sample_count: series.value.count,
+                sample_sum: series.value.sum,
+                bucket: buckets
+              )
+            )
+          when :native_histogram
+            nv = series.value
+            pos_spans, pos_deltas = build_spans_deltas(nv.positive_buckets)
+            neg_spans, neg_deltas = build_spans_deltas(nv.negative_buckets)
+
+            Io::Prometheus::Client::Metric.new(
+              label: labels,
+              histogram: Io::Prometheus::Client::Histogram.new(
+                sample_count: nv.count,
+                sample_sum: nv.sum,
+                schema: nv.schema,
+                zero_threshold: nv.zero_threshold,
+                zero_count: nv.zero_count,
+                positive_span: pos_spans,
+                positive_delta: pos_deltas,
+                negative_span: neg_spans,
+                negative_delta: neg_deltas
+              )
+            )
+          end
+        end
+
+        # Build BucketSpan and sint64 delta arrays from ascending [index, count] pairs.
+        # Worked example: [[1, 3], [2, 1], [5, 4]] ->
+        #   spans: [{offset: 1, length: 2}, {offset: 2, length: 1}]
+        #   deltas: [3, -2, 3]
+        private_class_method def self.build_spans_deltas(buckets)
+          return [], [] if buckets.empty?
+
+          spans = []
+          deltas = []
+          span_offset = nil
+          span_length = 0
+          prev_index = nil
+          prev_count = nil
+
+          buckets.each do |index, count|
+            if prev_index.nil?
+              span_offset = index
+              span_length = 1
+              deltas << count
+            else
+              gap = index - prev_index
+              if gap == 1
+                span_length += 1
+              else
+                spans << Io::Prometheus::Client::BucketSpan.new(offset: span_offset, length: span_length)
+                span_offset = gap - 1
+                span_length = 1
+              end
+              deltas << count - prev_count
+            end
+            prev_index = index
+            prev_count = count
+          end
+
+          spans << Io::Prometheus::Client::BucketSpan.new(offset: span_offset, length: span_length)
+          [spans, deltas]
+        end
+
+        private_class_method def self.encode_frame(message)
+          encoded = message.class.encode(message)
+          encode_varint(encoded.bytesize) << encoded
+        end
+
+        private_class_method def self.encode_varint(value)
+          buffer = String.new
+          loop do
+            byte = value & 0x7f
+            value >>= 7
+            byte |= 0x80 if value.positive?
+            buffer << byte
+            break if value.zero?
+          end
+          buffer
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "fast/prometheus"
+
+module Fast
+  module Prometheus
+    module Formats
+      # Prometheus text exposition format 0.0.4.
+      # Consumes Snapshot value objects; never reads live metrics.
+      module Text
+        CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+        DOC_ESCAPE  = /[\n\\]/
+        DOC_REPLACE = { "\n" => "\\n", "\\" => "\\\\" }.freeze
+
+        LABEL_ESCAPE = /[\n\\"]/
+        LABEL_REPLACE = { "\\" => "\\\\", '"' => '\\"', "\n" => "\\n" }.freeze
+
+        def self.render(snapshot)
+          snapshot.metrics.each_with_object(String.new) do |metric, output|
+            next if metric.type == :native_histogram
+
+            output << "# HELP #{metric.name} #{escape_doc(metric.docstring)}\n"
+            output << "# TYPE #{metric.name} #{metric.type}\n"
+
+            metric.series.each do |series|
+              render_series(output, metric.type, metric.name, series)
+            end
+          end
+        end
+
+        private_class_method def self.render_series(output, type, name, series)
+          case type
+          when :counter, :gauge
+            metric_line(output, name, series.labels, series.value)
+          when :histogram
+            histogram_lines(output, name, series.labels, series.value)
+          when :summary
+            summary_lines(output, name, series.labels, series.value)
+          end
+        end
+
+        private_class_method def self.escape_doc(string)
+          return string unless DOC_ESCAPE.match?(string)
+
+          string.gsub(DOC_ESCAPE, DOC_REPLACE)
+        end
+
+        private_class_method def self.escape_label(string)
+          string = string.to_s
+          return string unless LABEL_ESCAPE.match?(string)
+
+          string.gsub(LABEL_ESCAPE, LABEL_REPLACE)
+        end
+
+        private_class_method def self.format_labels(labels)
+          return "" if labels.empty?
+
+          output = String.new("{")
+          labels.each do |key, value|
+            output << "#{key}=\"#{escape_label(value)}\""
+            output << ","
+          end
+          output.chop!
+          output << "}"
+          output
+        end
+
+        private_class_method def self.metric_line(output, name, labels, value)
+          output << "#{name}#{format_labels(labels)} #{value}\n"
+        end
+
+        private_class_method def self.histogram_lines(output, name, labels, value)
+          value.cumulative_buckets.each do |boundary, count|
+            le = boundary.infinite? ? "+Inf" : boundary.to_s
+            metric_line(output, "#{name}_bucket", labels.merge("le" => le), count)
+          end
+
+          metric_line(output, "#{name}_sum", labels, value.sum)
+          metric_line(output, "#{name}_count", labels, value.count)
+        end
+
+        private_class_method def self.summary_lines(output, name, labels, value)
+          metric_line(output, "#{name}_sum", labels, value.sum)
+          metric_line(output, "#{name}_count", labels, value.count)
+        end
+      end
+    end
+  end
+end

data/lib/fast/prometheus/gauge.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "metric"
+
+module Fast
+  module Prometheus
+    # Gauge — an instantaneous value that can go up or down.
+    class Gauge < Metric
+      def type
+        :gauge
+      end
+
+      def set(value, labels: {})
+        raise ArgumentError, "value must be a numeric" unless value.is_a?(Numeric)
+
+        key = resolve(labels)
+        store.synchronize { store[key] = value.to_f }
+      end
+
+      def increment(by: 1, labels: {})
+        raise ArgumentError, "by must be a numeric" unless by.is_a?(Numeric)
+        return if by.zero?
+
+        key = resolve(labels)
+        store.synchronize { store[key] = (store[key] || 0.0) + by.to_f }
+      end
+
+      def decrement(by: 1, labels: {})
+        raise ArgumentError, "by must be a numeric" unless by.is_a?(Numeric)
+        return if by.zero?
+
+        key = resolve(labels)
+        store.synchronize { store[key] = (store[key] || 0.0) - by.to_f }
+      end
+    end
+  end
+end