librato-rack 0.1.0

data/lib/librato/collector/group.rb

@@ -0,0 +1,29 @@
+module Librato
+  class Collector
+    # abstracts grouping together several similarly named measurements
+    #
+    class Group
+
+      def initialize(collector, prefix)
+        @collector, @prefix = collector, "#{prefix}."
+      end
+
+      def group(prefix)
+        prefix = "#{@prefix}#{prefix}"
+        yield self.class.new(@collector, prefix)
+      end
+
+      def increment(counter, by=1)
+        counter = "#{@prefix}#{counter}"
+        @collector.increment counter, by
+      end
+
+      def measure(*args, &block)
+        args[0] = "#{@prefix}#{args[0]}"
+        @collector.measure(*args, &block)
+      end
+      alias :timing :measure
+
+    end
+  end
+end

data/lib/librato/rack.rb

@@ -0,0 +1,116 @@
+require 'thread'
+require 'librato/metrics'
+
+module Librato
+  extend SingleForwardable
+  def_delegators :tracker, :increment, :measure, :timing, :group
+
+  def self.register_tracker(tracker)
+    @tracker = tracker
+  end
+
+  def self.tracker
+    @tracker ||= Librato::Rack::Tracker.new
+  end
+end
+
+module Librato
+  # Middleware for rack applications. Installs tracking hearbeat for
+  # metric submission and tracks performance metrics.
+  #
+  # @example A basic rack app
+  #   require 'rack'
+  #   require 'librato-rack'
+  #
+  #   app = Rack::Builder.app do
+  #     use Librato::Rack
+  #     run lambda { |env| [200, {"Content-Type" => 'text/html'}, ["Hello!"]]}
+  #   end
+  #
+  class Rack
+    attr_reader :config, :tracker
+
+    def initialize(app, config = Configuration.new)
+      @app, @config = app, config
+      @tracker = Tracker.new(@config)
+      Librato.register_tracker(@tracker) # create global reference
+    end
+
+    def call(env)
+      check_log_output(env)
+      @tracker.check_worker
+      record_header_metrics(env)
+      response, duration = process_request(env)
+      record_request_metrics(response.first, duration)
+      response
+    end
+
+    private
+
+    def check_log_output(env)
+      return if @log_target
+      if env.keys.include?('HTTP_X_HEROKU_QUEUE_DEPTH') # on heroku
+        tracker.on_heroku = true
+        default = ::Logger.new($stdout)
+      else
+        default = env['rack.errors'] || $stderr
+      end
+      config.log_target ||= default
+      @log_target = config.log_target
+    end
+
+    def process_request(env)
+      time = Time.now
+      begin
+        response = @app.call(env)
+      rescue Exception => e
+        record_exception(e)
+        raise
+      end
+      duration = (Time.now - time) * 1000.0
+      [response, duration]
+    end
+
+    def record_header_metrics(env)
+      return unless env.keys.include?('HTTP_X_HEROKU_QUEUE_DEPTH')
+
+      tracker.group 'rack.heroku' do |group|
+        group.group 'queue' do |q|
+          q.measure 'depth',     env['HTTP_X_HEROKU_QUEUE_DEPTH'].to_f
+          q.timing  'wait_time', env['HTTP_X_HEROKU_QUEUE_WAIT_TIME'].to_f
+        end
+        group.measure 'dynos', env['HTTP_X_HEROKU_DYNOS_IN_USE'].to_f
+      end
+    end
+
+    def record_request_metrics(status, duration)
+      tracker.group 'rack.request' do |group|
+        group.increment 'total'
+        group.timing    'time', duration
+        group.increment 'slow' if duration > 200.0
+
+        group.group 'status' do |s|
+          s.increment status
+          s.increment "#{status.to_s[0]}xx"
+
+          s.timing "#{status}.time", duration
+          s.timing "#{status.to_s[0]}xx.time", duration
+        end
+      end
+    end
+
+    def record_exception(exception)
+      tracker.increment 'rack.request.exceptions'
+    end
+
+  end
+end
+
+require 'librato/collector'
+require 'librato/rack/configuration'
+require 'librato/rack/errors'
+require 'librato/rack/logger'
+require 'librato/rack/tracker'
+require 'librato/rack/validating_queue'
+require 'librato/rack/version'
+require 'librato/rack/worker'

data/lib/librato/rack/configuration.rb

