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.
require 'prometheus/client'
# returns a default registry
prometheus = Prometheus::Client.registry
# create a new counter metric
http_requests = Prometheus::Client::Counter.new(:http_requests, 'A counter of HTTP requests made')
# register the metric
prometheus.register(http_requests)
# equivalent helper function
http_requests = prometheus.counter(:http_requests, 'A counter of HTTP requests made')
# start using the counter
http_requests.increment
There are two Rack middlewares available, one to expose a metrics HTTP endpoint to be scraped by a Prometheus server (Exporter) and one to trace all HTTP requests (Collector).
It's highly recommended to enable gzip compression for the metrics endpoint,
for example by including the Rack::Deflater
middleware.
# config.ru
require 'rack'
require 'prometheus/middleware/collector'
require 'prometheus/middleware/exporter'
use Rack::Deflater, if: ->(_, _, _, body) { body.any? && body[0].length > 512 }
use Prometheus::Middleware::Collector
use Prometheus::Middleware::Exporter
run ->(_) { [200, {'Content-Type' => 'text/html'}, ['OK']] }
Start the server and have a look at the metrics endpoint: http://localhost:5000/metrics.
For further instructions and other scripts to get started, have a look at the integrated example application.
The Ruby client can also be used to push its collected metrics to a Pushgateway. This comes in handy with batch jobs or in other scenarios where it's not possible or feasible to let a Prometheus server scrape a Ruby process.
require 'prometheus/client'
require 'prometheus/client/push'
prometheus = Prometheus::Client.registry
# ... register some metrics, set/increment/observe/etc. their values
# push the registry state to the default gateway
Prometheus::Client::Push.new('my-batch-job').add(prometheus)
# optional: specify the instance name (instead of IP) and gateway
Prometheus::Client::Push.new(
'my-job', 'instance-name', 'http://example.domain:1234').add(prometheus)
# If you want to replace any previously pushed metrics for a given instance,
# use the #replace method.
Prometheus::Client::Push.new('my-batch-job', 'instance').replace(prometheus)
# If you want to delete all previously pushed metrics for a given instance,
# use the #delete method.
Prometheus::Client::Push.new('my-batch-job', 'instance').delete
The following metric types are currently supported.
Counter is a metric that exposes merely a sum or tally of things.
counter = Prometheus::Client::Counter.new(:service_requests_total, '...')
# increment the counter for a given label set
counter.increment({ service: 'foo' })
# increment by a given value
counter.increment({ service: 'bar' }, 5)
# get current value for a given label set
counter.get({ service: 'bar' })
# => 5
Gauge is a metric that exposes merely an instantaneous value or some snapshot thereof.
gauge = Prometheus::Client::Gauge.new(:room_temperature_celsius, '...')
# set a value
gauge.set({ room: 'kitchen' }, 21.534)
# retrieve the current value for a given label set
gauge.get({ room: 'kitchen' })
# => 21.534
A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.
histogram = Prometheus::Client::Histogram.new(:service_latency_seconds, '...')
# record a value
histogram.observe({ service: 'users' }, Benchmark.realtime { service.call(arg) })
# retrieve the current bucket values
histogram.get({ service: 'users' })
# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }
Summary, similar to histograms, is an accumulator for samples. It captures Numeric data and provides an efficient percentile calculation mechanism.
summary = Prometheus::Client::Summary.new(:service_latency_seconds, '...')
# record a value
summary.observe({ service: 'database' }, Benchmark.realtime { service.call() })
# retrieve the current quantile values
summary.get({ service: 'database' })
# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }
Install necessary development gems with bundle install
and run tests with
rspec:
rake