prometheus-client-tracer 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11dbb55ad9c5ce0135dd4376dff72e95b1f6e5ae378e1e4c6de2ce23a4ddc915
+  data.tar.gz: 762b4e6b78aaa60c82c97470a9cf1df136b0e3fe685396df117beee3671c7012
+SHA512:
+  metadata.gz: 6291fbf2dcb56141208005a94df27e22531cd3e7c012551a809ab3287602702d91d8a499a3cea580b3b2b8ef07c677898abdb7c5f0a06296b923652a94e60b66
+  data.tar.gz: ec047172d19516f20a24996adf32ceabb651e03627923e30b2e1ef90e096107f0f123e263cb2ff6325a5cbabfc86a4044a681046c54ebcfcd440c726a76817ea

data/.circleci/config.yml

@@ -0,0 +1,42 @@
+---
+version: 2
+
+references:
+  steps: &steps
+    - checkout
+
+    - type: cache-restore
+      key: prometheus-client-tracer-bundler-{{ checksum "prometheus-client-tracer.gemspec" }}
+
+    - run: gem install bundler -v 2.0.1
+    - run: bundle install --path vendor/bundle
+
+    - type: cache-save
+      key: prometheus-client-tracer-bundler-{{ checksum "prometheus-client-tracer.gemspec" }}
+      paths:
+        - vendor/bundle
+
+    - run: bundle exec rubocop
+    - run: bundle exec rspec
+
+jobs:
+  build-ruby24:
+    docker:
+      - image: ruby:2.4
+    steps: *steps
+  build-ruby25:
+    docker:
+      - image: ruby:2.5
+    steps: *steps
+  build-ruby26:
+    docker:
+      - image: ruby:2.6
+    steps: *steps
+
+workflows:
+  version: 2
+  tests:
+    jobs:
+      - build-ruby24
+      - build-ruby25
+      - build-ruby26

data/.rspec

@@ -0,0 +1 @@
+--require ./spec/spec_helper.rb --color

data/.rubocop.yml

@@ -0,0 +1,25 @@
+---
+inherit_gem:
+  gc_ruboconfig: rubocop.yml
+
+AllCops:
+  TargetRubyVersion: 2.4
+
+Metrics/MethodLength:
+  Max: 15
+
+RSpec/MultipleExpectations:
+  Max: 3
+
+Style/RescueStandardError:
+  Exclude:
+    - "*/**/*_spec.rb"
+
+Naming/UncommunicativeMethodParamName:
+  AllowedNames:
+    # These are the default allowed names, set by Rubocop
+    - io
+    - id
+    # These are some custom names that we want to allow, since they aren't
+    # uncommunicative - they're actually rather meaningful!
+    - as

data/.ruby-version

