puma-cloudwatch 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd707d05af913eccd60a30e1a17fde3c458c4fe89edb102ff7a29b483d65ac9d
+  data.tar.gz: 58f7896483eec60cde81ea9615d80fccf3dd63e001f80c63968f016fb0c10081
+SHA512:
+  metadata.gz: '08add2c6446a55ce039e8dfe8d0e86f01fd05b61b63cbc3e71830757034fd9ae220ad79a6a79536b416137c48adf92eafb74eb0c455e81f1f286830c1dc1c24a'
+  data.tar.gz: d30b0f1d6e88f6923aec9067c3731ff7610d48a51d450320195612998dc476456119e5be861de4d58c1e6522f1f0bc6459616810d1f2af90d03b79818eac2fcd

data/.gitignore

@@ -0,0 +1,13 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+/Gemfile.lock

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,7 @@
+---
+sudo: false
+language: ruby
+cache: bundler
+rvm:
+  - 2.5.6
+before_install: gem install bundler -v 2.0.2

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in puma_cloudwatch.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2019 Tung Nguyen
+
+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,66 @@
+# Puma Cloudwatch Puma
+
+A [puma](https://puma.io) plugin that sends puma stats to CloudWatch.
+
+## Usage
+
+You should configure the `PUMA_CLOUDWATCH_DIMENSION_VALUE` env variable to include your application name.
+For example, if you're application is named "myapp", this would be a good value to use:
+
+    PUMA_CLOUDWATCH_DIMENSION_VALUE=myapp-puma
+
+Then you can get metrics for your `myapp-puma` app. List of metrics:
+
+* pool_capacity: the number of requests that the server is capable of taking right now.
+* max_threads:  preconfigured maximum number of worker threads.
+* running: the number of running threads (spawned threads) for any Puma worker.
+* backlog: the number of connections in that worker's "todo" set waiting for a worker thread.
+
+The `pool_capacity` metric is important. It shows how busy the server is getting before it reaches capacity.
+
+### Environment Variables
+
+The plugin's settings can be controlled with environmental variables:
+
+Env Var | Description | Default Value
+--- | --- | ---
+PUMA\_CLOUDWATCH\_NAMESPACE | CloudWatch metric namespace | WebServer
+PUMA\_CLOUDWATCH\_DIMENSION\_NAME | CloudWatch metric dimension name | App
+PUMA\_CLOUDWATCH\_DIMENSION\_VALUE | CloudWatch metric dimension value | puma
+PUMA\_CLOUDWATCH\_FREQUENCY | How often to send data to CloudWatch in seconds. | 60
+PUMA\_CLOUDWATCH\_NOOP | When set, the plugin prints out the metrics instead of sending them to cloudwatch. | (unset)
+
+### Sum and Frequency
+
+If you leave the `PUMA_CLOUDWATCH_FREQUENCY` at its default of 60 seconds and graph out the `pool_capacity` capacity with a 1-minute period resolution, then the CloudWatch Sum statistic is useful. It shows how busy all the `myapp-puma` servers are.  Particularly, the `pool_capacity` shows available capacity,  and  `pool_threads` shows the total threads.
+
+**Important**: If you change the CloudWatch send frequency, then Sum statistic must be normalized.  For example, let's say you use `PUMA_CLOUDWATCH_FREQUENCY=30`. Then puma-cloudwatch will send data every 30s. However, if the chart is still using a 1-minute period, then the Sum statistic would "double".  Capacity has not doubled, puma-cloudwatch is just sending twice as much data.  To normalize the Sum, set the time period resolution to match the frequency. In this case: 30 seconds.
+
+If you use the Average statistic, then you don't have to worry about normalizing. Average already inherently normalized.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'puma-cloudwatch'
+```
+
+And then execute:
+
+    $ bundle
+
+In your `config/puma.rb`
+
+Add these 2 lines your `config/puma.rb`:
+
+```ruby
+activate_control_app
+plugin :cloudwatch
+```
+
+It activates the puma control rack application, and enables the puma-cloudwatch plugin to send metrics.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/puma_cloudwatch.

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "puma_cloudwatch"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/puma/plugin/cloudwatch.rb

@@ -0,0 +1,7 @@
+require 'puma-cloudwatch'
+
+Puma::Plugin.create do
+  def start(launcher)
+    PumaCloudwatch::Metrics.start_sending(launcher)
+  end
+end

data/lib/puma-cloudwatch.rb

@@ -0,0 +1 @@
+require_relative "puma_cloudwatch"

data/lib/puma_cloudwatch/metrics/fetcher.rb

@@ -0,0 +1,39 @@
+require "json"
+require "socket"
+
+class PumaCloudwatch::Metrics
+  class Fetcher
+    def initialize(options={})
+      @control_url = options[:control_url]
+      @control_auth_token = options[:control_auth_token]
+    end
+
+    def call
+      body = with_retries do
+        read_socket
+      end
+      JSON.parse(body.split("\n").last) # stats
+    end
+
+  private
+    def read_socket
+      Socket.unix(@control_url.gsub('unix://', '')) do |socket|
+        socket.print("GET /stats?token=#{@control_auth_token} HTTP/1.0\r\n\r\n")
+        socket.read
+      end
+    end
+
+    def with_retries
+      retries, max_attempts = 0, 10
+      yield
+    rescue Errno::ENOENT => e
+      retries += 1
+      if retries > max_attempts
+        raise e
+      end
+      puts "retries #{retries} #{e.class} #{e.message}" if ENV['PUMA_CLOUDWATCH_SOCKET_RETRY']
+      sleep 1
+      retry
+    end
+  end
+end

data/lib/puma_cloudwatch/metrics/looper.rb

@@ -0,0 +1,32 @@
+class PumaCloudwatch::Metrics
+  class Looper
+    def self.run(options)
+      new(options).run
+    end
+
+    def initialize(options)
+      @options = options
+      @control_url = options[:control_url]
+      @control_auth_token = options[:control_auth_token]
+      @frequency = Integer(ENV['PUMA_CLOUDWATCH_FREQUENCY'] || 60)
+    end
+
+    def run
+      raise StandardError, "Puma control app is not activated" if @control_url == nil
+      puts "Sending metrics to CloudWatch..."
+      Thread.new do
+        perform
+      end
+    end
+
+    def perform
+      puts "puma-cloudwatch plugin: Will send data every #{@frequency} seconds."
+      loop do
+        stats = Fetcher.new(@options).call
+        results = Parser.new(stats).call
+        Sender.new(results).call
+        sleep @frequency
+      end
+    end
+  end
+end

data/lib/puma_cloudwatch/metrics/parser.rb

@@ -0,0 +1,44 @@
+class PumaCloudwatch::Metrics
+  class Parser
+    METRICS = [:backlog, :running, :pool_capacity, :max_threads]
+
+    def initialize(data)
+      @data = data
+    end
+
+    def call
+      Array.new.tap { |result| parse(@data, result) }
+    end
+
+  private
+    # Build this structure:
+    #
+    #     [{:backlog=>[0, 0],
+    #     :running=>[0, 0],
+    #     :pool_capacity=>[16, 16],
+    #     :max_threads=>[16, 16]}]
+    #
+    def parse(stats, result)
+      item = Hash.new([])
+
+      clustered = stats.key?("worker_status")
+      if clustered
+        statuses = stats["worker_status"].map { |s| s["last_status"] } # last_status: Array with worker stats
+        statuses.each do |status|
+          METRICS.each do |metric|
+            count = status[metric.to_s]
+            item[metric] += [count] if count
+          end
+        end
+      else # single mode
+        METRICS.each do |metric|
+          count = stats[metric.to_s]
+          item[metric] += [count] if count
+        end
+      end
+
+      result << item unless item.empty?
+      result
+    end
+  end
+end

data/lib/puma_cloudwatch/metrics/sender.rb

@@ -0,0 +1,94 @@
+require "aws-sdk-cloudwatch"
+
+# It probably makes sense to configure PUMA_CLOUDWATCH_DIMENSION_VALUE to include your application name.
+# For example if you're application is named "myapp", this would be a good value to use:
+#
+#    PUMA_CLOUDWATCH_DIMENSION_VALUE=myapp-puma
+#
+# Then you can get all the metrics for the pool_capacity for your myapp-puma app.
+#
+# Summing the metric tells you the total available pool_capacity for the myapp-puma app.
+#
+class PumaCloudwatch::Metrics
+  class Sender
+    def initialize(metrics)
+      @metrics = metrics
+      @namespace = ENV['PUMA_CLOUDWATCH_NAMESPACE'] || "WebServer"
+      @dimension_name = ENV['PUMA_CLOUDWATCH_DIMENSION_NAME'] || "App"
+      @dimension_value = ENV['PUMA_CLOUDWATCH_DIMENSION_VALUE'] || "puma" # IE: myapp-puma
+    end
+
+    def call
+      put_metric_data(
+        namespace: @namespace,
+        metric_data: metric_data,
+      )
+    end
+
+    # Input @metrics example:
+    #
+    #     [{:backlog=>[0, 0],
+    #     :running=>[0, 0],
+    #     :pool_capacity=>[16, 16],
+    #     :max_threads=>[16, 16]}]
+    #
+    # Output example:
+    #
+    #   [{:metric_name=>"backlog",
+    #     :statistic_values=>{:sample_count=>2, :sum=>0, :minimum=>0, :maximum=>0}},
+    #   {:metric_name=>"running",
+    #     :statistic_values=>{:sample_count=>2, :sum=>0, :minimum=>0, :maximum=>0}},
+    #   {:metric_name=>"pool_capacity",
+    #     :statistic_values=>{:sample_count=>2, :sum=>32, :minimum=>16, :maximum=>16}},
+    #   {:metric_name=>"max_threads",
+    #     :statistic_values=>{:sample_count=>2, :sum=>32, :minimum=>16, :maximum=>16}}]
+    #
+    # Resources:
+    # pool_capcity and max_threads are the important metrics
+    # https://dev.to/amplifr/monitoring-puma-web-server-with-prometheus-and-grafana-5b5o
+    #
+    def metric_data
+      data = []
+      @metrics.each do |metric|
+        metric.each do |name, values|
+          data << {
+            metric_name: name.to_s,
+            dimensions: dimensions,
+            statistic_values: {
+              sample_count: values.length,
+              sum: values.sum,
+              minimum: values.min,
+              maximum: values.max
+            }
+          }
+        end
+      end
+      data
+    end
+
+    def dimensions
+      [
+        name: @dimension_name,
+        value: @dimension_value
+      ]
+    end
+
+  private
+    def put_metric_data(params)
+      if noop?
+        puts "NOOP: sending data to cloudwatch:"
+        pp params
+      else
+        cloudwatch.put_metric_data(params)
+      end
+    end
+
+    def noop?
+      !ENV["PUMA_CLOUDWATCH_NOOP"].nil?
+    end
+
+    def cloudwatch
+      @cloudwatch ||= Aws::CloudWatch::Client.new
+    end
+  end
+end

data/lib/puma_cloudwatch/metrics.rb

@@ -0,0 +1,20 @@
+module PumaCloudwatch
+  class Metrics
+    autoload :Fetcher, "puma_cloudwatch/metrics/fetcher"
+    autoload :Looper, "puma_cloudwatch/metrics/looper"
+    autoload :Parser, "puma_cloudwatch/metrics/parser"
+    autoload :Sender, "puma_cloudwatch/metrics/sender"
+
+    def self.start_sending(launcher)
+      new(launcher).start_sending
+    end
+
+    def initialize(launcher)
+      @launcher = launcher
+    end
+
+    def start_sending
+      Looper.run(@launcher.options)
+    end
+  end
+end

data/lib/puma_cloudwatch/version.rb

@@ -0,0 +1,3 @@
+module PumaCloudwatch
+  VERSION = "0.1.0"
+end

data/lib/puma_cloudwatch.rb

@@ -0,0 +1,7 @@
+require "puma_cloudwatch/version"
+
+module PumaCloudwatch
+  class Error < StandardError; end
+
+  autoload :Metrics, "puma_cloudwatch/metrics"
+end

data/puma-cloudwatch.gemspec

@@ -0,0 +1,31 @@
+lib = File.expand_path("lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "puma_cloudwatch/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "puma-cloudwatch"
+  spec.version       = PumaCloudwatch::VERSION
+  spec.authors       = ["Tung Nguyen"]
+  spec.email         = ["tongueroo@gmail.com"]
+
+  spec.summary       = "Puma plugin sends puma stats to CloudWatch"
+  spec.homepage      = "https://github.com/tongueroo/puma-cloudwatch"
+  spec.license       = "MIT"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "aws-sdk-cloudwatch"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: puma-cloudwatch
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tung Nguyen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-09-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-cloudwatch
+  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: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !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: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: 
+email:
+- tongueroo@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/puma-cloudwatch.rb
+- lib/puma/plugin/cloudwatch.rb
+- lib/puma_cloudwatch.rb
+- lib/puma_cloudwatch/metrics.rb
+- lib/puma_cloudwatch/metrics/fetcher.rb
+- lib/puma_cloudwatch/metrics/looper.rb
+- lib/puma_cloudwatch/metrics/parser.rb
+- lib/puma_cloudwatch/metrics/sender.rb
+- lib/puma_cloudwatch/version.rb
+- puma-cloudwatch.gemspec
+homepage: https://github.com/tongueroo/puma-cloudwatch
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tongueroo/puma-cloudwatch
+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: []
+rubygems_version: 3.0.6
+signing_key: 
+specification_version: 4
+summary: Puma plugin sends puma stats to CloudWatch
+test_files: []