prometheus-client-tracer 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11dbb55ad9c5ce0135dd4376dff72e95b1f6e5ae378e1e4c6de2ce23a4ddc915
-  data.tar.gz: 762b4e6b78aaa60c82c97470a9cf1df136b0e3fe685396df117beee3671c7012
+  metadata.gz: 79f6efb3f1967459a218c40e8cd89854231995138ed238d3d323e901d7a52922
+  data.tar.gz: 3253ed69867af1140f9390944692d32ccecb22766342d81409be0185a10f2f19
 SHA512:
-  metadata.gz: 6291fbf2dcb56141208005a94df27e22531cd3e7c012551a809ab3287602702d91d8a499a3cea580b3b2b8ef07c677898abdb7c5f0a06296b923652a94e60b66
-  data.tar.gz: ec047172d19516f20a24996adf32ceabb651e03627923e30b2e1ef90e096107f0f123e263cb2ff6325a5cbabfc86a4044a681046c54ebcfcd440c726a76817ea
+  metadata.gz: ec656afeb632da0716cbba505b9fb0074fb068ce041ae08fcbf9c5392351e2ba766e63e9690a7a53b163fa8688c8dc614dee73deb48f3921755c2330c254b04f
+  data.tar.gz: acaa90edcd32797f96ce46f0550ec785eddf9516792f2e4f40471eb949e39cfcfa8356723e69ec9c4da297e8f95e5969964524220c790cbcdd43f431b2cb5a66

data/.gitignore

@@ -0,0 +1 @@
+/prometheus-client-tracer-*.gem

data/.rubocop.yml

@@ -5,6 +5,9 @@ inherit_gem:
 AllCops:
   TargetRubyVersion: 2.4
 
+Style/ParallelAssignment:
+  Enabled: false
+
 Metrics/MethodLength:
   Max: 15
 

data/Gemfile.lock

@@ -2,7 +2,7 @@ PATH
   remote: .
   specs:
     prometheus-client-tracer (1.0.0)
-      prometheus-client (~> 0.10.0.alpha)
+      prometheus-client (~> 1.0)
 
 GEM
   remote: https://rubygems.org/
@@ -18,7 +18,7 @@ GEM
     parallel (1.17.0)
     parser (2.6.3.0)
       ast (~> 2.4.0)
-    prometheus-client (0.10.0.pre.alpha.2)
+    prometheus-client (1.0.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
       method_source (~> 0.9.0)
@@ -45,6 +45,7 @@ GEM
       unicode-display_width (>= 1.4.0, < 1.7)
     rubocop-rspec (1.33.0)
       rubocop (>= 0.60.0)
+    ruby-prof (0.18.0)
     ruby-progressbar (1.10.1)
     unicode-display_width (1.6.0)
 
@@ -56,6 +57,7 @@ DEPENDENCIES
   prometheus-client-tracer!
   pry (~> 0.10)
   rspec (~> 3.8)
+  ruby-prof (~> 0.18)
 
 BUNDLED WITH
    2.0.1

data/README.md

@@ -1,13 +1,16 @@
 # 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)
 
+https://blog.lawrencejones.dev/incremental-measurement/
+
 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
+that occur while the operation is in process, instead of applying one large
 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.
+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:
+https://github.com/prometheus/client_ruby/pull/135
 
 ## Why?
 
@@ -30,8 +33,21 @@ 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
+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](res/bias-0_1-1_0.png)
+
+As soon as job duration increases, the bias becomes significant, and the graph
+starts departing from reality:
+
+![Work per worker with long-running jobs](res/bias-0_1-30_0.png)
+
+## How?
+
+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.
@@ -42,9 +58,9 @@ 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:
+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:
 
 ```ruby
 def run
@@ -54,9 +70,10 @@ def run
 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:
+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:
 
 ```ruby
 # By default, collect the global tracer

data/exe/benchmark_tracer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# This file can be used to validate the performance of the tracer is not incomparable to a
+# naive tracing implementation. The performance will degrade linearly with the number of
+# on-going traces, however a modern i7 can achieve trace throughput:
+#
+#   naive: 333k/s
+#   trace,   0 on-going: 233k/s
+#   trace,   5 on-going: 216k/s
+#   trace,  25 on-going: 155k/s
+#   trace, 100 on-going: 84k/s
+#
+# While this seems more than reasonable performance for almost any use case, consider
+# using multiple tracers if this does become a problem.
+
+require "benchmark"
+
+require "prometheus/client"
+require "prometheus/client/tracer"
+
+counter = Prometheus::Client::Counter.new(
+  :counter, docstring: "example", labels: %i[worker]
+)
+another_counter = Prometheus::Client::Counter.new(
+  :counter_another, docstring: "another example", labels: %i[]
+)
+
+def trace(metric, labels = {})
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yield
+ensure
+  metric.increment(
+    by: Process.clock_gettime(Process::CLOCK_MONOTONIC) - start,
+    labels: labels,
+  )
+end
+
+n_string, n_concurrent_traces_string, = ARGV
+n, n_concurrent_traces = [n_string.to_i, n_concurrent_traces_string.to_i]
+
+n_concurrent_traces.times do
+  Prometheus::Client.tracer.send(:start, another_counter, {})
+end
+
+Benchmark.bm(7) do |x|
+  x.report("naive:") { n.times { trace(counter, worker: 1) { nil } } }
+  x.report("trace:") do
+    n.times { Prometheus::Client.tracer.trace(counter, worker: 1) { nil } }
+  end
+end

data/prometheus-client-tracer.gemspec

@@ -5,7 +5,7 @@ $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.version       = "1.1.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"
@@ -18,9 +18,10 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^spec/})
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "prometheus-client", "~> 0.10.0.alpha"
+  spec.add_dependency "prometheus-client", "~> 1.0"
 
   spec.add_development_dependency "gc_ruboconfig", "= 2.4.0"
   spec.add_development_dependency "pry", "~> 0.10"
   spec.add_development_dependency "rspec", "~> 3.8"
+  spec.add_development_dependency "ruby-prof", "~> 0.18"
 end

data/spec/prometheus/client/tracer_spec.rb

@@ -21,7 +21,7 @@ describe Prometheus::Client::Tracer do
     # The tracer is normally passed a block that manipulates @now.
     subject(:trace) { tracer.trace(metric, labels, &trace_block) }
 
-    let(:labels) { { worker: 1 } }
+    let(:labels) { { worker: "1" } }
     let(:trace_block) { -> { @now += 1.0 } }
 
     before do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: prometheus-client-tracer
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - me@lawrencejones.dev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-06 00:00:00.000000000 Z
+date: 2020-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prometheus-client
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0.alpha
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0.alpha
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: gc_ruboconfig
   requirement: !ruby/object:Gem::Requirement
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: ruby-prof
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.18'
 description: 
 email:
 - me@lawrencejones.dev
@@ -74,15 +88,19 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
+- ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
 - Gemfile
 - Gemfile.lock
 - README.md
+- exe/benchmark_tracer.rb
 - lib/prometheus/client/tracer.rb
 - lib/prometheus/middleware/trace_collector.rb
 - prometheus-client-tracer.gemspec
+- res/bias-0_1-1_0.png
+- res/bias-0_1-30_0.png
 - spec/prometheus/client/tracer_spec.rb
 - spec/prometheus/middleware/trace_collector_spec.rb
 - spec/spec_helper.rb