puma-plugin-telemetry_too 0.0.1.alpha3 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a3826bccd50a4b4366c876ed3d9fe7ce0d75e66a038e11463da80ee2878087cc
-  data.tar.gz: c1203228b7dbab1717f7a8061b63e95df64c98498dadfbbac493de89e7b80214
+  metadata.gz: bc86aadc264e046c25033d4c9a35b2c275fa49214ee1eff287101251454b0f98
+  data.tar.gz: fe40cce9b6b4df9c9d51b44fd4b00a03654050fc5283f3eb24df049254bf08d6
 SHA512:
-  metadata.gz: 3f6d2a4a638084d7d15bc0466c299305f06268205a47b35eec337edf7364cefce9a86bf17d98f1bda87c921f2d7d256683f405e30097d7b8ad4e0e7c1d1d6ac0
-  data.tar.gz: d7ba1f825881507ff547408c2d019a3d7b59b9efc39c5343e4ec3ad28d9e82fea8ee0213e2808b28585b847dbe88deb4ddbe83278f9db5f68a01021fd3af6de3
+  metadata.gz: a0c0fa9db9c0453773f9f240338df4989d2c5ad7703a17bc9093a3e0bdfbd2a6be1aa983cee00df6ea8ae284f70244e422be1e5750f0ec79fbde10c366bfd584
+  data.tar.gz: 5ca8438972313be19086b03e610c898e09f7d66b2bdfaff6e23e3aee294978060ef71fc1bd145b5725bb88975f5f23900a190c59912d805aa8ff7076cf59bea3

data/.rubocop.yml

@@ -1,5 +1,4 @@
-require:
-  - rubocop-performance
+plugins: rubocop-performance
 
 AllCops:
   TargetRubyVersion: 3.2

data/CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Introduce new `formatter:` options: `:json` and `:passthrough`
 - Introduce new `transform:` options: `:cloud_watch` and `:passthrough`
 - Introduce new `LogTarget` for logging metrics to any `::Logger` compatible logger
+- Introduce new `OpenTelemetryTarget` for sending metrics via OpenTelemetry Metrics
 - Support for Puma 7
 
 ## [1.1.4] 2025-05-29

data/README.md

@@ -4,6 +4,7 @@ NOTE: This is a fork of `puma-plugin-telemetry`, modified to:
 
 - Support Puma 7
 - Add `LogTarget`, with custom `formatter:` and `transform:` options
+- Add `OpenTelemetry` target
 - Warn about socket telemetry on unsupported platforms
 
 Puma plugin which should be able to handle all your metric needs regarding your webserver:
@@ -15,7 +16,7 @@ Puma plugin which should be able to handle all your metric needs regarding your
 
 ## Install
 
-Add this line to your application's Gemfile:
+Add this line to your application's `Gemfile`:
 
 ```ruby
 gem "puma-plugin-telemetry_too"
@@ -38,7 +39,7 @@ $ gem install puma-plugin-telemetry_too
 In your puma configuration file (i.e. `config/puma.rb` or `config/puma/<env>.rb`):
 
 ```ruby
-plugin "telemetry"
+plugin "telemetry_too"
 
 Puma::Plugin::TelemetryToo.configure do |config|
   config.enabled = true
@@ -98,14 +99,30 @@ The `LogTarget` defaults to `formatter: :logfmt`, and `transform: :passthrough`.
 
 A target for the Datadog StatsD client, that uses batch operation to publish metrics.
 
