Prometheus Ruby Client

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.

Usage

Overview

require'prometheus/client'# returns a default registryprometheus=Prometheus::Client.registry# create a new counter metrichttp_requests=Prometheus::Client::Counter.new(:http_requests,'A counter of HTTP requests made')# register the metricprometheus.register(http_requests)# equivalent helper functionhttp_requests=prometheus.counter(:http_requests,'A counter of HTTP requests made')# start using the counterhttp_requests.increment

Rack middleware

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.rurequire'rack'require'prometheus/middleware/collector'require'prometheus/middleware/exporter'useRack::DeflaterusePrometheus::Middleware::CollectorusePrometheus::Middleware::Exporterrun->(_){[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.

Pushgateway

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 gatewayPrometheus::Client::Push.new('my-batch-job').add(prometheus)# optional: specify the instance name (instead of IP) and gatewayPrometheus::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

Metrics

The following metric types are currently supported.

Counter

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 setcounter.increment({service: 'foo'})# increment by a given valuecounter.increment({service: 'bar'},5)# get current value for a given label setcounter.get({service: 'bar'})# => 5

Gauge

Gauge is a metric that exposes merely an instantaneous value or some snapshot thereof.

gauge=Prometheus::Client::Gauge.new(:room_temperature_celsius,'...')# set a valuegauge.set({room: 'kitchen'},21.534)# retrieve the current value for a given label setgauge.get({room: 'kitchen'})# => 21.534# increment the value (default is 1)gauge.increment({room: 'kitchen'})# => 22.534# decrement the value by a given valuegauge.decrement({room: 'kitchen'},5)# => 17.534

Histogram

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 valuehistogram.observe({service: 'users'},Benchmark.realtime{service.call(arg)})# retrieve the current bucket valueshistogram.get({service: 'users'})# => { 0.005 => 3, 0.01 => 15, 0.025 => 18, ..., 2.5 => 42, 5 => 42, 10 = >42 }

Summary

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 valuesummary.observe({service: 'database'},Benchmark.realtime{service.call()})# retrieve the current quantile valuessummary.get({service: 'database'})# => { 0.5 => 0.1233122, 0.9 => 3.4323, 0.99 => 5.3428231 }

Tests

Install necessary development gems with bundle install and run tests with rspec:

rake