puma-plugin-telemetry 1.1.6 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c4c03c973b8976fe5c41efaa5837ba7dea8acb62e9fdbc789925928864f60c
-  data.tar.gz: 44d6f8ceb1ad23d0251a59055f0f29b555b4bc74a56ce22722474cb0b9e50603
+  metadata.gz: 967086816efd56c3d2237c21240a41fcc0a7fa28314fc181d4afcd570337ea0c
+  data.tar.gz: e2dd1fdb9ad91c1e07c22304292492fc68b0450c7ef498851f64a067f872b84a
 SHA512:
-  metadata.gz: 07c4c38cade484b8c78c11a63761ed51ab7641ff354d9dab36e3d918a266e92c9a4f477b3b8b0a674776785e089f6a5c29629d24f774076293c268a79043cb6e
-  data.tar.gz: f8dcbd60fcb5b19409483c26b50fd91559bed7e0addddd5a42ddfc1a369a3d8f16a0a3e018a74ea697742dcabcdd3574ee50d2492fb521fa1190d92915937ab9
+  metadata.gz: ffe1e2dba8e463969b8ec987170f233678924ffcf69a6a8d54febe499be623495a95b87326e20bb860745a2842bc2e2fab0a43b03588ad0de75a1711558404e8
+  data.tar.gz: c6d86543aaf25ae6768c10b3c68d8511ab1089a6bb9cb6c60f0a67c38d0f57f1387ff21b8be1a784615e0779a4132d09cd6cf05a5eeeae2424986dd2f72f5a57

data/.rubocop.yml

@@ -8,3 +8,7 @@ AllCops:
 Metrics/BlockLength:
   Exclude:
     - spec/**/*
+
+Metrics/ClassLength:
+  Exclude:
+    - spec/**/*