-**NOTE** Be sure to have the `dogstatsd` gem installed.
-
 ```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 API, which uses batch operations to publish metrics.
+
+```ruby
+config.add_target :open_telemetry, meter_provider: OpenTelemetry.meter_provider
+```
+
+This target supports the following options:
+
+| Option         | Description                                                           | Default                        | Required |
+|----------------|-----------------------------------------------------------------------|--------------------------------|----------|
+| meter_provider | An instance of `OpenTelemetry::Metrics::MeterProvider`                | `OpenTelemetry.meter_provider` | No       |
+| force_flush    | Force-flush metrics after each call. <i>This can be expensive!</i>    | `false`                        | No       |
+| prefix         | Metric name prefix.<br>e.g. `prefix: "app"` → `app.workers.booted`    | `puma`                         | No       |
+| suffix         | Metric name suffix.<br>e.g. `suffix: "v1"` → `puma.workers.booted.v1` | `nil`                          | No       |
+| attributes     | Attributes to be included with the metric                             | `{}`                           | No       |
+
 ### All available options
 
 For detailed documentation checkout [`Puma::Plugin::TelemetryToo::Config`](./lib/puma/plugin/telemetry_too/config.rb) class.
@@ -130,8 +147,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 key/value log to `STDOUT` target
-  config.add_target ->(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_too/config.rb

@@ -44,6 +44,7 @@ module Puma
         TARGETS = {
           dogstatsd: TelemetryToo::Targets::DatadogStatsdTarget,
           io: TelemetryToo::Targets::IOTarget,
+          open_telemetry: TelemetryToo::Targets::OpenTelemetryTarget,
           log: TelemetryToo::Targets::LogTarget
         }.freeze
 

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

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Puma
+  class Plugin
+    module TelemetryToo
+      module Targets
+        # Target wrapping OpenTelemetry Metrics client.
+        #
+        # This uses the `gauge` metric type which only exports the last value because
+        # the OpenTelemetry exporter aggregates metrics before sending them. Meaning
+        # metrics could be published several times before they are flushed via aggregation
+        # thread. And when flushed, the last values will be sent.
+        #
+        # If you need to persist all metrics, you can enable the `force_flush` option.
+        # However, force-flushing metrics every time can significantly impact performance.
+        #
+        # ## Example
+        #
+        #     require 'opentelemetry-metrics-sdk'
+        #
+        #     OpenTelemetryTarget.new(meter_provider: OpenTelemetry.meter_provider, prefix: 'webserver')
+        class OpenTelemetryTarget
+          def initialize(meter_provider: ::OpenTelemetry.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 = {}
+            @mutex = Mutex.new
+          end
+
+          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)
+            mutex.synchronize do
+              instruments[metric] ||= create_gauge(metric)
+            end
+          end
+
+          private
+
+          attr_reader :meter_provider, :meter, :prefix, :suffix, :force_flush, :attributes, :instruments, :mutex
+
+          def create_gauge(metric)
+            meta = METADATA.fetch(metric, UNKNOWN_METADATA)
+            meter.create_gauge([prefix, metric, suffix].compact.join('.'),
+                               unit: String(meta.unit), description: String(meta.description))
+          end
+
+          def force_flush?
+            !!force_flush
+          end
+
+          Metadata = Data.define(:unit, :description) do
+            def initialize(unit:, description: '')
+              super
+            end
+          end
+          private_constant :Metadata
+
+          # rubocop:disable Metrics/LineLength
+          METADATA = {
+            'workers.booted' => Metadata[unit: '{process}', description: 'Number of booted Puma workers (processes).'],
+            'workers.total' => Metadata[unit: '{process}', description: 'Total number of Puma workers (processes).'],
+            'workers.spawned_threads' => Metadata[unit: '{thread}', description: 'Number of spawned threads across all Puma workers.'],
+            'workers.max_threads' => Metadata[unit: '{thread}', description: 'Maximum number of threads Puma is configured to spawn, across all workers.'],
+            'workers.requests_count' => Metadata[unit: '{request}', description: 'Total number of requests handled by all Puma workers, since start.'],
+            'queue.backlog' => Metadata[unit: '{request}', description: 'Requests that are waiting for an available thread.'],
+            'queue.backlog_max' => Metadata[unit: '{request}', description: "Maximum number of requests that have been fully buffered by the reactor and placed in a ready queue, but have not yet been picked up by a server thread. This stat is reset on every call, so it's the maximum value observed since the last stat call."],
+            'queue.reactor_max' => Metadata[unit: '{request}', description: "Maximum observed number of requests held in Puma's reactor. This stat is reset on every call, so it's the maximum value observed since the last stat call."],
+            'queue.capacity' => Metadata[unit: '{thread}', description: 'Number of Threads waiting to receive work.'],
+            'sockets.backlog' => Metadata[unit: '{request}', description: 'Number of unacknowledged connections in the Sockets Puma is bound to.']
+
+          }.freeze
+          private_constant :METADATA
+          # rubocop:enable Metrics/LineLength
+
+          UNKNOWN_METADATA = Metadata.new(unit: '1')
+          private_constant :UNKNOWN_METADATA
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,7 @@
 module Puma
   class Plugin
     module TelemetryToo
-      VERSION = '0.0.1.alpha3'
+      VERSION = '0.0.2'
     end
   end
 end

data/lib/puma/plugin/telemetry_too.rb

@@ -7,6 +7,7 @@ require 'puma/plugin/telemetry_too/version'
 require 'puma/plugin/telemetry_too/data'
 require 'puma/plugin/telemetry_too/targets/datadog_statsd_target'
 require 'puma/plugin/telemetry_too/targets/io_target'
+require 'puma/plugin/telemetry_too/targets/open_telemetry_target'
 require 'puma/plugin/telemetry_too/targets/log_target'
 require 'puma/plugin/telemetry_too/config'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: puma-plugin-telemetry_too
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha3
+  version: 0.0.2
 platform: ruby
 authors:
 - Leszek Zalewski
@@ -63,6 +63,7 @@ files:
 - lib/puma/plugin/telemetry_too/targets/datadog_statsd_target.rb
 - lib/puma/plugin/telemetry_too/targets/io_target.rb
 - lib/puma/plugin/telemetry_too/targets/log_target.rb
+- lib/puma/plugin/telemetry_too/targets/open_telemetry_target.rb
 - lib/puma/plugin/telemetry_too/transforms/cloud_watch_transform.rb
 - lib/puma/plugin/telemetry_too/transforms/l2met_transform.rb
 - lib/puma/plugin/telemetry_too/transforms/passthrough_transform.rb