@@ -0,0 +1,61 @@
+module Librato
+  class Rack
+    # Holds configuration for Librato::Rack middleware to use.
+    # Acquires some settings by default from environment variables,
+    # but this allows easy setting and overrides.
+    #
+    # @example
+    #   config = Librato::Rack::Configuration.new
+    #   config.user  = 'mimo@librato.com'
+    #   config.token = 'mytoken'
+    #
+    class Configuration
+      attr_accessor :user, :token, :api_endpoint, :tracker, :source_pids,
+                    :log_level, :flush_interval, :log_target
+      attr_reader :prefix, :source
+
+      def initialize
+        # set up defaults
+        self.tracker = nil
+        self.api_endpoint = Librato::Metrics.api_endpoint
+        self.flush_interval = 60
+        self.source_pids = false
+        @listeners = []
+
+        # check environment
+        self.user = ENV['LIBRATO_USER'] || ENV['LIBRATO_METRICS_USER']
+        self.token = ENV['LIBRATO_TOKEN'] || ENV['LIBRATO_METRICS_TOKEN']
+        self.prefix = ENV['LIBRATO_PREFIX'] || ENV['LIBRATO_METRICS_PREFIX']
+        self.source = ENV['LIBRATO_SOURCE'] || ENV['LIBRATO_METRICS_SOURCE']
+        self.log_level = ENV['LIBRATO_LOG_LEVEL'] || :info
+      end
+
+      def explicit_source?
+        !!@explicit_source
+      end
+
+      def prefix=(prefix)
+        @prefix = prefix
+        @listeners.each { |l| l.prefix = prefix }
+      end
+
+      def register_listener(listener)
+        @listeners << listener
+      end
+
+      def source=(src)
+        @source = src
+        @explicit_source = !!@source
+      end
+
+      def dump
+        fields = {}
+        %w{user token log_level source prefix flush_interval source_pids}.each do |field|
+          fields[field.to_sym] = self.send(field)
+        end
+        fields
+      end
+
+    end
+  end
+end

data/lib/librato/rack/errors.rb

@@ -0,0 +1,7 @@
+module Librato
+  class Rack
+
+    class InvalidLogLevel < RuntimeError; end
+
+  end
+end

data/lib/librato/rack/logger.rb

@@ -0,0 +1,71 @@
+require 'logger'
+
+module Librato
+  class Rack
+    # Wraps an available logger object and provides convenience
+    # methods for logging using a separate set of log levels
+    #
+    class Logger
+      LOG_LEVELS = [:off, :error, :warn, :info, :debug, :trace]
+
+      attr_accessor :logger, :prefix
+
+      def initialize(logger)
+        self.logger = logger
+        self.prefix = '[librato-rack] '
+      end
+
+      # @example Simple logging
+      #   log :debug, 'this is a debug message'
+      #
+      # @example Block logging - not executed if won't be logged
+      #   log(:debug) { "found #{thingy} at #{place}" }
+      #
+      def log(level, message=nil, &block)
+        return unless should_log?(level)
+        message = prefix + (message || block.call)
+        if logger.respond_to?(:puts) # io obj
+          logger.puts(message)
+        elsif logger.respond_to?(:error) # logger obj
+          log_to_logger(level, message)
+        else
+          raise "invalid logger object"
+        end
+      end
+
+      # set log level to any of LOG_LEVELS
+      def log_level=(level)
+        level = level.to_sym
+        if LOG_LEVELS.index(level)
+          @log_level = level
+          require 'pp' if should_log?(:debug)
+        else
+          raise InvalidLogLevel, "Invalid log level '#{level}'"
+        end
+      end
+
+      def log_level
+        @log_level ||= :info
+      end
+
+      private
+
+      # write message to an ruby stdlib logger object or another class with
+      # similar interface, respecting log levels when we can map them
+      def log_to_logger(level, message)
+        case level
+        when :error, :warn
+          method = level
+        else
+          method = :info
+        end
+        logger.send(method, message)
+      end
+
+      def should_log?(level)
+        LOG_LEVELS.index(self.log_level) >= LOG_LEVELS.index(level)
+      end
+
+    end
+  end
+end

data/lib/librato/rack/tracker.rb

