prometheus-client-ruby: a Ruby metric registry with Rack exporters and Pushgateway support

A metric registry that Prometheus scrapes over HTTP

The prometheus-client gem is described as a suite of instrumentation metric primitives for Ruby that can be exposed through a HTTP interface, intended to be used together with a Prometheus server. The unit of work is a registry, and the registry holds metric objects that the application updates as it runs. The library is a client library, not a server: it produces the data, and a Prometheus server does the storing, querying and alerting. The audience is Ruby application developers who already run Prometheus and want their counters, gauges and histograms in the standard format, and who would otherwise be hand-rolling a text endpoint. The README also points to an integrated example application under examples/rack for further instructions and scripts to get started, and the repository ships a COMPATIBILITY.md alongside UPGRADING.md, which tells you this library is versioned with some care around breaking changes.

Installing the gem and registering a first counter

Installation has two documented paths. For a global installation the README says to run gem install prometheus-client. For a Bundler based project, the instruction is to add gem "prometheus-client" to the Gemfile and then run bundle install afterwards. The first use is short: require the library, ask for the default registry, create a metric object, register it, and start incrementing it. There is a helper on the registry that does the create and register in one call, which the README shows as an equivalent alternative to the two-step version:

require 'prometheus/client'

# returns a default registry
prometheus = Prometheus::Client.registry

# create a new counter metric
http_requests = Prometheus::Client::Counter.new(:http_requests, docstring: 'A counter of HTTP requests made')
# register the metric
prometheus.register(http_requests)

# equivalent helper function
http_requests = prometheus.counter(:http_requests, docstring: 'A counter of HTTP requests made')

# start using the counter
http_requests.increment

The docstring argument is not decoration: the exposition endpoint serves it as the metric help text, so it is the place to record what a counter actually counts. Labels are declared at construction time and supplied at call time, which keeps the set of label values bounded by the code rather than by whatever a request happens to contain.

Two Rack middlewares, one endpoint, and gzip recommended

The Rack integration comes as two separate middlewares, and the README is clear about the split. The Exporter exposes a metrics HTTP endpoint to be scraped by a Prometheus server, and the Collector traces all HTTP requests, which is what produces the request counters and duration histograms without instrumenting handlers by hand. Order matters in a config.ru: the Collector should sit above the Exporter so request metrics are collected before the endpoint is served. The README also states that it is highly recommended to enable gzip compression for the metrics endpoint, for example by including the Rack::Deflater middleware, which is the first line of the example:

# config.ru

require 'rack'
require 'prometheus/middleware/collector'
require 'prometheus/middleware/exporter'

use Rack::Deflater
use Prometheus::Middleware::Collector
use Prometheus::Middleware::Exporter

run ->(_) { [200, {'content-type' => 'text/html'}, ['OK']] }

After starting the server the README points at the metrics endpoint at http://localhost:5123/metrics, which is the URL to check first: if that page lists your metric names with their help text, the wiring is correct. The port is the Rack default in the example, so a deployment on another port needs the Prometheus scrape configuration to match whatever the application actually binds.

Pushing to a Pushgateway from batch jobs

Not every Ruby process can be scraped. A cron job that runs for a minute and exits leaves nothing for a Prometheus server to poll, which is the case the Pushgateway exists for, and the gem supports it directly. The client pushes the registry state, and the README documents three operations: add, which adds the current registry contents, replace, which completely replaces the metrics under the given grouping key, removing anything present in the gateway but not in the registry, and delete, which removes everything previously pushed under that key. A grouping key uniquely identifies a job instance and gateway, and the README warns that labels used in the grouping key must not conflict with labels set on the metrics being pushed, because an error is raised if they do:

require 'prometheus/client'
require 'prometheus/client/push'

registry = Prometheus::Client.registry
# ... register some metrics, set/increment/observe/etc. their values

# push the registry state to the default gateway
Prometheus::Client::Push.new(job: 'my-batch-job').add(registry)

TLS and HTTP basic authentication are both supported, so the gateway can sit behind a certificate and a password. The replace and delete methods are also documented with a pointer to the Pushgateway PUT method explanation upstream, which is worth reading before using replace, since it can delete data that another instance wrote.

Why basic auth credentials are refused inside the gateway URL

One design decision is unusual enough to be worth reading carefully. By design, Prometheus::Client::Push does not read credentials for HTTP basic authentication when they are passed in the gateway URL with the user:[email protected] syntax, and the README says it raises an error if they are supplied that way. The reason given is URL encoding: with that syntax the username and password have to follow the usual rules for URL encoding of characters under RFC 3986. Rather than pushing that burden onto users, the library takes credentials through a separate method that imposes no encoding requirement:

push = Prometheus::Client::Push.new(job: "my-job", gateway: "http://localhost:9091")
push.basic_auth("user", "password")

The practical effect for an operator is that a password containing a colon, an at sign or a percent sign will not break the push, which is the whole point of the split. It also means configuration code that builds a gateway URL from configuration values has to be adjusted, since credentials in the URL are now an error rather than a convenience.

Four metric types, and the limits of Summary

The library supports four metric types, and the README describes each in one line. A counter exposes a sum or tally of things, and is incremented either by one or by a given value, with labels supplied at each call. A gauge exposes an instantaneous value or a snapshot of one, and can be set, incremented or decremented. A histogram samples observations, usually request durations or response sizes, and counts them in configurable buckets while also providing a sum of all observed values. Histograms get default buckets of [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10], and you can set your own explicitly or generate regular spacing with the linear_buckets and exponential_buckets methods. Summary is the weak point: it is an accumulator for samples that captures numeric data and is meant to provide an efficient percentile calculation mechanism, but for now only sum and total, the count of observations, are supported, with no actual quantiles.

Version 5.0.0, an Apache licence, and the upgrade notes

The maintenance picture is that of a library with a recent major version and a gap in the release history before it. The visible tags are v5.0.0 on 2026-10-04, v4.2.5 on 2025-07-05 and v4.2.4 on 2025-02-02, so the jump from 4.2.5 to 5.0.0 spans more than a year and probably carries breaking changes. The repository is not archived and the last push was on 2026-10-10. It also ships files that tell you how to move: UPGRADING.md for version transitions, COMPATIBILITY.md for supported Ruby and Prometheus versions, SECURITY.md for the reporting process, MAINTAINERS.md, a CHANGELOG.md, a CODE_OF_CONDUCT.md, and a NOTICE file alongside the LICENSE. The licence is Apache-2.0, which is permissive, and the NOTICE file is there because that licence expects certain attributions to be preserved when the software is redistributed. Reading UPGRADING.md before pulling v5.0.0 into an existing service is the first concrete step, because the tag gap is exactly where breaking changes hide.

Editorial conclusion

prometheus-client-ruby suits a Rack or plain Ruby service that wants to publish Prometheus metrics without writing the exposition format by hand, and that can live with a summary type that only exposes a sum and a count. It does not suit a team needing percentile queries in Ruby, because the README states that only sum and total are supported for summaries. Verify first that your Prometheus server can reach the /metrics endpoint on port 5123 in your deployment, then read UPGRADING.md and COMPATIBILITY.md before moving to v5.0.0, released on 2026-10-04.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. prometheus/client_ruby on GitHub
4. README
5. Releases