puma-plugin-statsd 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ae9c9480d1241bd90b7a2b0deb90b48e5effd7c48e85131db1c76b67a58934d
-  data.tar.gz: 1037c175245a0f94d4c73e8531cf8de04e619840516fc00a910353933bf44172
+  metadata.gz: 15aae3abb8fd429c80e9f80235278b5e4d3d98f9b00efd72e369f40f01c36b03
+  data.tar.gz: 61fbb46bd7c5845228daf85f293c3a672133378c7e9374c1e15bfb45f6ae4dfe
 SHA512:
-  metadata.gz: 2f69cf9f81b61a53aeb195b8f3706232e2793a0bc365c654b2a8338573c10e6ff0ca7e6ecf39651d128c5929111ef350bd3284c5f22d1d15bf5560d807b90e15
-  data.tar.gz: 9c5b0671b4c9e62c790b1e534e11990b93542f56e8da9b42ab050bc007c631ac961b2d66d99d05d7ab3a8b7bd2a1113200ec439306e1f937ff8c97c2c3f342e9
+  metadata.gz: c96b8f351feac2013070964b5b281156b5a1d46b2d3e14ce74e4459b8bbacde741aae9a4df0f3ce7b1939ad2cb6e3428dc636fd87f2cfad851abad8b7d6f1a36
+  data.tar.gz: 8918fdb4bb3020661b9f935e1562870e7c67777404fa2bf2cda33fea6539a62aca1e117155c22c5c8fed034865724a56746129be739d3bfd6e469bd7c99d05c5

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # CHANGELOG
 
