fast-prometheus 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf50aa0854cf98fd362294bd64ac2f07d04526428b6aa595c50c1058ffc82664
-  data.tar.gz: 66b21fc919d3913bdda5ae6b1aff7b661eb850981a43f54f5928d67aa0dbf16e
+  metadata.gz: 567abd58fbe511ba93717dbec96fa202313d689ed1fb30b765dace0de60d141f
+  data.tar.gz: 6c9cf404e4f7c0b7f54ea65f0f6c009ea488abdbf0bb2e1705d9c8e43e3b3b46
 SHA512:
-  metadata.gz: cb355b90d7dd5dcc885ff0181d87611ef6c39120f613053ed9a95e15988cf04b33959c3289bec698e8c664720a85a567729c8547ad53c427aa88214ba0143868
-  data.tar.gz: 379b37ebbccda56a8c3c7975351f709e138c4928be30ff3a8ccdac991164285db35fe1ce0758630506e36bb68199a311273de47d477b9578dd643ab2a8bc0da7
+  metadata.gz: cc0c6d858de7e4893e84dc615694a1488a84829eefed4511ad8ca445aa2be354f54b382e3edb54c78363bb5b1b4625ae026db395471fc47a49b3e027bbaa1c7e
+  data.tar.gz: 1e0c1751a0ade41579e5932044b37d5cecd4df4324bdcccc97d4886bf62d0569e1f030312645b8872f327ce2ffda25c3c525e77a3fe23022a7de125b30f5aec3

data/AGENTS.md