@@ -0,0 +1 @@
+2.6.2

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,61 @@
+PATH
+  remote: .
+  specs:
+    prometheus-client-tracer (1.0.0)
+      prometheus-client (~> 0.10.0.alpha)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    gc_ruboconfig (2.4.0)
+      rubocop (>= 0.70)
+      rubocop-rspec (>= 1.33.0)
+    jaro_winkler (1.5.3)
+    method_source (0.9.2)
+    parallel (1.17.0)
+    parser (2.6.3.0)
+      ast (~> 2.4.0)
+    prometheus-client (0.10.0.pre.alpha.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    rainbow (3.0.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.2)
+    rubocop (0.72.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.6)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 1.7)
+    rubocop-rspec (1.33.0)
+      rubocop (>= 0.60.0)
+    ruby-progressbar (1.10.1)
+    unicode-display_width (1.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  gc_ruboconfig (= 2.4.0)
+  prometheus-client-tracer!
+  pry (~> 0.10)
+  rspec (~> 3.8)
+
+BUNDLED WITH
+   2.0.1

data/README.md

@@ -0,0 +1,64 @@
+# prometheus-client-tracer-ruby [![CircleCI](https://circleci.com/gh/lawrencejones/prometheus-client-tracer-ruby.svg?style=svg)](https://circleci.com/gh/lawrencejones/prometheus-client-tracer-ruby)
+
+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 massive
+increment at the end.
+
+This means you can trust your metrics will be accurate, even if the operations
+you're measuring far exceed your scrape duration.
+
+## Why?
+
+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:
+
+```ruby
+def run
+  start = Time.now
+  long_running_task
+  metric.increment(by: start - Time.now)
+end
+```
+
+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.
+
+To avoid this time of measurement bias, this commit introduces 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, the Prometheus client initialises a global tracer in the same vein
+as the global registry. Most users are going to want to use a tracer without
+initialising a handle in their own code, and can do so like this:
+
+```ruby
+def run
+  Prometheus::Client.trace(metric, { worker: 1 }) do
+    long_running_task
+  end
+end
+```
+
+By default, users who do this will see their metrics update just as frequently
+as the original implementation. For the incremental measurement to work, they
+must use a TraceCollector to trigger a collection just prior to serving metrics:
+
+```ruby
+# By default, collect the global tracer
+use Prometheus::Middleware::TraceCollector
+```

data/lib/prometheus/client/tracer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Prometheus
+  module Client
+    # Most people will want to use a global tracer instead of building their own, similar
+    # to how most will use the global metrics registry.
+    def self.tracer
+      @tracer ||= Tracer.new
+    end
+
+    # Delegate to the Tracer.
+    def self.trace(metric, labels = {}, &block)
+      tracer.trace(metric, labels, &block)
+    end
+
+    # For metrics that track durations over the course of long-running tasks, we need to
+    # ensure the metric is updated gradually while they execute instead of right at the
+    # end. This class is used to track on-going 'traces', records of tasks starting and
+    # stopping, and exposes a method `collect` that will update the associated metric with
+    # the time elapsed since the last `collect`.
+    class Tracer
+      Trace = Struct.new(:metric, :labels, :time)
+
+      def initialize
+        @lock = Mutex.new
+        @traces = []
+      end
+
+      # Start and manage the life of a trace. Pass a long-running block to this method to
+      # ensure the associated metric is updated gradually throughout the execution.
+      def trace(metric, labels = {})
+        start(metric, labels)
+        yield
+      ensure
+        stop(metric, labels)
+      end
+
+      # Update currently traced metrics- this will increment all on-going traces with the
+      # delta of time between the last update and now. This should be called just before
+      # serving a /metrics request.
+      def collect(traces = @traces)
+        @lock.synchronize do
+          now = monotonic_now
+          traces.each do |trace|
+            time_since = [now - trace.time, 0].max
+            trace.time = now
+            trace.metric.increment(
+              by: time_since,
+              labels: trace.labels,
+            )
+          end
+        end
+      end
+
+      private
+
+      def start(metric, labels = {})
+        @lock.synchronize { @traces << Trace.new(metric, labels, monotonic_now) }
+      end
+
+      def stop(metric, labels = {})
+        matching = nil
+        @lock.synchronize do
+          matching, @traces = @traces.partition do |trace|
+            trace.metric == metric && trace.labels == labels
+          end
+        end
+
+        collect(matching)
+      end
+
+      # We're doing duration arithmetic which should make use of monotonic clocks, to
+      # avoid changes to the system time from affecting our metrics.
+      def monotonic_now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/prometheus/middleware/trace_collector.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "prometheus/client"
+
+module Prometheus
+  module Middleware
+    # This class integrates with a Prometheus::Client::Tracer to update associated metric
+    # traces just prior to serving metrics. By default, this will collect traces on the
+    # global Client tracer.
+    class TraceCollector
+      def initialize(app, options = {})
+        @app = app
+        @tracer = options[:tracer] || Client.tracer
+      end
+
+      def call(env)
+        @tracer.collect
+        @app.call(env)
+      end
+    end
+  end
+end

data/prometheus-client-tracer.gemspec

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+Gem::Specification.new do |spec|
+  spec.name          = "prometheus-client-tracer"
+  spec.version       = "1.0.0"
+  spec.summary       = "Tracer for accurate duration tracking with Prometheus metrics"
+  spec.authors       = %w[me@lawrencejones.dev]
+  spec.homepage      = "https://github.com/lawrencejones/prometheus-client-tracer"
+  spec.email         = %w[me@lawrencejones.dev]
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 2.4"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.test_files    = spec.files.grep(%r{^spec/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "prometheus-client", "~> 0.10.0.alpha"
+
+  spec.add_development_dependency "gc_ruboconfig", "= 2.4.0"
+  spec.add_development_dependency "pry", "~> 0.10"
+  spec.add_development_dependency "rspec", "~> 3.8"
+end

data/spec/prometheus/client/tracer_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "timeout"
+
+# rubocop:disable RSpec/InstanceVariable
+describe Prometheus::Client::Tracer do
+  subject(:tracer) { described_class.new }
+
+  let(:metric) do
+    Prometheus::Client::Counter.new(:counter, docstring: "example", labels: %i[worker])
+  end
+
+  describe ".trace" do
+    # These tests try stubbing timing logic. Instead of using let's, we use a test
+    # instance variable @now to represent the current time, as returned by a monotonic
+    # clock system call.
+    #
+    # The #monotonic_now method of the tracer is stubbed to always return the current
+    # value of @now, and tests can manipulate time by advancing that instance variable.
+    #
+    # The tracer is normally passed a block that manipulates @now.
+    subject(:trace) { tracer.trace(metric, labels, &trace_block) }
+
+    let(:labels) { { worker: 1 } }
+    let(:trace_block) { -> { @now += 1.0 } }
+
+    before do
+      @now = 0.0 # set initial time
+      allow(tracer).to receive(:monotonic_now) { @now }
+    end
+
+    it "increments metric with elapsed duration" do
+      expect { trace }.to change { metric.values[labels] }.by(1.0)
+    end
+
+    context "when .collect is called during a trace" do
+      let(:latch) { Mutex.new }
+      let(:trace_block) do
+        -> { latch.synchronize { @now += 1.0 } }
+      end
+
+      # rubocop:disable RSpec/ExampleLength
+      it "increments metric with incremental duration" do
+        latch.lock # acquire the lock, trace should now block
+        trace_thread = Thread.new do
+          trace # will block until latch is released
+        end
+
+        # We need to block until the trace_thread has actually begun, otherwise we'll
+        # never be able to guarantee the trace was started at now = 0.0, even if this
+        # should happen almost immediately.
+        Timeout.timeout(1) { sleep(0.01) until tracer.collect.any? }
+
+        # Advance the clock by 0.5s
+        @now += 0.5
+
+        # If we now collect, the metric should be incremented by the elapsed time (0.5s)
+        expect { tracer.collect }.to change { metric.values[labels] }.by(0.5)
+
+        # Collect once more should leave the metric unchanged, as no time has passed since
+        # the last collect
+        expect { tracer.collect }.to change { metric.values[labels] }.by(0.0)
+
+        # Unlocking the latch and allowing the trace thread to complete will execute the
+        # final part of a trace, which should update the metric with time elapsed. The
+        # trace thread advances time by 1s right before it ends, so we expect to update
+        # the metric by 1s.
+        #
+        # A bug would be if we incremented the metric by the time since our trace started
+        # and when it ended, which in total is 1.5s. This would suggest we never reset the
+        # trace clock when calling collect.
+        expect do
+          latch.unlock
+          trace_thread.join(1)
+          trace_thread.kill # in case thread misbehaves
+        end.to change { metric.values[labels] }.by(1.0)
+      end
+      # rubocop:enable RSpec/ExampleLength
+    end
+  end
+end
+# rubocop:enable RSpec/InstanceVariable

data/spec/prometheus/middleware/trace_collector_spec.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+describe Prometheus::Middleware::TraceCollector do
+  subject(:collector) { described_class.new(app, options) }
+
+  let(:app) { instance_double(Proc, call: []) }
+  let(:options) { { tracer: tracer } }
+  let(:tracer) { Prometheus::Client::Tracer.new }
+
+  describe ".call" do
+    subject(:call) { collector.call({}) }
+
+    # The most basic of tests, just verifying the tracer is invoked. We rely on the tests
+    # for the tracer to validate #collect works correctly.
+    it "calls tracer.collect, then the original app" do
+      expect(tracer).to receive(:collect).and_call_original
+      expect(app).to receive(:call)
+
+      call
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require "prometheus/client"
+require "prometheus/client/tracer"
+require "prometheus/middleware/trace_collector"

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification
+name: prometheus-client-tracer
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- me@lawrencejones.dev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-07-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prometheus-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0.alpha
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.10.0.alpha
+- !ruby/object:Gem::Dependency
+  name: gc_ruboconfig
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 2.4.0
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.10'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+description: 
+email:
+- me@lawrencejones.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".circleci/config.yml"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- README.md
+- lib/prometheus/client/tracer.rb
+- lib/prometheus/middleware/trace_collector.rb
+- prometheus-client-tracer.gemspec
+- spec/prometheus/client/tracer_spec.rb
+- spec/prometheus/middleware/trace_collector_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/lawrencejones/prometheus-client-tracer
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Tracer for accurate duration tracking with Prometheus metrics
+test_files:
+- spec/prometheus/client/tracer_spec.rb
+- spec/prometheus/middleware/trace_collector_spec.rb
+- spec/spec_helper.rb