@@ -0,0 +1,137 @@
+require 'socket'
+
+module Librato
+  class Rack
+    class Tracker
+      extend Forwardable
+
+      SOURCE_REGEX = /\A[-:A-Za-z0-9_.]{1,255}\z/
+
+      def_delegators :collector, :increment, :measure, :timing, :group
+      def_delegators :logger, :log
+
+      attr_reader :config
+      attr_accessor :on_heroku
+
+      def initialize(config)
+        @config = config
+        collector.prefix = config.prefix
+        config.register_listener(collector)
+      end
+
+      # start worker thread, one per process.
+      # if this process has been forked from an one with an active
+      # worker thread we don't need to worry about cleanup, the worker
+      # thread will not pass with the fork
+      def check_worker
+        return if @worker # already running
+        return if !should_start?
+        log(:debug) { "config: #{config.dump}" }
+        @pid = $$
+        log(:debug) { ">> starting up worker for pid #{@pid}..." }
+        @worker = Thread.new do
+          worker = Worker.new
+          worker.run_periodically(config.flush_interval) do
+            flush
+          end
+        end
+      end
+
+      # primary collector object used by this tracker
+      def collector
+        @collector ||= Librato::Collector.new
+      end
+
+      # send all current data to Metrics
+      def flush
+        log :debug, "flushing pid #{@pid} (#{Time.now}).."
+        start = Time.now
+        # thread safety is handled internally for stores
+        queue = build_flush_queue(collector)
+        queue.submit unless queue.empty?
+        log(:trace) { "flushed pid #{@pid} in #{(Time.now - start)*1000.to_f}ms" }
+      rescue Exception => error
+        log :error, "submission failed permanently: #{error}"
+      end
+
+      # source including process pid if indicated
+      def qualified_source
+        config.source_pids ? "#{source}.#{$$}" : source
+      end
+
+      private
+
+      # access to client instance
+      def client
+        @client ||= prepare_client
+      end
+
+      def build_flush_queue(collector)
+        queue = ValidatingQueue.new( :client => client, :source => qualified_source,
+          :prefix => config.prefix, :skip_measurement_times => true )
+        [collector.counters, collector.aggregate].each do |cache|
+          cache.flush_to(queue)
+        end
+        queue.add 'rack.processes' => 1
+        trace_queued(queue.queued) #if should_log?(:trace)
+        queue
+      end
+
+      # trace metrics being sent
+      def trace_queued(queued)
+        require 'pp'
+        log(:trace) { "Queued: " + queued.pretty_inspect }
+      end
+
+      def logger
+        return @logger if @logger
+        @logger = Logger.new(config.log_target)
+        @logger.log_level = config.log_level
+        @logger
+      end
+
+      def prepare_client
+        client = Librato::Metrics::Client.new
+        client.authenticate config.user, config.token
+        client.api_endpoint = config.api_endpoint
+        client.custom_user_agent = user_agent
+        client
+      end
+
+      def ruby_engine
+        return RUBY_ENGINE if Object.constants.include?(:RUBY_ENGINE)
+        RUBY_DESCRIPTION.split[0]
+      end
+
+      def should_start?
+        return false if @pid_checked == $$ # only check once per process
+        @pid_checked = $$
+        if !config.user || !config.token
+          # don't show this unless we're debugging, expected behavior
+          log :debug, 'halting: credentials not present.'
+          false
+        elsif qualified_source !~ SOURCE_REGEX
+          log :warn, "halting: '#{qualified_source}' is an invalid source name."
+          false
+        elsif on_heroku && !config.explicit_source?
+          log :warn, 'halting: source must be provided in configuration.'
+          false
+        else
+          true
+        end
+      end
+
+      def source
+        @source ||= (config.source || Socket.gethostname).downcase
+      end
+
+      def user_agent
+        ua_chunks = []
+        ua_chunks << "librato-rack/#{Librato::Rack::VERSION}"
+        ua_chunks << "(#{ruby_engine}; #{RUBY_VERSION}p#{RUBY_PATCHLEVEL}; #{RUBY_PLATFORM})"
+        ua_chunks.join(' ')
+      end
+
+    end
+  end
+end

data/lib/librato/rack/validating_queue.rb

@@ -0,0 +1,41 @@
+module Librato
+  class Rack
+    # Queue with special upfront validating logic, this should
+    # probably be available in librato-metrics but spiking here
+    # to work out the kinks
+    #
+    class ValidatingQueue < Librato::Metrics::Queue
+      METRIC_NAME_REGEX = /\A[-.:_\w]{1,255}\z/
+      SOURCE_NAME_REGEX = /\A[-:A-Za-z0-9_.]{1,255}\z/
+
+      attr_accessor :logger
+
+      # screen all measurements for validity before sending
+      def submit
+        @queued[:gauges].delete_if do |entry|
+          name = entry[:name].to_s
+          source = entry[:source] && entry[:source].to_s
+          if name !~ METRIC_NAME_REGEX
+            log :warn, "invalid metric name '#{name}', not sending."
+            true # delete
+          elsif source && source !~ SOURCE_NAME_REGEX
+            log :warn, "invalid source name '#{source}', not sending."
+            true # delete
+          else
+            false # preserve
+          end
+        end
+
+        super
+      end
+
+      private
+
+      def log(level, msg)
+        return unless logger
+        logger.log level, msg
+      end
+
+    end
+  end
+end