@@ -9,9 +9,16 @@ 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
+BENCH_QUICK=1 bundle exec ruby benchmark/observe.rb      # observe/get vs prometheus-client, one table
+BENCH_QUICK=1 bundle exec ruby benchmark/exposition.rb   # scrape suite: end to end, by stage, by size, vs google-protobuf
+protoc --proto_path=proto --ruby_out=fixtures/pb proto/metrics.proto proto/opentelemetry/proto/**/*.proto   # regenerate the reference decoders (tests only)
+bundle exec ruby script/scrape_rss.rb --mode server --series 7500   # RSS per scrape, see header
 ```
 
+## Dependencies
+
+- `google-protobuf` is a development dependency only: tests decode the library's output with it (`fixtures/reference.rb`). Runtime protobuf is `fast-protowire`; the message declarations live in `lib/fast/prometheus/formats/metrics_proto.rb` and `lib/fast/prometheus/otlp/proto.rb` and must mirror `proto/`.
+
 ## Style Rules
 
 - 2-space indentation

data/CHANGELOG.md

@@ -7,6 +7,114 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-09-18
+
+### Changed
+
+- Protobuf exposition and OTLP export no longer use `google-protobuf`. The
+  Prometheus client model and the OTLP messages are declared with
+  [fast-protowire](https://github.com/jetpks/fast-protowire), a wire-format
+  library with no native extension: no per-message arenas, no object cache,
+  no descriptor pool. Output is byte-identical (tests decode it with
+  google-protobuf as a development dependency). `Formats::Protobuf.render`
+  encodes each series on its own and appends it to the family's bytes, so a
+  36k-series scrape peaks at roughly the body size instead of ~320 MiB.
+- `OTLP::Mapper#request` returns a `Fast::Prometheus::OTLP::Proto::
+  ExportMetricsServiceRequest`; the gRPC interface's response class is
+  `Fast::Prometheus::OTLP::Proto::ExportMetricsServiceResponse`.
+- New `script/scrape_rss.rb`: an RSS-per-scrape harness for the exposition
+  path (forked server scraped over keep-alive, or in-process loops).
+- `Formats::Text.render` and `Formats::Protobuf.render` allocate per sample
+  and per series, not per label: text appends every piece straight into the
+  output (one String per sample line, the value), and protobuf writes each
+  series' bytes with `Fast::Protowire::Wire` into one reused scratch buffer,
+  with no message objects. Over 5,200 series x 12 labels a text render went
+  from 100,840 to 10,631 objects and a protobuf render from 342,705 to 6,165
+  (0.114 s to 0.030 s); in the 36k-series server harness, protobuf+gzip
+  scrapes went from 0.92 s to 0.25 s and text from 0.20 s to 0.08 s.
+- `MetricSnapshot#series` is the metric's store copied under its lock: a
+  frozen `Hash` from each series' label values (an `Array` in `label_names`
+  order) to its value, with `MetricSnapshot#labels(values)` for the
+  `{name => value}` view. The `Series` object and its per-series label Hash
+  are gone, and with them the snapshot's per-series cost: `Registry#collect`
+  over 36,000 series x 12 labels went from 34 ms, 72,056 objects and 19 MiB
+  to 1 ms, 342 objects and the 2 MiB copy. `Metric#snapshot_values` is keyed
+  the same way; `Metric#values` keeps its label-Hash keys. `HistogramValue`,
+  `SummaryValue` and `NativeHistogramValue` are frozen `Struct`s rather than
+  `Data`, since `Data.new` allocates two objects besides the instance;
+  `Histogram#cumulative_buckets` and the native histogram bucket readers
+  return frozen pairs.
+- A bound or unlabeled `increment`/`observe`/`set` allocates nothing (the
+  `labels: {}` default is one shared frozen Hash and the store lock is taken
+  with `yield`, not a captured block); a labeled call allocates only its
+  resolved key. `test/fast/prometheus/allocations.rb` freezes these budgets.
+- `fast-protowire` is resolved from rubygems.org (`~> 0.1`); the
+  sibling-path override is gone from `gems.rb`. Development and the
+  published benchmarks are on Ruby 4.0.7 (`mise.toml`, CI's dev row).
+
+### Added
+
+- `benchmark/exposition.rb`, a scrape benchmark suite: end-to-end scrapes
+  through `Middleware::Exporter` over `Async::HTTP` in every content variant,
+  each stage of a scrape on its own (collect, render, gzip) with objects and
+  malloc bytes, the renderers against `prometheus-client`'s text formatter
+  from 1k to 100k series, and the protobuf renderer against the two
+  google-protobuf encoders this gem used to ship with live native arenas and
+  GC time. `benchmark/observe.rb` reports every metric operation against
+  `prometheus-client` as one table: i/s, speedup and objects per call.
+
+## [0.2.0] - 2026-09-15
+
+### Added
+
+- `Registry#exist?(name)` — true iff a metric is registered under `name`.
+- `Metric#init_label_set(labels)` is now public: it resolves `labels` like any
+  mutator and creates that series at the type's zero value under the store
+  lock, only if it's absent — it never resets a live series.
+- Every metric now seeds a zero-valued series at construction when it's fully
+  bound (no declared labels, or `preset_labels:` covers every declared
+  label); a fully-bound `with_labels` child seeds its own series the same
+  way. A seeded series shows up in `values`, `Registry#collect`, and text/
+  protobuf exposition at zero — for example a freshly registered counter now
+  renders `requests_total 0.0` instead of being absent from scrapes until
+  first incremented. Partially-bound metrics and zero-valued
+  `increment`/`decrement` still seed nothing; `get` still never creates a
+  series.
+- `Gauge#set_to_current_time(labels: {})` — `set(Time.now.to_f, labels:
+  labels)`.
+- `Metric#snapshot_values` — every series' value in its frozen snapshot shape
+  (`HistogramValue`, `SummaryValue`, `NativeHistogramValue`, or the
+  already-frozen `Float` for `Counter`/`Gauge`), keyed by label hash, built
+  under the store lock.
+
+### Changed
+
+- **Breaking:** `Metric` names may now be given as a `String` or a `Symbol`
+  and are normalized to a `Symbol` on construction; `Metric#name` always
+  returns a `Symbol` where it previously echoed back whatever was passed in.
+  `Registry#unregister`, `#get`, `#exist?`, and `#fetch_or_register` accept
+  either form and symbolize it before lookup; `DuplicateMetric` now fires
+  across forms (registering `"requests_total"` after `:requests_total` is
+  already registered raises).
+- **Breaking:** `Metric#label_names` is renamed to `Metric#labels`; the old
+  name no longer exists (no alias). `MetricSnapshot#label_names` is
+  unaffected.
+- **Breaking:** `Histogram#get`/`#values` and `Summary#get`/`#values` now
+  return prometheus-client-shaped hashes instead of the internal
+  `HistogramSlot`/`Summary::Value` storage objects. `Histogram#get` returns a
+  fresh `Hash` keyed by each bucket boundary's `to_s` (ascending), then
+  `"+Inf"`, then `"sum"`, with cumulative `Integer` bucket counts and a
+  `Float` sum; `Summary#get` returns `{ "count" => Integer, "sum" => Float }`.
+  `Histogram#cumulative_buckets`, `#sum`, and `#count` now return zero-valued
+  results for an unobserved series instead of `nil`. `NativeHistogram#get`/
+  `#values` now return the frozen `NativeHistogramValue` snapshot type
+  (previously the internal `NativeHistogram::Slot`), including a zero-valued
+  value for an unobserved series. All of these are fresh copies per call;
+  mutating a returned `Hash` no longer affects the metric.
+- `Fast::Prometheus.registry=` now assigns under the same lock the reader
+  uses, closing a race between a writer and a concurrent reader/memoizing
+  first read.
+
 ## [0.1.0] - 2026-09-11
 
 ### Added

data/README.md

@@ -21,7 +21,7 @@ Or add to your `Gemfile`:
 gem "fast-prometheus"
 ```
 
-`require "fast/prometheus"` loads only the core, with no IO dependencies. The
+`require "fast/prometheus"` loads only the core, with no IO dependencies. Protobuf exposition and OTLP export are built on [fast-protowire](https://github.com/jetpks/fast-protowire) rather than `google-protobuf`, so no native protobuf runtime is loaded either. The
 opt-in surfaces and what each pulls in are listed in
 [the require-path reference](docs/reference/require-paths.md).
 
@@ -76,7 +76,7 @@ under Falcon and scraping it with a real Prometheus, see
 - [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.
+- [Benchmarks](docs/explanation/benchmarks.md) — scrape and observe benchmarks against prometheus-client and google-protobuf, and how to reproduce them.
 
 ## Concurrency
 
@@ -90,13 +90,18 @@ handled it; aggregating across processes is out of scope. See
 
 ## 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):
+Single process, locked, thread-safe by default (`benchmark-ips` and allocation
+comparisons against `prometheus-client` and `google-protobuf`; see
+[the benchmarks page](docs/explanation/benchmarks.md) for the full runs 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
+- A protobuf scrape of 36,000 series renders in **29 objects**, where the
+  `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
+- 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
 
 ## Development
 
@@ -104,6 +109,8 @@ full run and conditions):
 bundle exec sus
 bundle exec rubocop
 E2E_REQUIRED=1 ./integration/run
