puma-plugin-statsd 2.4.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 024db26ca54b74eb4cc86cfbc8aacda5f5b68d25177b007a9050a22545466351
-  data.tar.gz: 1e42d780def66948cd9fd01357b0a424ad04aaac86bfa6f8e5c26de82a430e11
+  metadata.gz: 1d758cafa62bb07175a7c0a21a78e55414bfbb03b619fd5aad6bc311ccbbfaef
+  data.tar.gz: 6fd5c3b92fff9fe73305e7bc41149804765363d6cf0d108f7076325a75a4c57e
 SHA512:
-  metadata.gz: 6c44f94b38dc4c1848827bf20a3503f639be3cd13a0501beb807dd75d092403b229caf0c83c24b57caec9a255a76b2f371ce9b2e2cfa9efabc9e06ba07d9730c
-  data.tar.gz: af204a3591ff96c4bd876d42eec731037236265208abdb58f492145beda7e9124a511317623918bf9ce213c5e76c87307f26659e8cc12feea7a364b31d1a4ad3
+  metadata.gz: 8a86c803e4ae70ed64335db450a7965f928abcea69dee6cfdf9fcc0b733526f166fe17eefde8aac8db3f90b631c783ce13d437c7458c09729859c8b489d4cc20
+  data.tar.gz: dd6b1cf13cdbcc419b7e50b82dc2d1932904132dec9511be84fb2f8e321d6e9db900c823115f7154d7c1a13d24dad0e7efa9c25b5ee6e3bc944a1eee430121be

data/CHANGELOG.md

@@ -1,12 +1,22 @@
 # CHANGELOG
 
+## 2.6.0 2023-12-11
+
+* New metric: `puma.percent_busy` - The percentage of busy threads calculated as pool capacity relative to max threads (PR #[58](https://github.com/yob/puma-plugin-statsd/pull/58))
+
+## 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
+* Support the origin detection over UDP from Datadog via DD_ENTITY_ID env var (PR #[42](https://github.com/yob/puma-plugin-statsd/pull/42))
 
 ## 2.2.0 2022-07-31
 

data/README.md

@@ -3,14 +3,21 @@
 [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.percent_busy - The percentage of busy threads calculated as pool capacity relative to max threads
+* 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 +44,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 +108,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

@@ -36,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?
@@ -95,6 +96,14 @@ class PumaStats
       @stats.fetch(:requests_count, 0)
     end
   end
+
+  def percent_busy
+    (1 - (pool_capacity / max_threads.to_f)) * 100
+  end
+
+  def requests_delta
+    requests_count - @previous_requests_count
+  end
 end
 
 Puma::Plugin.create do
@@ -109,7 +118,8 @@ Puma::Plugin.create do
       end
 
     @statsd = ::StatsdConnector.new
-    @log_writer.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)
@@ -192,12 +202,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
       @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)
@@ -205,11 +217,13 @@ Puma::Plugin.create do
         @statsd.send(metric_name: prefixed_metric_name("puma.backlog"), value: stats.backlog, type: :gauge, tags: tags)
         @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.percent_busy"), value: stats.percent_busy, 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
         @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.4.0
+  version: 2.6.0
 platform: ruby
 authors:
 - James Healy
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-12-27 00:00:00.000000000 Z
+date: 2023-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: puma
@@ -131,7 +131,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: Send puma metrics to statsd via a background thread