data/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0]
+
+### Added
+- New `:open_telemetry` target. Metric names get the `puma` prefix by default. Requires the `opentelemetry-metrics-sdk` gem in the consumer project (#30)
+- New `formatter:` options for the IO target: `:json` and `:passthrough` (#25)
+- New `transform:` options for the IO target: `:cloud_watch` and `:passthrough` (#25)
+
+### Changed
+- A custom `formatter:` on the IO target now receives the transformed telemetry. Pass `transform: :passthrough` to get the same telemetry as before (#25)
+
+### Dropped
+- The `Targets::IOTarget::JSONFormatter` constant. Its behavior moved to `Formatters::JSONFormatter` and `Transforms::CloudWatchTransform` (#25)
+
+### Fixed
+- Stop the telemetry runner when puma shuts down or when the target IO stream is closed. This prevents `IOError: closed stream` errors during shutdown (#31, #45)
+- Log target errors with `unknown_error` instead of `error`, so a failed publish does not make puma exit (#31, #45)
+
 ## [1.1.6]
 
 ### Changed

data/README.md

@@ -41,26 +41,67 @@ Puma::Plugin::Telemetry.configure do |config|
 end
 ```
 
-### Basic
+### Basic IO Target
 
-Output telemetry as JSON to `STDOUT`
+A basic I/O target will emit telemetry data to `STDOUT`, formatted in JSON.
 
 ```ruby
-  config.add_target :io
+config.add_target :io
 ```
 
+#### Options
+
+This target has configurable `formatter:` and `transform:` options.
+The `formatter:` options are
+
+* `:json` _(default)_ - Print the logs in JSON.
+* `:passthrough` - A passthrough formatter which returns the telemetry `Hash` unaltered, passing it directly to the `io:` instance.
+
+The `transform:` options are
+
+* `:cloud_watch` _(default)_ - Transforms telemetry keys, replacing dots with dashes to support AWS CloudWatch Log Metrics filters.
+* `:passthrough` -  A passthrough transform which returns the telemetry `Hash` unaltered.
+
 ### Datadog StatsD target
 
-Given gem provides built in target for Datadog StatsD client, that uses batch operation to publish metrics.
+A target for the Datadog StatsD client, that uses batch operation to publish metrics.
 
-**NOTE** Be sure to have `dogstatsd` gem installed.
+**NOTE** This target requires the `dogstatsd-ruby` gem in your project:
 
 ```ruby
-  config.add_target :dogstatsd, client: Datadog::Statsd.new
+gem "dogstatsd-ruby"
+```
+
+```ruby
+config.add_target :dogstatsd, client: Datadog::Statsd.new
 ```
 
 You can provide all the tags, namespaces, and other configuration options as always to `Datadog::Statsd.new` method.
 
+### OpenTelemetry target
+
+A target for the OpenTelemetry Metrics SDK, that uses batch operations to publish metrics.
+
+**NOTE** This target requires the `opentelemetry-metrics-sdk` gem in your project:
+
+```ruby
+gem "opentelemetry-metrics-sdk"
+```
+
+```ruby
+config.add_target :open_telemetry, meter_provider: OpenTelemetry.meter_provider
+```
+
+This target supports the following options:
+
+| Option         | Description                                                                                                                            | Default | Required |
+|----------------|----------------------------------------------------------------------------------------------------------------------------------------|---------|----------|
+| meter_provider | The meter provider used to create instruments, e.g. `OpenTelemetry.meter_provider`                                                      | -       | Yes      |
+| prefix         | Metric name prefix. <br> ex) prefix: 'web' => 'web.workers.booted'. Pass `nil` for no prefix                                             | 'puma'  | No       |
+| suffix         | Metric name suffix. <br> ex) suffix: 'v1' => 'workers.booted.v1'                                                                         | nil     | No       |
+| attributes     | Attributes to be included with the metric                                                                                                | {}      | No       |
+| force_flush    | Force flush the meter provider after each publish, so all values are exported, not only the last aggregated one. Can impact performance | false   | No       |
+
 ### All available options
 
 For detailed documentation checkout [`Puma::Plugin::Telemetry::Config`](./lib/puma/plugin/telemetry/config.rb) class.
@@ -73,7 +114,7 @@ Puma::Plugin::Telemetry.configure do |config|
   config.puma_telemetry = %w[workers.requests_count queue.backlog queue.capacity]
   config.socket_telemetry!
   config.socket_parser = :inspect
-  config.add_target :io, formatter: :json, io: StringIO.new
+  config.add_target :io, io: StringIO.new, formatter: :json, transform: :passthrough
   config.add_target :dogstatsd, client: Datadog::Statsd.new(tags: { env: ENV["RAILS_ENV"] })
 end
 ```
@@ -85,8 +126,8 @@ Target is a simple object that implements `call` methods that accepts `telemetry
 Just be mindful that if the API takes long to call, it will slow down frequency with which telemetry will get reported.
 
 ```ruby
-  # Example logfmt to stdout target
-  config.add_target proc { |telemetry| puts telemetry.map { |k, v| "#{k}=#{v.inspect}" }.join(" ") }
+  # Example key/value log to `STDOUT` target
+  config.add_target ->(telemetry) { puts telemetry.map { |k, v| "#{k}=#{v.inspect}" }.join(" ") }
 ```
 
 ## Extra middleware

data/lib/puma/plugin/telemetry/config.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'socket'
+
 module Puma
   class Plugin
     module Telemetry
@@ -32,7 +34,8 @@ module Puma
 
         TARGETS = {
           dogstatsd: Telemetry::Targets::DatadogStatsdTarget,
-          io: Telemetry::Targets::IOTarget
+          io: Telemetry::Targets::IOTarget,
+          open_telemetry: Telemetry::Targets::OpenTelemetryTarget
         }.freeze
 
         # Whenever telemetry should run with puma
@@ -91,7 +94,15 @@ module Puma
         end
 
         def socket_telemetry!
-          @socket_telemetry = true
+          # These structs are platform specific, and not available on macOS,
+          # for example. If they're undefined, then we cannot capture socket
+          # telemetry. We'll warn in that case.
+          if defined?(Socket::SOL_TCP) && defined?(Socket::TCP_INFO)
+            @socket_telemetry = true
+          else
+            @socket_telemetry = false
+            warn("Cannot capture socket telemetry on this platform (#{RUBY_PLATFORM}); socket_telemetry is disabled.")
+          end
         end
 
         def socket_telemetry?

data/lib/puma/plugin/telemetry/formatters/json_formatter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Puma
+  class Plugin
+    module Telemetry
+      module Formatters
+        # JSON formatter, expects `call` method accepting telemetry hash
+        class JSONFormatter
+          def self.call(telemetry)
+            ::JSON.dump(telemetry)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/telemetry/formatters/passthrough_formatter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Puma
+  class Plugin
+    module Telemetry
+      module Formatters
+        # A passthrough formatter - it returns the telemetry Hash it was given
+        class PassthroughFormatter
+          def self.call(telemetry)
+            telemetry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/telemetry/targets/base_formatting_target.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative '../formatters/json_formatter'
+require_relative '../formatters/passthrough_formatter'
+require_relative '../transforms/cloud_watch_transform'
+require_relative '../transforms/passthrough_transform'
+
+module Puma
+  class Plugin
+    module Telemetry
+      module Targets
+        # A base class for other Targets concerned with formatting telemetry
+        class BaseFormattingTarget
+          def initialize(formatter: :json, transform: :cloud_watch)
+            @transform = case transform
+                         when :cloud_watch then Transforms::CloudWatchTransform
+                         when :passthrough then Transforms::PassthroughTransform
+                         else transform
+                         end
+            @formatter = case formatter
+                         when :json then Formatters::JSONFormatter
+                         when :passthrough then Formatters::PassthroughFormatter
+                         else formatter
+                         end
+          end
+
+          def call(_telemetry)
+            raise NotImplementedError, "#{__method__} must be implemented by #{self.class.name}"
+          end
+
+          private
+
+          attr_reader :formatter, :transform
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/telemetry/targets/io_target.rb

@@ -1,40 +1,25 @@
 # frozen_string_literal: true
 
-require 'json'
+require_relative 'base_formatting_target'
 
 module Puma
   class Plugin
     module Telemetry
       module Targets
         # Simple IO Target, publishing metrics to STDOUT or logs
-        #
-        class IOTarget
-          # JSON formatter for IO, expects `call` method accepting telemetry hash
-          #
-          class JSONFormatter
-            # NOTE: Replace dots with dashes for better support of AWS CloudWatch
-            #       Log Metric filters, as they don't support dots in key names.
-            def self.call(telemetry)
-              log = telemetry.transform_keys { |k| k.tr('.', '-') }
-
-              log['name'] = 'Puma::Plugin::Telemetry'
-              log['message'] = 'Publish telemetry'
-
-              ::JSON.dump(log)
-            end
-          end
-
-          def initialize(io: $stdout, formatter: :json)
+        class IOTarget < BaseFormattingTarget
+          def initialize(io: $stdout, formatter: :json, transform: :cloud_watch)
+            super(formatter: formatter, transform: transform)
             @io = io
-            @formatter = case formatter
-                         when :json then JSONFormatter
-                         else formatter
-                         end
           end
 
           def call(telemetry)
-            @io.puts(@formatter.call(telemetry))
+            io.puts(formatter.call(transform.call(telemetry)))
           end
+
+          private
+
+          attr_reader :io
         end
       end
     end

data/lib/puma/plugin/telemetry/targets/open_telemetry_target.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Puma
+  class Plugin
+    module Telemetry
+      module Targets
+        # Target wrapping OpenTelemetry Metrics client.
+        #
+        # ## Example
+        #
+        #     require 'opentelemetry-metrics-sdk'
+        #
+        #     OpenTelemetryTarget.new(meter_provider: OpenTelemetry.meter_provider)
+        #
+        class OpenTelemetryTarget
+          def initialize(meter_provider:, prefix: 'puma', suffix: nil, force_flush: false, attributes: {})
+            @meter_provider = meter_provider
+            @meter          = meter_provider.meter('puma.telemetry')
+            @prefix         = prefix
+            @suffix         = suffix
+            @force_flush    = force_flush
+            @attributes     = attributes
+            @instruments    = {}
+          end
+
+          # We are using `gauge` metric type, which means that only the last value will get exported
+          # since the OpenTelemetry exporter aggregates metrics before sending them.
+          #
+          # This means that we could publish metrics from here several times
+          # before they get flushed from the aggregation thread, and when they
+          # do, only the last values will get sent.
+          #
+          # That's why we provide the option to explicitly call force_flush here, in order to persist
+          # all metrics, and not only the most recent ones.
+          #
+          # Note: Force flushing metrics every time can significantly impact performance
+          #
+          def call(telemetry)
+            telemetry.each do |metric, value|
+              instrument(metric).record(value, attributes: @attributes)
+            end
+
+            @meter_provider.force_flush if @force_flush
+          end
+
+          def instrument(metric)
+            @instruments[metric] ||= @meter.create_gauge([@prefix, metric, @suffix].compact.join('.'))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/telemetry/transforms/cloud_watch_transform.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Puma
+  class Plugin
+    module Telemetry
+      module Transforms
+        # Replace dots with dashes for better support of AWS CloudWatch Log
+        # Metric filters, as they don't support dots in key names.
+        # Expects `call` method accepting telemetry Hash
+        class CloudWatchTransform
+          def self.call(telemetry)
+            telemetry.transform_keys { |k| String(k).tr('.', '-') }.tap do |data|
+              data['name'] = 'Puma::Plugin::Telemetry'
+              data['message'] = 'Publish telemetry'
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/telemetry/transforms/passthrough_transform.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Puma
+  class Plugin
+    module Telemetry
+      module Transforms
+        # A passthrough transform - it returns the telemetry Hash it was given
+        class PassthroughTransform
+          def self.call(telemetry)
+            telemetry
+          end
+        end
+      end
+    end
+  end
+end

data/lib/puma/plugin/telemetry/version.rb

@@ -3,7 +3,7 @@
 module Puma
   class Plugin
     module Telemetry
-      VERSION = '1.1.6'
+      VERSION = '1.2.0'
     end
   end
 end

data/lib/puma/plugin/telemetry.rb

@@ -7,6 +7,7 @@ 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/targets/open_telemetry_target'
 require 'puma/plugin/telemetry/config'
 
 module Puma
@@ -64,6 +65,7 @@ module Puma
       module PluginInstanceMethods
         def start(launcher)
           @launcher = launcher
+          @stopped = false
 
           unless Puma::Plugin::Telemetry.config.enabled?
             log_writer.log 'plugin=telemetry msg="disabled, exiting..."'
@@ -72,26 +74,27 @@ module Puma
 
           log_writer.log 'plugin=telemetry msg="enabled, setting up runner..."'
 
-          in_background do
-            sleep Puma::Plugin::Telemetry.config.initial_delay
-            run!
-          end
+          setup_runner
         end
 
         def run!
           loop do
-            log_writer.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
-            log_writer.error "plugin=telemetry err=#{e.class} msg=#{e.message.inspect}"
-          ensure
+            break if stopped?
+
+            break unless try_publish
+
             sleep Puma::Plugin::Telemetry.config.frequency
           end
         end
 
+        def stop!
+          @stopped = true
+        end
+
+        def stopped?
+          !!@stopped
+        end
+
         def call(telemetry)
           Puma::Plugin::Telemetry.config.targets.each do |target|
             target.call(telemetry)
@@ -100,6 +103,39 @@ module Puma
 
         private
 
+        def setup_runner
+          @launcher.events.on_stopped { stop! }
+
+          in_background do
+            sleep Puma::Plugin::Telemetry.config.initial_delay
+            run!
+          end
+        end
+
+        def try_publish
+          publish
+          true
+        rescue IOError, Errno::EPIPE
+          # Puma closes the IO streams during shutdown, stop publishing
+          log_safely 'plugin=telemetry msg="IO stream closed, stopping the runner"'
+          false
+        rescue StandardError => e
+          log_writer.unknown_error(e, nil, 'plugin=telemetry')
+          true
+        end
+
+        def publish
+          log_writer.debug 'plugin=telemetry msg="publish"'
+
+          call(Puma::Plugin::Telemetry.build(@launcher))
+        end
+
+        def log_safely(message)
+          log_writer.log(message)
+        rescue IOError, Errno::EPIPE
+          nil
+        end
+
         def log_writer
           if Puma::Const::PUMA_VERSION.to_i < 6
             @launcher.events

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puma-plugin-telemetry
 version: !ruby/object:Gem::Version
-  version: 1.1.6
+  version: 1.2.0
 platform: ruby
 authors:
 - Leszek Zalewski
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puma
@@ -51,8 +51,14 @@ files:
 - lib/puma/plugin/telemetry.rb
 - lib/puma/plugin/telemetry/config.rb
 - lib/puma/plugin/telemetry/data.rb
+- lib/puma/plugin/telemetry/formatters/json_formatter.rb
+- lib/puma/plugin/telemetry/formatters/passthrough_formatter.rb
+- lib/puma/plugin/telemetry/targets/base_formatting_target.rb
 - lib/puma/plugin/telemetry/targets/datadog_statsd_target.rb
 - lib/puma/plugin/telemetry/targets/io_target.rb
+- lib/puma/plugin/telemetry/targets/open_telemetry_target.rb
+- lib/puma/plugin/telemetry/transforms/cloud_watch_transform.rb
+- lib/puma/plugin/telemetry/transforms/passthrough_transform.rb
 - lib/puma/plugin/telemetry/version.rb
 - lib/rack/request_queue_time_middleware.rb
 - puma-plugin-telemetry.gemspec