puma-cloudwatch 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a921bab00785245aefb2570d27d05402679d20fc8a7e27d37c4d2d3f201bf487
-  data.tar.gz: 22659775c4c299d935a76e9d1ba9f770d973d359e85f68bf0c813663157a9693
+  metadata.gz: 30c13a9edd19ef80be39c8595fff1bcd873fcb73142f22ddc4411b46ca422e34
+  data.tar.gz: 87ac141ad365b30c9b1dd9faedb7a5e796741f6cbfe9aa1aeac7cb8bd61c72cd
 SHA512:
-  metadata.gz: 5f4dd10d03c089fb82417b6bbc883eef15042f07f58b714fc651cf3a4495a5c4afc86275bed3e480487d66c980a41487c7bb80fec12404e760ba2a5f45886f68
-  data.tar.gz: e1b87394b4f173ccabed12fffeddac6c4296aa56117181ff1297f4ded6d3e4374c9e3dd1d1b45f4ffed1a8fc1cf0cd99c3ca1b941d1bab173d1f684c4edc13ef
+  metadata.gz: d735125967e0129352dd4952bec95452ae9cc7b971a56016e2970e10558c73bd12d5b8b9ca9222f998f8e423040b75c86408d5c323602b64b92006e68e8928ea
+  data.tar.gz: 16af951c663bb2e20585842ade8c0a9fac670ecbb818f5c0decfc35a7ae83bbc6eca01fdca709b9e93ae66cf61a4a8d51e0755578b1d87c79cf00eccf9698700

data/CHANGELOG.md

@@ -3,7 +3,11 @@
 All notable changes to this project will be documented in this file.
 This project *loosely tries* to adhere to [Semantic Versioning](http://semver.org/).
 
-## [0.1.0]
+## [0.3.0]
+- add PUMA\_CLOUDWATCH\_ENABLED env var check
+- improve puma-cloudwatch plugin message
+
+## [0.2.0]
 - add PUMA\_CLOUDWATCH\_DEBUG flag
 - fixes for ruby 2.3
 - Update looper.rb puts

data/README.md

@@ -1,22 +1,27 @@
 # Puma Cloudwatch Plugin
 
+[![Gem Version](https://badge.fury.io/rb/puma-cloudwatch.svg)](https://badge.fury.io/rb/puma-cloudwatch)
+
 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:
+**Important**: To enable the plugin to send metrics to CloudWatch you must set the `PUMA_CLOUDWATCH_ENABLED` env variable. This allows you to send only metrics on configured servers and not unintentionally send them locally.
+
+It also strongly encourage to sent the `PUMA_CLOUDWATCH_DIMENSION_VALUE` env variable to include your application name. For example, if your application is named "demo-web", this would be a good value to use:
 
-    PUMA_CLOUDWATCH_DIMENSION_VALUE=myapp-puma
+    PUMA_CLOUDWATCH_DIMENSION_VALUE=demo-web-puma
 
-Then you can get metrics for your `myapp-puma` app. List of metrics:
+Then you can get metrics for your `demo-web-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.
+The `pool_capacity` metric is important. It can be used to show how busy the server is getting before it reaches capacity.  The formula is:
+
+    busy_percent = ( 1 - pool_capacity / max_threads ) * 100
 
 ### Environment Variables
 
@@ -24,17 +29,19 @@ The plugin's settings can be controlled with environmental variables:
 
 Env Var | Description | Default Value
 --- | --- | ---
-PUMA\_CLOUDWATCH\_NAMESPACE | CloudWatch metric namespace | WebServer
+PUMA\_CLOUDWATCH\_DEBUG | When set, the plugin prints out the metrics that get sent to CloudWatch. | (unset)
 PUMA\_CLOUDWATCH\_DIMENSION\_NAME | CloudWatch metric dimension name | App
 PUMA\_CLOUDWATCH\_DIMENSION\_VALUE | CloudWatch metric dimension value | puma
+PUMA\_CLOUDWATCH\_ENABLED | Enables sending of the data to CloudWatch. | (unset)
 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)
+PUMA\_CLOUDWATCH\_NAMESPACE | CloudWatch metric namespace | WebServer
+PUMA\_CLOUDWATCH\_MUTE\_START\_MESSAGE | Mutes the "puma-cloudwatch plugin" startup message | (unset)
 
-### Sum and Frequency
+### Sum and Frequency Normalization
 
-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.
+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 "normalized" and useful. It shows the overall capacity total of the `demo-web-puma` servers.  Particularly, the `pool_capacity` shows available capacity,  and  `pool_threads` shows the total threads configured.
 
-**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 change the CloudWatch send frequency, then Sum statistic must be normalized by changing the period on the chart.  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 for that period.  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 is inherently normalized.
 
@@ -71,4 +78,4 @@ If are you using ECS awsvpc, make sure you have the task running on private subn
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/puma_cloudwatch.
+Bug reports and pull requests are welcome on GitHub at https://github.com/tongueroo/puma-cloudwatch

data/lib/puma_cloudwatch/metrics/looper.rb

@@ -9,16 +9,27 @@ class PumaCloudwatch::Metrics
       @control_url = options[:control_url]
       @control_auth_token = options[:control_auth_token]
       @frequency = Integer(ENV['PUMA_CLOUDWATCH_FREQUENCY'] || 60)
+      @enabled = ENV['PUMA_CLOUDWATCH_ENABLED'] || false
     end
 
     def run
       raise StandardError, "Puma control app is not activated" if @control_url == nil
-      puts "puma-cloudwatch plugin: Will send data every #{@frequency} seconds."
+      puts(message) unless ENV['PUMA_CLOUDWATCH_MUTE']
       Thread.new do
         perform
       end
     end
 
+    def message
+      message = "puma-cloudwatch plugin: Will send data every #{@frequency} seconds."
+      unless @enabled
+        to_enable = "To enable set the environment variable PUMA_CLOUDWATCH_ENABLED=1"
+        message = "Disabled: #{message}\n#{to_enable}"
+      end
+      message
+    end
+
+  private
     def perform
       loop do
         stats = Fetcher.new(@options).call
@@ -27,5 +38,9 @@ class PumaCloudwatch::Metrics
         sleep @frequency
       end
     end
+
+    def enabled?
+      !!@enabled
+    end
   end
 end

data/lib/puma_cloudwatch/metrics/sender.rb

@@ -15,7 +15,8 @@ class PumaCloudwatch::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
+      @dimension_value = ENV['PUMA_CLOUDWATCH_DIMENSION_VALUE'] || "puma"
+      @enabled = ENV['PUMA_CLOUDWATCH_ENABLED'] || false
     end
 
     def call
@@ -75,20 +76,20 @@ class PumaCloudwatch::Metrics
 
   private
     def put_metric_data(params)
-      if noop? or ENV['PUMA_CLOUDWATCH_DEBUG']
+      if ENV['PUMA_CLOUDWATCH_DEBUG']
         message = "sending data to cloudwatch:"
-        message = "NOOP: #{message}" if noop?
+        message = "NOOP: #{message}" unless enabled?
         puts message
         pp params
       end
 
-      unless noop?
+      if enabled?
         cloudwatch.put_metric_data(params)
       end
     end
 
-    def noop?
-      !ENV["PUMA_CLOUDWATCH_NOOP"].nil?
+    def enabled?
+      !!@enabled
     end
 
     def cloudwatch

data/lib/puma_cloudwatch/version.rb

@@ -1,3 +1,3 @@
 module PumaCloudwatch
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puma-cloudwatch
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tung Nguyen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-09-17 00:00:00.000000000 Z
+date: 2019-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: aws-sdk-cloudwatch