+BENCH_QUICK=1 bundle exec ruby benchmark/observe.rb      # every metric operation vs prometheus-client
+BENCH_QUICK=1 bundle exec ruby benchmark/exposition.rb   # the scrape suite
 ```
 
 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

@@ -10,7 +10,7 @@ module Fast
         :counter
       end
 
-      def increment(by: 1, labels: {})
+      def increment(by: 1, labels: NO_LABELS)
         raise ArgumentError, "by must be a non-negative numeric" unless by.is_a?(Numeric) && by >= 0
         return if by.zero?
 

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

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "fast/protowire"
+
+module Fast
+  module Prometheus
+    module Formats
+      module Protobuf
+        # The Prometheus client data model (proto/metrics.proto,
+        # io.prometheus.client) declared for the wire. The checked-in proto
+        # is proto3, so scalars have implicit presence and a zero value is
+        # omitted. Only the fields the exposition emits or a scraper reads
+        # back are declared; exemplars and created timestamps ride along as
+        # unknown fields.
+        module Proto
+          MetricType = Fast::Protowire::Enum.define(COUNTER: 0, GAUGE: 1, SUMMARY: 2, UNTYPED: 3, HISTOGRAM: 4,
+                                                    GAUGE_HISTOGRAM: 5)
+
+          class LabelPair < Fast::Protowire::Message
+            field :name, :string, 1
+            field :value, :string, 2
+          end
+
+          class Gauge < Fast::Protowire::Message
+            field :value, :double, 1
+          end
+
+          class Counter < Fast::Protowire::Message
+            field :value, :double, 1
+          end
+
+          class Quantile < Fast::Protowire::Message
+            field :quantile, :double, 1
+            field :value, :double, 2
+          end
+
+          class Summary < Fast::Protowire::Message
+            field :sample_count, :uint64, 1
+            field :sample_sum, :double, 2
+            repeated :quantile, Quantile, 3
+          end
+
+          class Untyped < Fast::Protowire::Message
+            field :value, :double, 1
+          end
+
+          class Bucket < Fast::Protowire::Message
+            field :cumulative_count, :uint64, 1
+            field :upper_bound, :double, 2
+            field :cumulative_count_float, :double, 4
+          end
+
+          class BucketSpan < Fast::Protowire::Message
+            field :offset, :sint32, 1
+            field :length, :uint32, 2
+          end
+
+          class Histogram < Fast::Protowire::Message
+            field :sample_count, :uint64, 1
+            field :sample_sum, :double, 2
+            repeated :bucket, Bucket, 3
+            field :sample_count_float, :double, 4
+            field :schema, :sint32, 5
+            field :zero_threshold, :double, 6
+            field :zero_count, :uint64, 7
+            field :zero_count_float, :double, 8
+            repeated :negative_span, BucketSpan, 9
+            repeated :negative_delta, :sint64, 10
+            repeated :negative_count, :double, 11
+            repeated :positive_span, BucketSpan, 12
+            repeated :positive_delta, :sint64, 13
+            repeated :positive_count, :double, 14
+          end
+
+          class Metric < Fast::Protowire::Message
+            repeated :label, LabelPair, 1
+            field :gauge, Gauge, 2
+            field :counter, Counter, 3
+            field :summary, Summary, 4
+            field :untyped, Untyped, 5
+            field :timestamp_ms, :int64, 6
+            field :histogram, Histogram, 7
+          end
+
+          class MetricFamily < Fast::Protowire::Message
+            field :name, :string, 1
+            field :help, :string, 2
+            field :type, MetricType, 3
+            repeated :metric, Metric, 4
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,97 +1,234 @@
 # frozen_string_literal: true
 
 require "fast/prometheus"
-require_relative "metrics_pb"
+require_relative "metrics_proto"
 
 module Fast
   module Prometheus
     module Formats
+      # Prometheus protobuf exposition: a stream of varint-length-prefixed
+      # MetricFamily messages.
+      #
+      # Each family's header is a declared Proto::MetricFamily; the series
+      # under it are written straight to the wire with Fast::Protowire::Wire,
+      # no LabelPair/Metric/Counter objects, because a scrape's series count
+      # is the one thing here that is large. A series' bytes go into one
+      # scratch buffer reused for the whole render and are copied under the
+      # family's metric tag, so rendering allocates per series only what
+      # Array#pack needs for a double. Native histograms, few and irregular,
+      # still go through Proto::Histogram. Bytes are identical to what the
+      # declared classes (and google-protobuf) produce; the tests check.
       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
+          counter: :COUNTER,
+          gauge: :GAUGE,
+          summary: :SUMMARY,
+          histogram: :HISTOGRAM,
+          native_histogram: :HISTOGRAM
         }.freeze
         private_constant :TYPE_MAP
 
+        # Field tags for the messages written by hand, read off the
+        # declarations so field numbers live in metrics_proto.rb only. All
+        # are one byte (field numbers below 16), which the size arithmetic
+        # below relies on.
+        def self.tag(message_class, field)
+          field = message_class.fields.fetch(field)
+          Fast::Protowire::Wire.tag(field.number, field.wire_type)
+        end
+        private_class_method :tag
+
+        FAMILY_METRIC = tag(Proto::MetricFamily, :metric)
+        METRIC_LABEL = tag(Proto::Metric, :label)
+        METRIC_GAUGE = tag(Proto::Metric, :gauge)
+        METRIC_COUNTER = tag(Proto::Metric, :counter)
+        METRIC_SUMMARY = tag(Proto::Metric, :summary)
+        METRIC_HISTOGRAM = tag(Proto::Metric, :histogram)
+        LABEL_NAME = tag(Proto::LabelPair, :name)
+        LABEL_VALUE = tag(Proto::LabelPair, :value)
+        VALUE = tag(Proto::Counter, :value) # Gauge.value has the same tag
+        SUMMARY_COUNT = tag(Proto::Summary, :sample_count)
+        SUMMARY_SUM = tag(Proto::Summary, :sample_sum)
+        HISTOGRAM_COUNT = tag(Proto::Histogram, :sample_count)
+        HISTOGRAM_SUM = tag(Proto::Histogram, :sample_sum)
+        HISTOGRAM_BUCKET = tag(Proto::Histogram, :bucket)
+        BUCKET_COUNT = tag(Proto::Bucket, :cumulative_count)
+        BUCKET_BOUND = tag(Proto::Bucket, :upper_bound)
+        private_constant :FAMILY_METRIC, :METRIC_LABEL, :METRIC_GAUGE, :METRIC_COUNTER, :METRIC_SUMMARY,
+                         :METRIC_HISTOGRAM, :LABEL_NAME, :LABEL_VALUE, :VALUE, :SUMMARY_COUNT, :SUMMARY_SUM,
+                         :HISTOGRAM_COUNT, :HISTOGRAM_SUM, :HISTOGRAM_BUCKET, :BUCKET_COUNT, :BUCKET_BOUND
+
+        # Tag plus eight bytes: what a double field occupies when sent.
+        DOUBLE_SIZE = 9
+        private_constant :DOUBLE_SIZE
+
+        # One varint-length-prefixed MetricFamily frame per metric.
         def self.render(snapshot)
+          scratch = String.new
           snapshot.metrics.each_with_object(String.new) do |ms, buffer|
-            buffer << encode_frame(build_metric_family(ms))
+            family = encode_metric_family(ms, scratch)
+            Fast::Protowire::Wire.append_varint(buffer, family.bytesize)
+            buffer << family
           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)
+        # A family's bytes are its header (name, help, type) followed by one
+        # metric entry per series, each written into +scratch+ and copied.
+        private_class_method def self.encode_metric_family(metric_snapshot, scratch)
+          header = Proto::MetricFamily.new(name: metric_snapshot.name.name, help: metric_snapshot.docstring,
+                                           type: TYPE_MAP.fetch(metric_snapshot.type))
+          type = metric_snapshot.type
+          names = metric_snapshot.label_names
+          buffer = header.encode
+          metric_snapshot.series.each_pair do |values, value|
+            scratch.clear
+            append_metric(scratch, names, values, value, type)
+            buffer << FAMILY_METRIC
+            Fast::Protowire::Wire.append_varint(buffer, scratch.bytesize)
+            buffer << scratch
           end
+          buffer
+        end
 
+        # Metric: labels (1) then the one value field for the type, in
+        # field-number order as the declared encoder would write them.
+        private_class_method def self.append_metric(out, names, values, value, type)
+          names.each_index { |i| append_label_pair(out, names[i], values[i]) }
           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 :counter then append_scalar_message(out, METRIC_COUNTER, value)
+          when :gauge then append_scalar_message(out, METRIC_GAUGE, value)
+          when :summary then append_summary(out, value)
+          when :histogram then append_histogram(out, value)
           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
-              )
-            )
+            Fast::Protowire::Wire.append_length_delimited(out, METRIC_HISTOGRAM, native_histogram(value).encode)
+          end
+        end
+
+        # LabelPair { string name = 1; string value = 2 }.
+        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
+          out << METRIC_LABEL
+          append_varint(out, 2 + varint_size(name_size) + name_size + varint_size(value_size) + value_size)
+          Fast::Protowire::Wire.append_length_delimited(out, LABEL_NAME, name)
+          Fast::Protowire::Wire.append_length_delimited(out, LABEL_VALUE, value)
+        end
+
+        # Counter / Gauge { double value = 1 }: empty when the value is the
+        # proto3 default (+0.0 exactly; -0.0 and NaN are sent).
+        private_class_method def self.append_scalar_message(out, tag, value)
+          out << tag
+          if omit_double?(value)
+            out << 0
+          else
+            out << DOUBLE_SIZE
+            append_double(out, VALUE, value)
+          end
+        end
+
+        # Summary { uint64 sample_count = 1; double sample_sum = 2 }.
+        private_class_method def self.append_summary(out, value)
+          count = value.count
+          sum = value.sum
+          out << METRIC_SUMMARY
+          append_varint(out, uint_size(SUMMARY_COUNT, count) + double_size(sum))
+          append_uint(out, SUMMARY_COUNT, count)
+          append_double(out, SUMMARY_SUM, sum) unless omit_double?(sum)
+        end
+
+        # Histogram { uint64 sample_count = 1; double sample_sum = 2;
+        # repeated Bucket bucket = 3 } with Bucket { uint64 cumulative_count
+        # = 1; double upper_bound = 2 }. Sizes are summed first, then the
+        # bytes are written, so no bucket is encoded into its own buffer.
+        private_class_method def self.append_histogram(out, value)
+          count = value.count
+          sum = value.sum
+          buckets = value.cumulative_buckets
+          size = uint_size(HISTOGRAM_COUNT, count) + double_size(sum)
+          buckets.each do |bound, cumulative|
+            bucket_size = bucket_size(bound, cumulative)
+            size += 1 + varint_size(bucket_size) + bucket_size
+          end
+
+          out << METRIC_HISTOGRAM
+          append_varint(out, size)
+          append_uint(out, HISTOGRAM_COUNT, count)
+          append_double(out, HISTOGRAM_SUM, sum) unless omit_double?(sum)
+          buckets.each do |bound, cumulative|
+            out << HISTOGRAM_BUCKET
+            append_varint(out, bucket_size(bound, cumulative))
+            append_uint(out, BUCKET_COUNT, cumulative)
+            append_double(out, BUCKET_BOUND, bound) unless omit_double?(bound)
+          end
+        end
+
+        private_class_method def self.bucket_size(bound, cumulative)
+          uint_size(BUCKET_COUNT, cumulative) + double_size(bound)
+        end
+
+        # -- wire pieces ------------------------------------------------------
+
+        private_class_method def self.append_varint(out, value)
+          Fast::Protowire::Wire.append_varint(out, value)
+        end
+
+        # A uint64 field, omitted at zero.
+        private_class_method def self.append_uint(out, tag, value)
+          return if value.zero?
+
+          out << tag
+          append_varint(out, value)
+        end
+
+        private_class_method def self.append_double(out, tag, value)
+          out << tag
+          [value].pack("E", buffer: out)
+        end
+
+        private_class_method def self.uint_size(_tag, value)
+          value.zero? ? 0 : 1 + varint_size(value)
+        end
+
+        private_class_method def self.double_size(value)
+          omit_double?(value) ? 0 : DOUBLE_SIZE
+        end
+
+        # Bytes a non-negative varint takes.
+        private_class_method def self.varint_size(value)
+          size = 1
+          while value > 0x7f
+            value >>= 7
+            size += 1
           end
+          size
+        end
+
+        # Implicit presence: +0.0 is not sent; -0.0 (bitwise different) is.
+        private_class_method def self.omit_double?(value)
+          value.zero? && (1.0 / value).positive?
+        end
+
+        # -- native histograms, through the declared classes ------------------
+
+        private_class_method def self.native_histogram(value)
+          pos_spans, pos_deltas = build_spans_deltas(value.positive_buckets)
+          neg_spans, neg_deltas = build_spans_deltas(value.negative_buckets)
+
+          Proto::Histogram.new(
+            sample_count: value.count,
+            sample_sum: value.sum,
+            schema: value.schema,
+            zero_threshold: value.zero_threshold,
+            zero_count: value.zero_count,
+            positive_span: pos_spans,
+            positive_delta: pos_deltas,
+            negative_span: neg_spans,
+            negative_delta: neg_deltas
+          )
         end
 
         # Build BucketSpan and sint64 delta arrays from ascending [index, count] pairs.
@@ -118,7 +255,7 @@ module Fast
               if gap == 1
                 span_length += 1
               else
-                spans << Io::Prometheus::Client::BucketSpan.new(offset: span_offset, length: span_length)
+                spans << Proto::BucketSpan.new(offset: span_offset, length: span_length)
                 span_offset = gap - 1
                 span_length = 1
               end
@@ -128,26 +265,9 @@ module Fast
             prev_count = count
           end
 
-          spans << Io::Prometheus::Client::BucketSpan.new(offset: span_offset, length: span_length)
+          spans << Proto::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