puma-plugin-statsd 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed64454a76b4776e4362b9e149ecaa09f9212c4482e5c4e6d2a1a2a33fc06c80
+  data.tar.gz: e5ad995a36ee4ae265ff02a07172ede4f1614e5263777293e81bc620ed2013fd
+SHA512:
+  metadata.gz: 924aec321ac03bff296515886d8e2ad67e111c6ad769be6a97732a51c45fa26179b0d2dea815f5351e3e5d844ecc6b6a7c684b0cbc643b6ff33f86a9f6d1c0d3
+  data.tar.gz: 0da8be2a3781dd14c6804054f7698eb7840c2dd3d7515b8ad9c7e642636f1231bd000570e4b7eff9497730d98add97e6948283fa0d7c57ead73fc4573c261a84

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2018 James Healy
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,110 @@
+# Puma Statsd Plugin
+
+[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 already natively supports [socket activation][socket-activation].
+
+  [puma]: https://github.com/puma/puma
+  [statsd]: https://github.com/etsy/statsd
+
+## Installation
+
+Add this gem to your Gemfile with puma and then bundle:
+
+```ruby
+gem "puma"
+gem "puma-plugin-statsd"
+```
+
+Add it to your puma config:
+
+```ruby
+# config/puma.rb
+
+bind "http://127.0.0.1:9292"
+
+workers 1
+threads 8, 16
+
+plugin :statsd
+```
+
+## Usage
+
+Ensure you have an environment variable set that points to a statsd host, then boot your puma app as usual
+
+```
+STATSD_HOST=127.0.0.1 bundle exec puma
+```
+
+```
+STATSD_HOST=127.0.0.1 MY_POD_NAME=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 two environment variables.
+
+`MY_POD_NAME` adds a `pod_name` tag to the metrics. The `MY_POD_NAME`
+environment variable is recommended in th datadog kubernetes setup
+documentation, and for puma apps deployed to kubernetes it's very helpful to
+have the option to report on specific pods.
+
+You can set it on your pods like this:
+
+```yaml
+env:
+  - name: MY_POD_NAME
+    valueFrom:
+      fieldRef:
+        fieldPath: metadata.name
+```
+
+`STATSD_GROUPING` adds a `grouping` tag to the metrics, with a value equal to
+the environment variable value. This is particularly helpful in a kubernetes
+deployment where each pod has a unique name but you want the option to group
+metrics across all pods in a deployment. Setting this on the pods in a
+deployment might look something like:
+
+```yaml
+env:
+  - name: STATSD_GROUPING
+    value: deployment-foo
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/yob/puma-plugin-statsd.
+
+## Acknowledgements
+
+This gem is a fork of the excellent [puma-plugin-statsd][puma-plugin-statsd] by
+Sam Cochran.
+
+  [puma-plugin-statsd]: https://github.com/sj26/puma-plugin-systemd
+
+Other puma plugins that were helpful references:
+
+* [puma-heroku](https://github.com/evanphx/puma-heroku)
+* [tmp-restart](https://github.com/puma/puma/blob/master/lib/puma/plugin/tmp_restart.rb)
+
+The [puma docs](https://github.com/puma/puma/blob/master/docs/plugins.md) were also helpful.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License][license].
+
+  [license]: http://opensource.org/licenses/MIT

data/lib/puma/plugin/statsd.rb

@@ -0,0 +1,151 @@
+# coding: utf-8, frozen_string_literal: true
+
+require "json"
+require 'socket'
+require "puma"
+require "puma/plugin"
+
+
+Puma::Plugin.create do
+
+  class Statsd
+    ENV_NAME = "STATSD_HOST"
+    STATSD_PORT = 8125
+    STATSD_TYPES = { count: 'c', gauge: 'g' }
+
+    attr_reader :host
+
+    def initialize
+      @host = ENV.fetch(ENV_NAME, nil)
+    end
+
+    def enabled?
+      !!host
+    end
+
+    def send(metric_name:, value:, type:, tags: {})
+      data = "#{metric_name}:#{value}|#{STATSD_TYPES.fetch(type)}"
+      if tags.any?
+        tag_str = tags.map { |k,v| "#{k}:#{v}" }.join(",")
+        data = "#{data}|##{tag_str}"
+      end
+
+      UDPSocket.new.send(data, 0, host, STATSD_PORT)
+    end
+  end
+
+  # Wrap puma's stats in a safe API
+  class PumaStats
+    def initialize(stats)
+      @stats = stats
+    end
+
+    def clustered?
+      @stats.has_key? "workers"
+    end
+
+    def workers
+      @stats.fetch("workers", 1)
+    end
+
+    def booted_workers
+      @stats.fetch("booted_workers", 1)
+    end
+
+    def running
+      if clustered?
+        @stats["worker_status"].map { |s| s["last_status"].fetch("running", 0) }.inject(0, &:+)
+      else
+        @stats.fetch("running", 0)
+      end
+    end
+
+    def backlog
+      if clustered?
+        @stats["worker_status"].map { |s| s["last_status"].fetch("backlog", 0) }.inject(0, &:+)
+      else
+        @stats.fetch("backlog", 0)
+      end
+    end
+
+    def pool_capacity
+      if clustered?
+        @stats["worker_status"].map { |s| s["last_status"].fetch("pool_capacity", 0) }.inject(0, &:+)
+      else
+        @stats.fetch("pool_capacity", 0)
+      end
+    end
+
+    def max_threads
+      if clustered?
+        @stats["worker_status"].map { |s| s["last_status"].fetch("max_threads", 0) }.inject(0, &:+)
+      else
+        @stats.fetch("max_threads", 0)
+      end
+    end
+  end
+
+  # Puma creates the plugin when encountering `plugin` in the config.
+  def initialize(loader)
+    @loader = loader
+  end
+
+  # We can start doing something when we have a launcher:
+  def start(launcher)
+    @launcher = launcher
+
+    @statsd = Statsd.new
+    if @statsd.enabled?
+      @launcher.events.debug "statsd: enabled (host: #{@statsd.host})"
+      register_hooks
+    else
+      @launcher.events.debug "statsd: not enabled (no #{Statsd::ENV_NAME} env var found)"
+    end
+  end
+
+  private
+
+  def register_hooks
+    in_background(&method(:stats_loop))
+  end
+
+  def fetch_stats
+    JSON.parse(Puma.stats)
+  end
+
+  def stats
+    PumaStats.new(fetch_stats)
+  end
+
+  def tags
+    tags = {}
+    if ENV.has_key?("MY_POD_NAME")
+      tags[:pod_name] = ENV.fetch("MY_POD_NAME", "no_pod")
+    end
+    if ENV.has_key?("STATSD_GROUPING")
+      tags[:grouping] = ENV.fetch("STATSD_GROUPING", "no-group")
+    end
+    tags
+  end
+
+  # Send data to statsd every few seconds
+  def stats_loop
+    sleep 5
+    loop do
+      @launcher.events.debug "statsd: notify statsd"
+      begin
+        @statsd.send(metric_name: "puma.workers", value: stats.workers, type: :gauge, tags: tags)
+        @statsd.send(metric_name: "puma.booted_workers", value: stats.booted_workers, type: :gauge, tags: tags)
+        @statsd.send(metric_name: "puma.running", value: stats.running, type: :gauge, tags: tags)
+        @statsd.send(metric_name: "puma.backlog", value: stats.backlog, type: :gauge, tags: tags)
+        @statsd.send(metric_name: "puma.pool_capacity", value: stats.pool_capacity, type: :gauge, tags: tags)
+        @statsd.send(metric_name: "puma.max_threads", value: stats.max_threads, type: :gauge, tags: tags)
+      rescue StandardError => e
+        @launcher.events.error "! statsd: notify stats failed:\n  #{e.to_s}\n  #{e.backtrace.join("\n    ")}"
+      ensure
+        sleep 2
+      end
+    end
+  end
+
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: puma-plugin-statsd
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- James Healy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-07-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 
+email: james@yob.id.au
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- lib/puma/plugin/statsd.rb
+homepage: https://github.com/yob/puma-plugin-statsd
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Send puma metrics to statsd via a background thread
+test_files: []