puma-plugin-telemetry 1.1.0

data/lib/puma/plugin/telemetry.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'puma'
+require 'puma/plugin'
+
+require 'puma/plugin/telemetry/version'
+require 'puma/plugin/telemetry/data'
+require 'puma/plugin/telemetry/targets/datadog_statsd_target'
+require 'puma/plugin/telemetry/targets/io_target'
+require 'puma/plugin/telemetry/config'
+
+module Puma
+  class Plugin
+    # Telemetry plugin for puma, supporting:
+    #
+    # - multiple targets, decide where to push puma telemetry information, i.e. datadog, cloudwatch, logs
+    # - filtering, select which metrics are interesting for you, extend when necessery
+    #
+    module Telemetry
+      class Error < StandardError; end
+
+      class << self
+        attr_writer :config
+
+        def config
+          @config ||= Config.new
+        end
+
+        def configure
+          yield(config)
+        end
+
+        def build(launcher = nil)
+          socket_telemetry(puma_telemetry, launcher)
+        end
+
+        private
+
+        def puma_telemetry
+          stats = ::Puma.stats_hash
+          data_class = if stats.key?(:workers)
+                         ClusteredData
+                       else
+                         WorkerData
+                       end
+          data_class
+            .new(stats)
+            .metrics(config.puma_telemetry)
+        end
+
+        def socket_telemetry(telemetry, launcher)
+          return telemetry if launcher.nil?
+          return telemetry unless config.socket_telemetry?
+
+          telemetry.merge! SocketData.new(launcher.binder.ios, config.socket_parser)
+                                     .metrics
+
+          telemetry
+        end
+      end
+
+      # Contents of actual Puma Plugin
+      #
+      module PluginInstanceMethods
+        def start(launcher)
+          unless Puma::Plugin::Telemetry.config.enabled?
+            launcher.events.log 'plugin=telemetry msg="disabled, exiting..."'
+            return
+          end
+
+          @launcher = launcher
+          @launcher.events.log 'plugin=telemetry msg="enabled, setting up runner..."'
+
+          in_background do
+            sleep Puma::Plugin::Telemetry.config.initial_delay
+            run!
+          end
+        end
+
+        def run!
+          loop do
+            @launcher.events.debug 'plugin=telemetry msg="publish"'
+
+            call(Puma::Plugin::Telemetry.build(@launcher))
+          rescue Errno::EPIPE
+            # Occurs when trying to output to STDOUT while puma is shutting down
+          rescue StandardError => e
+            @launcher.events.error "plugin=telemetry err=#{e.class} msg=#{e.message.inspect}"
+          ensure
+            sleep Puma::Plugin::Telemetry.config.frequency
+          end
+        end
+
+        def call(telemetry)
+          Puma::Plugin::Telemetry.config.targets.each do |target|
+            target.call(telemetry)
+          end
+        end
+      end
+    end
+  end
+end
+
+Puma::Plugin.create do
+  include Puma::Plugin::Telemetry::PluginInstanceMethods
+end

data/lib/rack/request_queue_time_middleware.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Measures the queue time (= time between receiving the request in downstream
+# load balancer and starting request in ruby process)
+class RequestQueueTimeMiddleware
+  ENV_KEY = 'rack.request_queue_time'
+
+  def initialize(app, statsd:, process: Process)
+    @app = app
+    @statsd = statsd
+    @process = process
+  end
+
+  def call(env)
+    queue_time = measure_queue_time(env)
+
+    report_queue_time(queue_time)
+
+    env[ENV_KEY] = queue_time
+
+    @app.call(env)
+  end
+
+  private
+
+  def measure_queue_time(env)
+    start_time = queue_start(env)
+
+    return unless start_time
+
+    queue_time = request_start.to_f - start_time.to_f
+
+    queue_time unless queue_time.negative?
+  end
+
+  # Get the content of the x-amzn-trace-id header, the epoch time in seconds.
+  # see also: https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-request-tracing.html
+  def queue_start(env)
+    value = env['HTTP_X_AMZN_TRACE_ID']
+    value&.split('Root=')&.last&.split('-')&.fetch(1)&.to_i(16)
+  end
+
+  def request_start
+    @process.clock_gettime(Process::CLOCK_REALTIME)
+  end
+
+  def report_queue_time(queue_time)
+    return if queue_time.nil?
+
+    @statsd.timing('queue.time', queue_time)
+
+    return unless defined?(Datadog) && Datadog.respond_to?(:tracer)
+
+    span = Datadog.tracer.active_root_span
+    span&.set_tag('request.queue_time', queue_time)
+  end
+end

data/puma-plugin-telemetry.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/puma/plugin/telemetry/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'puma-plugin-telemetry'
+  spec.version       = Puma::Plugin::Telemetry::VERSION
+  spec.authors       = ['Leszek Zalewski']
+  spec.email         = ['tnt@babbel.com']
+
+  spec.license       = 'MIT'
+
+  spec.summary     = 'Puma plugin, adding ability to publish various metrics to your prefered targets.'
+  spec.homepage    = 'https://github.com/babbel/puma-plugin-telemetry'
+
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+  spec.metadata['github_repo'] = 'ssh://github.com/babbel/puma-plugin-telemetry'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'puma', '>= 5.0'
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: puma-plugin-telemetry
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Leszek Zalewski
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2022-06-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 
+email:
+- tnt@babbel.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/CODEOWNERS"
+- ".github/workflows/build.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".tool-versions"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- docs/example-datadog_backlog_size.png
+- docs/example-datadog_queue_time.png
+- docs/examples.md
+- lib/puma/plugin/telemetry.rb
+- lib/puma/plugin/telemetry/config.rb
+- lib/puma/plugin/telemetry/data.rb
+- lib/puma/plugin/telemetry/targets/datadog_statsd_target.rb
+- lib/puma/plugin/telemetry/targets/io_target.rb
+- lib/puma/plugin/telemetry/version.rb
+- lib/rack/request_queue_time_middleware.rb
+- puma-plugin-telemetry.gemspec
+homepage: https://github.com/babbel/puma-plugin-telemetry
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/babbel/puma-plugin-telemetry
+  source_code_uri: https://github.com/babbel/puma-plugin-telemetry
+  changelog_uri: https://github.com/babbel/puma-plugin-telemetry/blob/main/CHANGELOG.md
+  github_repo: ssh://github.com/babbel/puma-plugin-telemetry
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.27
+signing_key: 
+specification_version: 4
+summary: Puma plugin, adding ability to publish various metrics to your prefered targets.
+test_files: []