+## 2.5.0 2023-08-27
+
+* Support adjusting the default reporting interval of 2s (set STATSD_INTERVAL_SECONDS env var)  (PR #[54](https://github.com/yob/puma-plugin-statsd/pull/54))
+* New metric: `puma.requests` - the number of requests served since the last report (PR #[55](https://github.com/yob/puma-plugin-statsd/pull/55))
+* Improved documentation in the README
+
+## 2.4.0 2022-12-27
+
+* Support puma 6 (PR #[46](https://github.com/yob/puma-plugin-statsd/pull/46))
+
 ## 2.3.0 2022-11-26
 
 * Support the origin detection over UDP from Datadog via DD_ENTITY_ID env var

data/README.md

@@ -3,14 +3,20 @@
 [Puma][puma] integration with [statsd][statsd] for easy tracking of key metrics
 that puma can provide:
 
-* puma.workers
-* puma.booted_workers
-* puma.running
-* puma.backlog
-* puma.pool_capacity
-* puma.max_threads
-* puma.old_workers
-* puma.requests_count
+Gauges:
+
+* puma.workers - The number of distinct process running. In single mode this will be 1, in cluster mode the number of worker processes
+* puma.old_workers - The number of worker processes that are about to be shut down as part of a phased restart. Will normally be 0
+* puma.booted_workers - The number of worker processes that are in a booted state
+* puma.running - The number of worker threads currently running. In quiet times, idle threads may be shutdown, but they'll start back up again when traffic arrives
+* puma.backlog - The number of requests that have made it to a worker but are yet to be processed. This will normally be zero, as requests queue on the tcp/unix socket in front of the master puma process, not in the worker thread pool
+* puma.pool_capacity - The number of idle and unused worker threads. When this is low/zero, puma is running at full capacity and might need scaling up
+* puma.max_threads - The maximum number of worker threads that might run at one time
+* puma.requests_count - Total number of requests served by this puma since it started
+
+Counters:
+
+* puma.requests - The number of requests served since the previous report
 
   [puma]: https://github.com/puma/puma
   [statsd]: https://github.com/etsy/statsd
@@ -37,27 +43,61 @@ threads 8, 16
 plugin :statsd
 ```
 
-## Usage
+## Configuration
+
+### Statsd Connection
 
-By default the plugin assumes statsd is available at 127.0.0.1. If that's true in your environment, just start puma like normal:
+By default the plugin assumes statsd is available at 127.0.0.1. If that's true
+in your environment, just start puma like normal:
 
 ```
 bundle exec puma
 ```
 
-If statsd isn't on 127.0.0.1 or the port is non-standard, you can configure them using optional environment variables:
+If statsd isn't on 127.0.0.1 or the UDP port is non-standard, you can configure
+them using optional environment variables:
 
 ```
 STATSD_HOST=127.0.0.1 STATSD_PORT=9125 bundle exec puma
 ```
 
+Some setups have statsd listening on a Unix socket rather than UDP. In that case, specify the socket path:
+
+```
+STATSD_SOCKET_PATH=/tmp/statsd.socket bundle exec puma
+```
+
+### Interval
+
+By default values will be reported to statsd every 2 seconds. To customise that
+internal, set the `STATSD_INTERVAL_SECONDS` environment variable.
+
+```
+STATSD_INTERVAL_SECONDS=1 bundle exec puma
+```
+
+Fractional seconds are supported. Here's how you'd opt into 500ms:
+
+```
+STATSD_INTERVAL_SECONDS="0.5" bundle exec puma
+```
+
+### Prefix
+
+In some environments you may want to prefix the metric names. To report
+`foo.puma.pool_capacity` instead of `puma.pool_capacity`:
+
+```
+STATSD_METRIC_PREFIX=foo bundle exec puma
+```
+
 ### Datadog Integration
 
 metric tags are a non-standard addition to the statsd protocol, supported by
 the datadog "dogstatsd" server.
 
 Should you be reporting the puma metrics to a dogstatsd server, you can set
-tags via the following three environment variables.
+tags via the following environment variables.
 
 #### DD_TAGS
 
@@ -67,10 +107,16 @@ tags via the following three environment variables.
 For example, you could set this environment variable to set three datadog tags,
 and then you can filter by in the datadog interface:
 
-```bash
-export DD_TAGS="env:test simple-tag-0 tag-key-1:tag-value-1"
-bundle exec rails server
 ```
+DD_TAGS="env:test simple-tag-0 tag-key-1:tag-value-1" bundle exec puma
+```
+
+#### DD_ENV, DD_SERVICE, DD_VERSION, DD_ENTITY_ID
+
+The `env`, `service`, `version` and `dd.internal.entity_id` tags have special
+meaning to datadog, and they can be set using the above environment variables.
+These are the conventional environment variables recommended by datadog, so
+they're likely to be set in many deployments.
 
 #### MY_POD_NAME
 

data/lib/puma/plugin/statsd.rb

@@ -1,4 +1,5 @@
-# coding: utf-8, frozen_string_literal: true
+# coding: utf-8
+# frozen_string_literal: true
 require "puma"
 require "puma/plugin"
 require 'socket'
@@ -6,7 +7,7 @@ require 'socket'
 class StatsdConnector
   ENV_NAME = "STATSD_HOST"
   STATSD_TYPES = { count: 'c', gauge: 'g' }
-  METRIC_DELIMETER = ".".freeze
+  METRIC_DELIMETER = "."
 
   attr_reader :host, :port
 
@@ -35,8 +36,9 @@ end
 
 # Wrap puma's stats in a safe API
 class PumaStats
-  def initialize(stats)
+  def initialize(stats, previous_requests_count = 0)
     @stats = stats
+    @previous_requests_count = previous_requests_count
   end
 
   def clustered?
@@ -94,15 +96,26 @@ class PumaStats
       @stats.fetch(:requests_count, 0)
     end
   end
+
+  def requests_delta
+    requests_count - @previous_requests_count
+  end
 end
 
 Puma::Plugin.create do
   # We can start doing something when we have a launcher:
   def start(launcher)
     @launcher = launcher
+    @log_writer =
+      if Gem::Version.new(Puma::Const::PUMA_VERSION) >= Gem::Version.new(6)
+        @launcher.log_writer
+      else
+        @launcher.events
+      end
 
     @statsd = ::StatsdConnector.new
-    @launcher.events.debug "statsd: enabled (host: #{@statsd.host})"
+    @interval_seconds = ENV.fetch("STATSD_INTERVAL_SECONDS", "2").to_f
+    @log_writer.debug "statsd: enabled (host: #{@statsd.host}, interval: #{@interval})"
 
     # Fetch global metric prefix from env variable
     @metric_prefix = ENV.fetch("STATSD_METRIC_PREFIX", nil)
@@ -185,12 +198,14 @@ Puma::Plugin.create do
   # Send data to statsd every few seconds
   def stats_loop
     tags = environment_variable_tags
+    previous_requests_count = 0
 
     sleep 5
     loop do
-      @launcher.events.debug "statsd: notify statsd"
+      @log_writer.debug "statsd: notify statsd"
       begin
-        stats = ::PumaStats.new(Puma.stats_hash)
+        stats = ::PumaStats.new(Puma.stats_hash, previous_requests_count)
+        previous_requests_count = stats.requests_count
         @statsd.send(metric_name: prefixed_metric_name("puma.workers"), value: stats.workers, type: :gauge, tags: tags)
         @statsd.send(metric_name: prefixed_metric_name("puma.booted_workers"), value: stats.booted_workers, type: :gauge, tags: tags)
         @statsd.send(metric_name: prefixed_metric_name("puma.old_workers"), value: stats.old_workers, type: :gauge, tags: tags)
@@ -199,10 +214,11 @@ Puma::Plugin.create do
         @statsd.send(metric_name: prefixed_metric_name("puma.pool_capacity"), value: stats.pool_capacity, type: :gauge, tags: tags)
         @statsd.send(metric_name: prefixed_metric_name("puma.max_threads"), value: stats.max_threads, type: :gauge, tags: tags)
         @statsd.send(metric_name: prefixed_metric_name("puma.requests_count"), value: stats.requests_count, type: :gauge, tags: tags)
+        @statsd.send(metric_name: prefixed_metric_name("puma.requests"), value: stats.requests_delta, type: :count, tags: tags)
       rescue StandardError => e
-        @launcher.events.unknown_error e, nil, "! statsd: notify stats failed"
+        @log_writer.unknown_error e, nil, "! statsd: notify stats failed"
       ensure
-        sleep 2
+        sleep @interval_seconds
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puma-plugin-statsd
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.5.0
 platform: ruby
 authors:
 - James Healy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-26 00:00:00.000000000 Z
+date: 2023-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puma
@@ -19,7 +19,7 @@ dependencies:
         version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -29,7 +29,7 @@ dependencies:
         version: '5.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -131,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Send puma metrics to statsd via a background thread