fast-prometheus 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d60578f0bebf141e385a3313c32792c5310dd048a242e8f7b901585b71ab43cb
-  data.tar.gz: cd38790e53ff5680b72e7773b79226fbb25768bf03e4eeeba14fccb280acee6d
+  metadata.gz: cc4b46dd402452acfca0d58f4f3230850c4ef19101f8d84027cc903877451efc
+  data.tar.gz: eb10abc576793f118af30ee6ea4ce44b5339939d5906816b4f92d3e14af64762
 SHA512:
-  metadata.gz: efb05ec4182f3564031b9997bc2ffe840a9846ac0d652a29d6d1f118188de58d6156c49e4db703a8ca65305041bd758406b6bfe56728d767c9850f44e9382d77
-  data.tar.gz: 1063c21987bc816e1e41821e21ca831a8576c69d07c823fc2da1488c5800712ac75aa4360bf69cf04cb0b0c1af708a05468b8ca9b17aec1e31e94e2bdeeb2186
+  metadata.gz: 393888fd071c19df54148a57187c415d3397107a51b96e0d442b5931be691aea0ca23f3570daaf0654b644993f8f5da8ae1b97be8da864c96b01e7948c2f90c9
+  data.tar.gz: 7a842a1b2381f9b43c38a378c676b77d692619d74d6df7ac6ff979a783a041e248a8b7afcd7f2ec3cd569bf5be386500fffbd7efaad2ce729cf8f9bded0c6791

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,75 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-09-19
+
+### Changed
+
+- Requires [fast-protowire](https://github.com/jetpks/fast-protowire) `~> 0.2`,
+  whose encoder writes nested messages in place and allocates nothing per
+  message: the declared-message paths here (family headers, native
+  histograms, OTLP export) get that for free, and the `Wire` primitives the
+  per-series renderer uses append text as bytes with no binary copy on
+  Ruby 3.4+.
+- Benchmarks re-taken on the new dependency and republished on the
+  benchmarks page and in the README.
+
+## [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

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.4x** faster than
+  prometheus-client's; histogram observe is **3.0x** faster and summary observe **3.2x**
+- 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