leafy-rack 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 32375b3191e4984cdda79aeaaae526f855cf073c
+  data.tar.gz: 884c3eec470ff217b30bf0aa8c1fec7fed4a153e
+SHA512:
+  metadata.gz: 8a2b594c128067d6415ff542da326e467d2ea1acf8cf9bdfe2c82f78a487bbb335eb8c412eff89586ee3f345cee872ad435307957cf55eccfa559514dbaa5fe8
+  data.tar.gz: 80ecea5eada8befc856236ec8361c28714aa4597057c4a4a0ac090b39a0bbb923c8f2ab088163b2532fe0ae41d70444ac509aed0aee3c1ddd0781d38298e9e3b

data/.gitignore

@@ -0,0 +1,4 @@
+.yardoc
+doc
+pkg
+*.lock

data/Gemfile

@@ -0,0 +1,10 @@
+#-*- mode: ruby -*-
+
+source 'https://rubygems.org'
+
+gem 'leafy-metrics', :path => '../leafy-metrics'
+gem 'leafy-health', :path => '../leafy-health'
+
+gemspec
+
+# vim: syntax=Ruby

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Lookout
+
+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,155 @@
+# Leafy-Rack
+
+## installation
+
+via rubygems
+```
+gem install leafy-rack
+```
+or add to your Gemfile
+```
+gem 'leafy-rack
+```
+
+installing the gem also takes care of the jar dependencies with jruby-1.7.16+
+
+## intro
+
+there actually three parts to this gem
+
+* serializers to write out json data from the collected data of ```Leafy::Health::Registry``` and ```Leafy::Metrics::Registry```
+
+* instrumented class which is almost like a rack middleware but is threadsafe and is meant to be shared with **ALL** requests. with this sharing in can count the number of active requests.
+
+* a collection of middleware
+
+## serializers for health and metrics data
+
+are using the internal API of ```Leafy::Health::Registry``` or ```Leafy::Metrics::Registry``` to ```run_health_checks``` or retrieve the collect metrics and produces the json representation of these data.
+
+    registry = Leafy::Health::Registry.new
+	json_writer = Leafy::Json::HealthWriter.new
+	json_writer.to_json( registry.health.run_health_checks )
+
+or
+
+    registry = Leafy::Metrics::Registry.new
+	json_writer = Leafy::Json::MetricsWriter.new
+	json_writer.to_json( registry.metrics )
+
+both json writers can take a second argument to generate pretty prints:
+
+	json_writer.to_json( registry.health.run_health_checks, true )  
+	json_writer.to_json( registry.metrics, true )
+
+## instrumented http response
+
+the class ```Leafy::Instrumented::Instrumented``` has a call method which expect a block. the block needs to return the usual rack middleware result ```[status, headers, body]```.
+
+typical usage of this inside a rack-middleware
+
+    metrics = Leafy::Metrics::Registry.new
+    instrumented = Leafy::Instrumented::Instrumented.new( metrics, 'myapp' )
+	instrumented.call do
+       @app.call( env )
+	end
+
+see the ```Leafy::Rack::Instrumented``` for an example.
+
+## rack middleware
+
+* instrumented middleware collecting metrics on response status, response time, and active requests
+* json data of metrics snapshot
+* json data of current health
+* ping
+* java thread-dump
+* admin page with links to metrics, health, ping and thread-dump data
+
+### instrumented middleware
+
+    metrics = Leafy::Metrics::Registry.new
+    use Leafy::Rack::Instrumented, Leafy::Instrumented::Instrumented.new( metrics, 'webapp' )
+
+note: when this instrumented middleware gets configured **after** any of the admin middleware (see below) then those admin requests are not going into the instrumented metrics.
+
+### metrics middleware
+
+json data of a snapshot of metrics are under the path **/metrics**
+
+    metrics = Leafy::Metrics::Registry.new
+    use Leafy::Rack::Metrics, metrics
+
+or with custom path
+
+    metrics = Leafy::Metrics::Registry.new
+    use Leafy::Rack::Metrics, metrics, '/admin/metrics'
+
+### health-checks middleware
+
+json data of current health are under the path **/health**
+
+    health = Leafy::Health::Registry.new
+    use Leafy::Rack::Health, health
+
+or with custom path
+
+    health = Leafy::Health::Registry.new
+    use Leafy::Rack::Health, health, '/admin/health'
+
+### ping middleware
+
+under the path **/ping**
+
+    use Leafy::Rack::Ping
+
+or with custom path
+
+    use Leafy::Rack::Ping, '/admin/ping'
+
+### java thread-dump middleware
+
+under the path **/threads**
+
+    use Leafy::Rack::ThreadDump
+
+or with custom path
+
+    use Leafy::Rack::ThreadDump, '/admin/threads'
+
+
+### admin page middleware
+
+a simple page with links to metrics, health, ping and thread-dump data under the path **/admin**
+
+    metrics = Leafy::Metrics::Registry.new
+    health = Leafy::Health::Registry.new
+
+    use Leafy::Rack::Admin, metrics, health
+
+or with custom path
+
+    metrics = Leafy::Metrics::Registry.new
+    health = Leafy::Health::Registry.new
+
+    use Leafy::Rack::Admin, metrics, health, '/hidden/admin'
+
+## example sinatra app
+
+there is an [example sinatra application](https://github.com/lookout/leafy/tree/master/examples/hellowarld) which uses admin and instrumented middleware and adds some extra metrics inside the application.
+
+## developement
+
+get all the gems and jars in place
+
+    gem install jar-dependencies --development
+	bundle install
+
+please make sure you are using jar-dependencies > 0.1.8 !
+
+for running all specs
+
+	rake
+
+or
+
+    rspec spec/reporter_spec.rb

data/Rakefile

@@ -0,0 +1,14 @@
+#-*- mode: ruby -*-
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new
+
+require "yard"
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+  t.options += ["--title", "Leafy Rack Middleware"]
+end
+
+task :default => [ :spec ]
+
+# vim: syntax=Ruby

data/leafy-rack.gemspec

@@ -0,0 +1,29 @@
+#-*- mode: ruby -*-
+
+require File.expand_path( '../lib/leafy/rack/version', __FILE__ )
+
+Gem::Specification.new do |s|
+  s.name = 'leafy-rack'
+  s.version = Leafy::Rack::VERSION
+  s.author = 'christian meier'
+  s.email = [ 'christian.meier@lookout.com' ]
+
+  s.license = 'MIT'
+  s.summary = %q(rack middleware to expose leafy metrics/health data and more)
+  s.homepage = 'https://github.com/lookout/leafy'
+  s.description = %q(rack middleware to expose leafy metrics/health data as well a ping rack and a thread-dump rack)
+
+  s.files = `git ls-files`.split($/)
+
+  s.requirements << 'jar io.dropwizard.metrics:metrics-json, 3.1.0'
+  s.requirements << 'jar io.dropwizard.metrics:metrics-jvm, 3.1.0'
+
+  s.add_runtime_dependency 'jar-dependencies', '~> 0.1.8'
+  s.add_runtime_dependency 'leafy-metrics', '~> 0.1.0'
+  s.add_runtime_dependency 'leafy-health',  '~> 0.1.0'
+  s.add_development_dependency 'rspec', '~> 3.1.0'
+  s.add_development_dependency 'yard', '~> 0.8.7'
+  s.add_development_dependency 'rake', '~> 10.2'
+end
+
+# vim: syntax=Ruby

data/lib/leafy/instrumented/basic_instrumented.rb

@@ -0,0 +1,38 @@
+module Leafy
+  module Instrumented
+    class BasicInstrumented
+
+      NAME_PREFIX = "responseCodes"
+
+      def initialize( registry, name, meter_names_by_status_code = {} )
+        @meters_by_status_code = java.util.concurrent.ConcurrentHashMap.new
+        meter_names_by_status_code.each do |k,v|
+          @meters_by_status_code[ k ] = registry.register_meter( "#{name}.#{v}" )
+        end
+        @other = registry.register_meter( "#{name}.#{NAME_PREFIX}.other" )
+        @active = registry.register_counter( "#{name}.active_requests" )
+        @timer = registry.register_timer( "#{name}.requests" )
+      end
+
+      def call( &block )
+        raise "block needed" unless block_given?
+        @active.inc
+
+        @timer.time do
+
+          result = block.call
+          mark_meter_for_status_code result[0]
+          result
+
+        end
+      ensure
+        @active.dec
+      end
+
+      def mark_meter_for_status_code( status )
+        metric = @meters_by_status_code[ status ] || @other
+        metric.mark
+      end
+    end
+  end
+end

data/lib/leafy/instrumented/instrumented.rb

@@ -0,0 +1,27 @@
+require 'leafy/instrumented/basic_instrumented'
+
+module Leafy
+  module Instrumented
+    class Instrumented < BasicInstrumented
+
+      OK = 200;
+      CREATED = 201;
+      NO_CONTENT = 204;
+      RESET_CONTENT = 205;
+      BAD_REQUEST = 400;
+      NOT_FOUND = 404;
+      SERVER_ERROR = 500;
+
+      def initialize( registry, name )
+        super( registry, name,
+               { OK => "#{NAME_PREFIX}.ok",
+                 CREATED => "#{NAME_PREFIX}.created",
+                 NO_CONTENT => "#{NAME_PREFIX}.noContent",
+                 RESET_CONTENT => "#{NAME_PREFIX}.resetContent",
+                 BAD_REQUEST => "#{NAME_PREFIX}.badRequest",
+                 NOT_FOUND => "#{NAME_PREFIX}.notFound",
+                 SERVER_ERROR => "#{NAME_PREFIX}.serverError" } )
+      end
+    end
+  end
+end

data/lib/leafy/json/health_writer.rb

@@ -0,0 +1,15 @@
+require 'leafy/health'
+require 'leafy/json/json_writer'
+
+java_import com.codahale.metrics.json.HealthCheckModule
+
+module Leafy
+  module Json
+    class HealthWriter < JsonWriter
+
+      def initialize
+        super( HealthCheckModule.new )
+      end
+    end
+  end
+end

data/lib/leafy/json/json_writer.rb

@@ -0,0 +1,33 @@
+java_import com.fasterxml.jackson.databind.ObjectMapper
+
+module Leafy
+  module Json
+    class JsonWriter
+
+      def initialize( jacksonModule )
+        @mapper = ObjectMapper.new.registerModule( jacksonModule )
+      end
+
+      def data
+        raise 'need implementation'
+      end
+
+      def to_json( data, pretty = false )
+        # TODO make this stream
+        output = java.io.ByteArrayOutputStream.new
+        writer( pretty ).writeValue(output, data);
+        output.to_s
+      end
+  
+      private
+  
+      def writer( pretty )
+        if pretty
+          @mapper.writerWithDefaultPrettyPrinter
+        else
+          @mapper.writer
+        end
+      end
+    end
+  end
+end

data/lib/leafy/json/metrics_writer.rb

@@ -0,0 +1,22 @@
+require 'leafy/metrics'
+require 'leafy/json/json_writer'
+
+java_import com.codahale.metrics.MetricFilter
+java_import com.codahale.metrics.json.MetricsModule
+
+java_import java.util.concurrent.TimeUnit
+
+module Leafy
+  module Json
+    class MetricsWriter < JsonWriter
+
+      def initialize
+        super( # make this configurable
+              MetricsModule.new(TimeUnit::SECONDS,
+                                TimeUnit::SECONDS,
+                                true,
+                                MetricFilter::ALL) )
+      end
+    end
+  end
+end

data/lib/leafy/rack/admin.rb

@@ -0,0 +1,72 @@
+require 'leafy/rack/metrics'
+require 'leafy/rack/health'
+require 'leafy/rack/ping'
+require 'leafy/rack/thread_dump'
+
+module Leafy
+  module Rack
+    class Admin
+      
+      def self.response( path )
+        [  
+         200, 
+         { 'Content-Type' => 'text/html' }, 
+         [ <<EOF
+<DOCTYPE html>
+<html>
+  <head>
+    <title>metrics</title>
+  </head>
+  <body>
+    <h1>menu</h1>
+    <ul>
+      <li><a href='#{path}/metrics'>metrics</a> (<a href='#{path}/metrics?pretty'>pretty</a>)</li>
+      <li><a href='#{path}/health'>health</a> (<a href='#{path}/health?pretty'>pretty</a>)</li>
+      <li><a href='#{path}/ping'>ping</a></li>
+      <li><a href='#{path}/threads'>thread-dump</a></li>
+    </ul>
+  </body>
+</html>  
+EOF
+         ]
+        ]
+      end
+
+      def initialize(app, metrics_registry, health_registry, path = '/admin')
+        @app = app
+        @path = path
+        @metrics = metrics_registry
+        @health = health_registry
+      end
+
+      def call(env)
+        if ( path = env['PATH_INFO'] ).start_with? @path
+          dispatch( path.sub( /#{@path}/, ''), env )
+        else
+          @app.call( env )
+        end
+      end
+
+      private
+
+      def dispatch( path, env )
+        case path
+        when '/metrics'
+          Metrics.response( @metrics.metrics, env )
+        when '/health'
+          Health.response( @health.health, env )
+        when '/ping'
+          Ping.response
+        when '/threads'
+          ThreadDump.response
+        when '/'
+          Admin.response( @path )
+        when ''
+          Admin.response( @path )
+        else # let the app deal with "not found"
+          @app.call( env )
+        end
+      end
+    end
+  end
+end

data/lib/leafy/rack/health.rb

@@ -0,0 +1,36 @@
+require 'leafy/rack'
+require 'leafy/json/health_writer'
+
+module Leafy
+  module Rack
+    class Health
+
+      WRITER = ::Leafy::Json::HealthWriter.new
+
+      def self.response( health, env )
+        data = health.run_health_checks
+        is_healthy = data.values.all? { |r| r.healthy? }
+        [
+         is_healthy ? 200 : 500, 
+         { 'Content-Type' => 'application/json',
+           'Cache-Control' => 'must-revalidate,no-cache,no-store' }, 
+         [ WRITER.to_json( data, env[ 'QUERY_STRING' ] == 'pretty' ) ]
+        ]
+      end
+
+      def initialize(app, registry, path = '/health')
+        @app = app
+        @path = path
+        @registry = registry
+      end
+      
+      def call(env)
+        if env['PATH_INFO'] == @path
+          Health.response( @registry.health, env )
+        else
+          @app.call( env )
+        end
+      end
+    end
+  end
+end

data/lib/leafy/rack/instrumented.rb

@@ -0,0 +1,20 @@
+require 'leafy/rack'
+require 'leafy/instrumented/instrumented'
+
+module Leafy
+  module Rack
+    class Instrumented
+      
+      def initialize( app, instrumented )
+        @app = app
+        @instrumented = instrumented
+      end
+      
+      def call( env )
+        @instrumented.call do
+          @app.call env
+        end
+      end      
+    end
+  end
+end

data/lib/leafy/rack/metrics.rb

@@ -0,0 +1,35 @@
+require 'leafy/rack'
+require 'leafy/metrics'
+require 'leafy/json/metrics_writer'
+module Leafy
+  module Rack
+
+    class Metrics
+
+      WRITER = ::Leafy::Json::MetricsWriter.new
+
+      def self.response( metrics, env )
+        [ 
+         200, 
+         { 'Content-Type' => 'application/json',
+           'Cache-Control' => 'must-revalidate,no-cache,no-store' }, 
+         [ WRITER.to_json( metrics, env[ 'QUERY_STRING' ] == 'pretty' ) ]
+        ]
+      end
+
+      def initialize(app, registry, path = '/metrics')
+        @app = app
+        @path = path
+        @registry = registry
+      end
+      
+      def call(env)
+        if env['PATH_INFO'] == @path
+          Metrics.response( @registry.metrics, env )
+        else
+          @app.call( env )
+        end
+      end
+    end
+  end
+end

data/lib/leafy/rack/ping.rb

@@ -0,0 +1,29 @@
+require 'leafy/rack'
+module Leafy
+  module Rack
+    class Ping
+      
+      def self.response
+        [ 
+         200, 
+         { 'Content-Type' => 'text/plain',
+           'Cache-Control' => 'must-revalidate,no-cache,no-store' }, 
+         [ 'pong' ]
+        ]
+      end
+
+      def initialize(app, path = '/ping')
+        @app = app
+        @path = path
+      end
+
+      def call(env)
+        if env['PATH_INFO'] == @path
+          Ping.response
+        else
+          @app.call( env )
+        end
+      end
+    end
+  end
+end

data/lib/leafy/rack/thread_dump.rb

@@ -0,0 +1,56 @@
+require 'leafy/rack'
+
+java_import java.lang.management.ManagementFactory
+
+module Leafy
+ module Rack
+   class ThreadDumpWriter
+
+      def initialize
+        begin
+          # Some PaaS like Google App Engine blacklist java.lang.managament
+          @threads = com.codahale.metrics.jvm.ThreadDump.new(ManagementFactory.getThreadMXBean());
+        rescue LoadError
+          # we won't be able to provide thread dump
+        end
+      end
+
+      def to_text
+        if @threads
+          # TODO make this stream
+          output = java.io.ByteArrayOutputStream.new
+          @threads.dump(output)
+          output.to_s
+        end
+      end
+    end
+
+    class ThreadDump
+
+      WRITER = ThreadDumpWriter.new
+
+      def self.response
+        dump = WRITER.to_text
+        [  
+         200, 
+         { 'Content-Type' => 'text/plain',
+           'Cache-Control' => 'must-revalidate,no-cache,no-store' }, 
+         [ dump ? dump : 'Sorry your runtime environment does not allow to dump threads.' ]
+        ]
+      end
+
+      def initialize(app, path = '/threads')
+        @app = app
+        @path = path
+      end
+
+      def call(env)
+        if env['PATH_INFO'] == @path
+          ThreadDump.response
+        else
+          @app.call( env )
+        end
+      end
+    end
+  end
+end

data/lib/leafy/rack/version.rb

@@ -0,0 +1,6 @@
+module Leafy
+  module Rack
+    VERSION = '0.1.0'.freeze
+  end
+end
+    

data/lib/leafy/rack.rb

@@ -0,0 +1 @@
+require 'leafy-rack_jars'

data/lib/leafy-rack.rb

@@ -0,0 +1 @@
+require 'leafy/rack'

data/lib/leafy-rack_jars.rb

@@ -0,0 +1,10 @@
+# this is a generated file, to avoid over-writing it just delete this comment
+require 'jar_dependencies'
+
+require_jar( 'com.fasterxml.jackson.core', 'jackson-annotations', '2.4.0' )
+require_jar( 'com.fasterxml.jackson.core', 'jackson-core', '2.4.2' )
+require_jar( 'org.slf4j', 'slf4j-api', '1.7.7' )
+require_jar( 'io.dropwizard.metrics', 'metrics-jvm', '3.1.0' )
+require_jar( 'io.dropwizard.metrics', 'metrics-core', '3.1.0' )
+require_jar( 'com.fasterxml.jackson.core', 'jackson-databind', '2.4.2' )
+require_jar( 'io.dropwizard.metrics', 'metrics-json', '3.1.0' )