Skip to content
Tracer for accurately tracking long-running operations with Prometheus metrics
Branch: master
Clone or download
Latest commit 24c39af Jul 11, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci CircleCI Jul 4, 2019
exe Fix typo Jul 11, 2019
lib/prometheus Initial commit Jul 4, 2019
res Expand README Jul 10, 2019
spec Initial commit Jul 4, 2019
.gitignore Add blog post link to readme Jul 6, 2019
.rspec Initial commit Jul 4, 2019
.rubocop.yml exe/benchmark-tracer.rb Jul 10, 2019
Gemfile Initial commit Jul 4, 2019
Gemfile.lock exe/benchmark-tracer.rb Jul 10, 2019 Expand README Jul 10, 2019
prometheus-client-tracer.gemspec exe/benchmark-tracer.rb Jul 10, 2019

prometheus-client-tracer-ruby CircleCI

This gem provides an interface for tracing long-running duration measurements using the Prometheus client. By updating the associated metric as part of the Prometheus /metrics endpoint, the increment is spread evenly over the scrapes that occur while the operation is in process, instead of applying one large increment at the end.

If you find this useful and would prefer it to live within the official Prometheus Ruby client, please drop your feedback as a comment here:


One of the most common observability requirements is to trace the amount of time spent running a job or task. This information is useful in the context of when this time was spent. The typical implementation of such a measurement might be:

def run
  start =
  metric.increment(by: start -

The metric tracking duration is incremented only once the task has finished. If the task took > Prometheus scrape interval, perhaps by a significant factor (say 1hr vs the normal 15s scrape interval), then the metric is incremented by a huge value only after the task has finished. Graphs visualising how time is spent will show no activity while the task was running and then an impossible burst just as things finish.

When jobs run quickly, your graphs will look reasonable. An example with ten workers constantly working small jobs, each worker reports one second of work per second, as the world should be.

Work per worker with small jobs

As soon as job duration increases, the bias becomes significant, and the graph starts departing from reality:

Work per worker with long-running jobs


To avoid this time of measurement bias, this gem provides a metric tracer that manages updating metrics associated with long-running tasks. Users will begin a trace, do work, and while the work is on-going any calls to the tracer collect method will incrementally update the associated metric with elapsed time.

This is a game-changer in terms of making metrics usable, removing a huge source of uncertainty when interpreting metric measurements. The implementation of the tracer is thread safe and designed to be as lightweight as possible- it should hopefully provide no performance hit and be preferable for tracing durations of most lengths, provided you don't exceed hundreds of on-going traces.

For easy use, we patch the Prometheus client with a global tracer, following the example of the global registry. Most users will want to use tracers without initialising one in their own code, and can do so like this:

def run
  Prometheus::Client.trace(metric, { worker: 1 }) do

Without any additional configuration, users who do this will see their metrics update just as frequently as the naive implementation. For the incremental measurement to work, they must use a TraceCollector to trigger a collection just prior to serving metrics:

# By default, collect the global tracer
use Prometheus::Middleware::TraceCollector
You can’t perform that action at this time.