backlog_reporter 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6eb400858084826fc89a815e578f16df5eda6239
+  data.tar.gz: 2588b718a53a120e52c46d041f3e7c46268eb7a1
+SHA512:
+  metadata.gz: 4d435dad0c4d13c40910a87eeb8afa74b73c44453f286b0d726188b53b56c17be046ef32873c5d6ff7aa92dae451bb87555a0d273a271744b982eefe6612992e
+  data.tar.gz: 29a5529a6dfbbcfee7c6c09d7a54d401b2a29abe6c433ef3b8d475699cf866e322428218d555c7c868786a74bd34abdc50c01f5bba01de15e63d1e8411253e69

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.4
+before_install: gem install bundler -v 1.12.5

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+0.2.0
+* Renamed gem from puma_backlog_detector to backlog_reporter
+
+0.1.1
+* Correct homepage in spec
+* Specify license
+
+0.1.0
+* Initial release

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+#ruby=ruby-2.2.4
+#ruby-gemset=backlog-reporter
+
+# Specify your gem's dependencies in backlog_reporter.gemspec
+gemspec
+
+gem 'ci_reporter_rspec', group: :test

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 Conjur Inc.
+
+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,76 @@
+# Backlog Reporter
+
+This gem monitors the size of the web server internal request backlog. (The backlog is requests whose socket has been accepted, but which are not yet being processed by the web server.) Once the request backlog exceeds a certain threshold, a flag file is touched. This flag file can be monitored by a fronting web server (e.g. Nginx) to proactively return 503 Service Unavailable, so that the backlog does not grow further. Once the request backlog falls back below the threshold, the flag file is deleted.
+
+The rapid 503 response prevents the backlog from growing without bound, and it prevents the server from trying to process too many requests in parallel. When the server is trying to process too many requests at once, the average latency starts to climb and all clients start to see longer and longer response times.
+
+# Requirements
+
+Currently, `backlog_reporter` works only with the Puma web server. 
+
+# Example
+
+Here's an example of a web service whose behavior was improved with the Backlog Reporter.
+
+## Without Backlog Reporter
+
+At the 10 request per second rate, the response time starts to degrade until it climbs above 20 seconds per request and the remainder of the requests time out.
+
+![Before backlog reporter](./doc/images/before_backlog.png)
+
+## With Backlog Reporter
+
+Once the server starts to become overloaded, it degrades in a predictable way. The average response time increases to about 5 seconds; however, it does not increase further from this level. With client retry, all requests will eventually be served successfully.
+
+![After backlog reporter](./doc/images/after_backlog.png)
+
+(Note: The performance of this application was also improved at the same time; that's why even the initial responses are faster).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'backlog_reporter'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install backlog_reporter
+
+## Usage
+
+In rails config:
+
+```ruby
+  config.backlog_reporter.flag_path = '/run/app/congested.flag'
+  config.backlog_reporter.max_backlog = 16
+  config.backlog_reporter.check_interval = 0.01 # seconds
+```
+
+In nginx config:
+
+```
+  location / {
+    proxy_pass http://localhost:300;
+
+    if (-f /run/app/congested.flag) {
+      return 503;
+    }
+  }
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/conjurinc/backlog-reporter.
+

data/Rakefile

@@ -0,0 +1,34 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+task :headers do
+  require 'rubygems'
+  require 'copyright_header'
+
+  spec = Gem::Specification.load 'puma_backlog_detector.gemspec'
+
+  args = {
+    license: spec.license,
+    copyright_software: spec.name,
+    copyright_software_description: spec.summary,
+    :copyright_holders => ['Conjur Inc.'],
+    :copyright_years => ['2016'],
+    :add_path => 'lib:spec',
+    :output_dir => '.'
+  }
+
+  command_line = CopyrightHeader::CommandLine.new( args )
+  command_line.execute
+end
+
+begin
+  require 'ci/reporter/rake/rspec'
+
+  task jenkins: ['ci:setup:rspec', :spec]
+rescue LoadError
+  # expected on non-jenkins
+end

data/backlog_reporter.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'backlog_reporter/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "backlog_reporter"
+  spec.version       = BacklogReporter::VERSION
+  spec.authors       = ["Rafał Rzepecki"]
+  spec.email         = ["rafal@conjur.net"]
+  spec.license = "MIT"
+
+  spec.summary       = %q{Periodically check Puma backlog and write a flag file}
+  spec.homepage      = "https://github.com/conjurinc/backlog-reporter"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "puma", "~> 3.6"
+  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "puma_backlog_detector"
+
+# 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

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/doc/images/.keep

@@ -0,0 +1 @@
+

data/jenkins.sh

@@ -0,0 +1,4 @@
+#!/bin/sh -xe
+
+bundle
+rake jenkins || :

data/lib/backlog_reporter/railtie.rb

@@ -0,0 +1,36 @@
+#
+# Copyright (C) 2016 Conjur Inc.
+#
+# 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.
+#
+class BacklogReporter
+  class Railtie < Rails::Railtie
+    config.backlog_reporter = ActiveSupport::OrderedOptions.new
+    config.backlog_reporter.max_backlog = 16
+    config.backlog_reporter.check_interval = 0.01
+    config.backlog_reporter.flag_path = nil
+
+    initializer "backlog_reporter.run" do
+      conf = config.backlog_reporter
+      if conf.flag_path
+        @backlog_reporter = BacklogReporter.new conf.flag_path, conf.max_backlog
+        @backlog_reporter.check_in_background conf.check_interval
+      end
+    end
+  end
+end

data/lib/backlog_reporter/version.rb

@@ -0,0 +1,23 @@
+#
+# Copyright (C) 2016 Conjur Inc.
+#
+# 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.
+#
+class BacklogReporter
+  VERSION = "0.2.0"
+end

data/lib/backlog_reporter.rb

@@ -0,0 +1,69 @@
+#
+# Copyright (C) 2016 Conjur Inc.
+#
+# 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.
+#
+require "backlog_reporter/version"
+require "backlog_reporter/railtie" if defined? Rails
+
+class BacklogReporter
+  def initialize flag_path, max_backlog = 16
+    @flag = FlagFile.new flag_path
+    @max_backlog = max_backlog
+  end
+
+  def check
+    if server = Puma::Server.current
+      @flag.set server.backlog > @max_backlog
+    end
+  end
+
+  def check_periodically interval_s = 0.01
+    while true
+      check
+      sleep interval_s
+    end
+  end
+
+  def check_in_background interval_s = 0.01
+    @thread = Thread.new { check_periodically interval_s }
+  end
+
+  def stop
+    if @thread
+      @thread.exit
+      @thread.join
+      @thread = nil
+    end
+  end
+
+  class FlagFile
+    def initialize path
+      @path = path
+      @exists = File.exists? path
+      set false
+    end
+
+    def set value
+      if @exists != value
+        FileUtils.send((value ? :touch : :rm_f), @path)
+        @exists = value
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: backlog_reporter
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Rafał Rzepecki
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-09-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: puma
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !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:
+- rafal@conjur.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- .travis.yml
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- backlog_reporter.gemspec
+- bin/console
+- bin/setup
+- doc/images/.keep
+- doc/images/after_backlog.png
+- doc/images/before_backlog.png
+- jenkins.sh
+- lib/backlog_reporter.rb
+- lib/backlog_reporter/railtie.rb
+- lib/backlog_reporter/version.rb
+homepage: https://github.com/conjurinc/backlog-reporter
+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.0.14.1
+signing_key: 
+specification_version: 4
+summary: Periodically check Puma backlog and write a flag file
+test_files: []
+has_rdoc: