librato-rails 0.9.0 → 0.10.0.pre1

data/CHANGELOG.md

@@ -1,3 +1,17 @@
+### Version 0.10.0.pre1
+* Add render instrumentation metrics
+* Add cache instrumentation metrics
+* Add metrics on HTTP method use
+* Rack middleware moved from end of stack to beginning, improving value of rack metrics (Thibaud Guillaume-Gentil)
+* Add ability to control startup with LIBRATO_AUTORUN
+* Add ability to force startup in console mode with LIBRATO_AUTORUN
+* Refactor to use librato-rack
+* Remove old deprecated heroku-specific stats
+* Fix startup bug when using unicorn with preload false
+* Fix bug where grouped instrumentation could lose some options
+* Sign gem when building
+* Documentation improvements
+
 ### Version 0.9.0
 * Bump librato-metrics dependency version for new functionality
 

data/FAQ.md

@@ -0,0 +1,25 @@
+# Frequently asked questions for librato-rails
+
+#### What is the difference between rack.request.time and rails.request.time, etc?
+
+The `rails.request.*` metrics are reported using rails' built-in instrumentation and show rails' [internal benchmarks](http://edgeguides.rubyonrails.org/active_support_instrumentation.html) for request execution.
+
+The `rack.request.*` metrics are generated from within the rack middleware and are guaranteed to always be greater than or equal to rails' real execution time.
+
+On versions of `librato-rails` prior to 0.9.0 these can appear similar as the middleware is loaded on the top of the stack but on 0.9.0 or greater the entire middleware stack is recorded. Recording the whole stack gives you a better sense of actual request processing time and also the ability to differentiate how many of your requests are being handled in middleware and what percentage of your request time is being taken up by middleware.
+
+#### I've noticed that the HTTP request sending my metrics sometimes takes a while, isn't that slowing down my web server or limiting how many requests I can handle?
+
+Submissions to the Librato service take place in a background thread which runs extremely quickly and has minimal impact on your primary request-serving thread or threads.
+
+The only time that the worker uses any CPU is to package up submissions, which is highly optimized. While the worker thread is sleeping or waiting for a response it is non-blocking and doesn't compete with your request-serving threads.
+
+Even if you are using a single-threaded _app server_ like unicorn or thin, you are still running in a multi-threaded _environment_ (the ruby interpreter) so the worker thread will run and report successfully.
+
+#### With a `LOG_LEVEL` of debug or trace I sometimes don't see a worker start for each process
+
+`librato-rails` logs metrics for requests both within the rack middleware and within rails itself. Certain requests may be handled entirely within the rack middleware - these never reach the rails tier at all.
+
+If the first request a process gets is a rack-only process the rails log is unavailable and the startup message may be lost.
+
+However, with a level of `debug` or `trace` you should be able to see flush messages for every worker that is running, even if the startup message is not logged. You can also use the `rack.processes` metric to see how many processes are reporting.

data/README.md

@@ -1,7 +1,7 @@
 librato-rails
 =======
 
-[![Build Status](https://secure.travis-ci.org/librato/librato-rails.png?branch=master)](http://travis-ci.org/librato/librato-rails)
+[![Gem Version](https://badge.fury.io/rb/librato-rails.png)](http://badge.fury.io/rb/librato-rails) [![Build Status](https://secure.travis-ci.org/librato/librato-rails.png?branch=master)](http://travis-ci.org/librato/librato-rails) [![Code Climate](https://codeclimate.com/github/librato/librato-rails.png)](https://codeclimate.com/github/librato/librato-rails)
 
 `librato-rails` will report key statistics for your Rails app to [Librato Metrics](https://metrics.librato.com/) and allow you to easily track your own custom metrics. Metrics are delivered asynchronously behind the scenes so they won't affect performance of your requests.
 
@@ -207,10 +207,17 @@ end
 
 These are just a few examples. Combining `ActiveSupport::Notifications` instrumentation with Librato can be extremely powerful. As an added benefit, using the instrument/subscribers model allows you to isolate complex instrumentation code from your main application codebase.
 
-## Custom Prefix
+## Custom Prefixes
 
 You can set an optional prefix to all metrics reported by `librato-rails` in your [configuration](https://github.com/librato/librato-rails/wiki/Configuration). This can be helpful for isolating test data or forcing different apps to use different metric names.
 
+## Use with Background Workers / Cron Jobs
+
+`librato-rails` is designed to run within a long-running process and report periodically. Intermittently running rake tasks and most background job tools (delayed job, resque, queue_classic) don't run long enough for this to work.
+
+Never fear, [we have some guidelines](https://github.com/librato/librato-rails/wiki/Monitoring-Background-Workers) for how to instrument your workers properly.
+
+
 ## Cross-Process Aggregation
 
 `librato-rails` submits measurements back to the Librato platform on a _per-process_ basis. By default these measurements are then combined into a single measurement per source (default is your hostname) before persisting the data.
@@ -227,6 +234,8 @@ Note that it may take 2-3 minutes for the first results to show up in your Metri
 
 If you want to get more information about `librato-rails` submissions to the Metrics service you can set your `log_level` to `debug` (see [configuration](https://github.com/librato/librato-rails/wiki/Configuration)) to get detailed information added to your logs about the settings `librato-rails` is seeing at startup and when it is submitting.
 
+Be sure to tail your logs manually (`tail -F <logfile>`) as the log output you get when using the `rails server` command often skips startup log lines.
+
 If you are having an issue with a specific metric, using a `log_level` of `trace` will add the exact measurements being sent to your logs along with lots of other information about `librato-rails` as it executes. Neither of these modes are recommended long-term in production as they will add quite a bit of volume to your log file and will slow operation somewhat. Note that submission I/O is non-blocking, submission times are total time - your process will continue to handle requests during submissions.
 
 If you are debugging setting up `librato-rails` locally you can set `flush_interval` to something shorter (say 10s) to force submission more frequently. Don't change your `flush_interval` in production as it will not result in measurements showing up more quickly, but may affect performance.

data/lib/librato/rails/configuration.rb

@@ -1,52 +1,49 @@
 module Librato
   module Rails
-    module Configuration
+    # Adds yaml-based config and extra properties to the configuration
+    # class provided by librato-rack
+    #
+    # https://github.com/librato/librato-rack/blob/master/lib/librato/rack/configuration.rb
+    #
+    class Configuration < Rack::Configuration
       CONFIG_SETTABLE = %w{user token flush_interval log_level prefix source source_pids}
 
-      mattr_accessor :config_file
-      self.config_file = 'config/librato.yml'
+      attr_accessor :config_by, :config_file
 
-      # set custom api endpoint
-      def api_endpoint=(endpoint)
-        @api_endpoint = endpoint
+      # options:
+      # * :config_file - alternate config file location
+      #
+      def initialize(options={})
+        self.config_file = options[:config_file] || 'config/librato.yml'
+        super()
+        self.log_prefix = '[librato-rails] '
       end
 
-      # detect / update configuration
-      def check_config
-        self.log_level = ENV['LIBRATO_LOG_LEVEL'] if ENV['LIBRATO_LOG_LEVEL']
+      # detect and load configuration from config file or env vars
+      def load_configuration
         if self.config_file && File.exists?(self.config_file)
           configure_with_config_file
         else
-          configure_with_environment
+          self.config_by = :environment
+          super
         end
+
+        # respect autorun and log_level env vars regardless of config method
+        self.autorun = detect_autorun
+        self.log_level = ENV['LIBRATO_LOG_LEVEL'] if ENV['LIBRATO_LOG_LEVEL']
       end
 
       private
 
       def configure_with_config_file
-        log :debug, "configuring with librato.yml; ignoring environment variables.."
-        if env_specific = YAML.load(ERB.new(File.read(config_file)).result)[::Rails.env]
+        self.config_by = :config_file
+        env_specific = YAML.load(ERB.new(File.read(config_file)).result)[::Rails.env]
+        if env_specific
           settable = CONFIG_SETTABLE & env_specific.keys
           settable.each { |key| self.send("#{key}=", env_specific[key]) }
-        else
-          log :debug, "halting: current environment (#{::Rails.env}) not in config file."
-        end
-      end
-
-      def configure_with_environment
-        log :debug, "using environment variables for configuration.."
-        %w{user token source log_level prefix}.each do |settable|
-          legacy_env_var = "LIBRATO_METRICS_#{settable.upcase}"
-          if ENV[legacy_env_var]
-            log :warn, "#{legacy_env_var} is deprecated, use LIBRATO_#{settable.upcase} instead"
-            send("#{settable}=", ENV[legacy_env_var])
-          end
-          # if both are present, new-style dominates
-          env_var = "LIBRATO_#{settable.upcase}"
-          send("#{settable}=", ENV[env_var]) if ENV[env_var]
         end
       end
 
     end
   end
-end
+end

data/lib/librato/rails/railtie.rb

@@ -2,15 +2,40 @@ module Librato
   module Rails
     class Railtie < ::Rails::Railtie
 
+      # don't have any custom http vars anymore, check if hostname is UUID
+      on_heroku = Socket.gethostname =~ /[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/i
+
       # make configuration proxy for config inside Rails
-      config.librato_rails = Librato::Rails
+      config.librato_rails = Configuration.new
+
+      # set up tracker
+      tracker = Tracker.new(config.librato_rails)
+      config.librato_rails.tracker = tracker
+      Librato.register_tracker(tracker)
+
+      unless ::Rails.env.test?
+        unless defined?(::Rails::Console) && ENV['LIBRATO_AUTORUN'] != '1'
+
+          initializer 'librato_rails.setup' do |app|
+            # set up logging; heroku needs logging to STDOUT
+            if on_heroku
+              logger = Logger.new(STDOUT)
+              logger.level = Logger::INFO
+            else
+              logger = ::Rails.logger
+            end
+            config.librato_rails.log_target = logger
+            tracker.log(:debug) { "config: #{config.librato_rails.dump}" }
+
+            if tracker.should_start?
+              tracker.log :info, "starting up (pid #{$$}, using #{config.librato_rails.config_by})..."
+              app.middleware.insert(0, Librato::Rack, :config => config.librato_rails)
+            end
+          end
 
-      initializer 'librato_rails.setup' do |app|
-        # don't start in test mode or in the console
-        unless ::Rails.env.test? || defined?(::Rails::Console)
-          Librato::Rails.setup(app)
         end
       end
+
     end
   end
 end

data/lib/librato/rails/subscribers/cache.rb

@@ -0,0 +1,22 @@
+module Librato
+  module Rails
+    module Subscribers
+
+      # Cache
+
+      %w{read generate fetch_hit write delete}.each do |metric|
+
+        ActiveSupport::Notifications.subscribe "cache_#{metric}.active_support" do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+
+          collector.group "rails.cache" do |c|
+            c.increment metric
+            c.timing "#{metric}.time", event.duration
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/librato/rails/subscribers/controller.rb

@@ -0,0 +1,56 @@
+module Librato
+  module Rails
+    module Subscribers
+
+      # Controllers
+
+      ActiveSupport::Notifications.subscribe 'process_action.action_controller' do |*args|
+
+        event = ActiveSupport::Notifications::Event.new(*args)
+        controller = event.payload[:controller]
+        action = event.payload[:action]
+
+        format = event.payload[:format] || "all"
+        format = "all" if format == "*/*"
+        status = event.payload[:status]
+        http_method = event.payload[:method]
+        exception = event.payload[:exception]
+        # page_key = "request.#{controller}.#{action}_#{format}."
+
+        collector.group "rails.request" do |r|
+
+          r.increment 'total'
+          r.timing    'time', event.duration
+
+          if exception
+            r.increment 'exceptions'
+          else
+            r.timing 'time.db', event.payload[:db_runtime] || 0
+            r.timing 'time.view', event.payload[:view_runtime] || 0
+          end
+
+          if http_method
+            http_method.downcase!
+            r.group 'method' do |m|
+              m.increment http_method
+              m.timing "#{http_method}.time", event.duration
+            end
+          end
+
+          unless status.blank?
+            r.group 'status' do |s|
+              s.increment status
+              s.increment "#{status.to_s[0]}xx"
+              s.timing "#{status}.time", event.duration
+              s.timing "#{status.to_s[0]}xx.time", event.duration
+            end
+          end
+
+          r.increment 'slow' if event.duration > 200.0
+        end # end group
+
+      end # end subscribe
+
+    end
+  end
+end

data/lib/librato/rails/subscribers/mail.rb

@@ -0,0 +1,18 @@
+module Librato
+  module Rails
+    module Subscribers
+
+      # ActionMailer
+
+      ActiveSupport::Notifications.subscribe 'deliver.action_mailer' do |*args|
+        # payload[:mailer] => 'UserMailer'
+        collector.increment "rails.mail.sent"
+      end
+
+      ActiveSupport::Notifications.subscribe 'receive.action_mailer' do |*args|
+        collector.increment "rails.mail.received"
+      end
+
+    end
+  end
+end

data/lib/librato/rails/subscribers/render.rb

@@ -0,0 +1,28 @@
+module Librato
+  module Rails
+    module Subscribers
+
+      # Render operations
+
+      %w{partial template}.each do |metric|
+
+        ActiveSupport::Notifications.subscribe "render_#{metric}.action_view" do |*args|
+          event = ActiveSupport::Notifications::Event.new(*args)
+          path = event.payload[:identifier].split('/views/', 2)
+
+          if path[1]
+            source = path[1].gsub('/', ':')
+            # trim leading underscore for partial sources
+            source.gsub!(':_', ':') if metric == 'partial'
+            collector.group "rails.view" do |c|
+              c.increment "render_#{metric}", source: source, sporadic: true
+              c.timing "render_#{metric}.time", event.duration, source: source, sporadic: true
+            end
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/librato/rails/subscribers/sql.rb

@@ -0,0 +1,24 @@
+module Librato
+  module Rails
+    module Subscribers
+
+      # SQL
+
+      ActiveSupport::Notifications.subscribe 'sql.active_record' do |*args|
+        payload = args.last
+
+        collector.group "rails.sql" do |s|
+          # puts (event.payload[:name] || 'nil') + ":" + event.payload[:sql] + "\n"
+          s.increment 'queries'
+
+          sql = payload[:sql].strip
+          s.increment 'selects' if sql.starts_with?('SELECT')
+          s.increment 'inserts' if sql.starts_with?('INSERT')
+          s.increment 'updates' if sql.starts_with?('UPDATE')
+          s.increment 'deletes' if sql.starts_with?('DELETE')
+        end
+      end
+
+    end
+  end
+end

data/lib/librato/rails/subscribers.rb

@@ -1,77 +1,22 @@
+require 'active_support/notifications'
+
 module Librato
   module Rails
 
-    # controllers
-
-    ActiveSupport::Notifications.subscribe /process_action.action_controller/ do |*args|
-
-      event = ActiveSupport::Notifications::Event.new(*args)
-      controller = event.payload[:controller]
-      action = event.payload[:action]
-
-      format = event.payload[:format] || "all"
-      format = "all" if format == "*/*"
-      status = event.payload[:status]
-      exception = event.payload[:exception]
-      # page_key = "request.#{controller}.#{action}_#{format}."
-
-      group "rails.request" do |r|
-
-        r.increment 'total'
-        r.timing    'time', event.duration
-
-        if exception
-          r.increment 'exceptions'
-        else
-          r.timing 'time.db', event.payload[:db_runtime] || 0
-          r.timing 'time.view', event.payload[:view_runtime] || 0
-        end
-
-        unless status.blank?
-          r.group 'status' do |s|
-            s.increment status
-            s.increment "#{status.to_s[0]}xx"
-            s.timing "#{status}.time", event.duration
-            s.timing "#{status.to_s[0]}xx.time", event.duration
-          end
-        end
-
-        r.increment 'slow' if event.duration > 200.0
-      end # end group
-
-    end # end subscribe
-
-    # SQL
+    # defines basic context that all librato-rails subscribers will run in
+    module Subscribers
 
-    ActiveSupport::Notifications.subscribe 'sql.active_record' do |*args|
-      payload = args.last
-
-      group "rails.sql" do |s|
-        # puts (event.payload[:name] || 'nil') + ":" + event.payload[:sql] + "\n"
-        s.increment 'queries'
-
-        sql = payload[:sql].strip
-        s.increment 'selects' if sql.starts_with?('SELECT')
-        s.increment 'inserts' if sql.starts_with?('INSERT')
-        s.increment 'updates' if sql.starts_with?('UPDATE')
-        s.increment 'deletes' if sql.starts_with?('DELETE')
-      end
-    end
-
-    # ActionMailer
-
-    ActiveSupport::Notifications.subscribe 'deliver.action_mailer' do |*args|
-      # payload[:mailer] => 'UserMailer'
-      group "rails.mail" do |m|
-        m.increment 'sent'
+      # make collector object directly available, it won't be changing
+      def self.collector
+        @collector ||= Librato.tracker.collector
       end
-    end
 
-    ActiveSupport::Notifications.subscribe 'receive.action_mailer' do |*args|
-      group "rails.mail" do |m|
-        m.increment 'received'
-      end
     end
-
   end
-end
+end
+
+require_relative 'subscribers/cache'
+require_relative 'subscribers/controller'
+require_relative 'subscribers/render'
+require_relative 'subscribers/sql'
+require_relative 'subscribers/mail'

data/lib/librato/rails/tracker.rb

@@ -0,0 +1,13 @@
+module Librato
+  module Rails
+    class Tracker < Rack::Tracker
+
+      private
+
+      def version_string
+        "librato-rails/#{Librato::Rails::VERSION}"
+      end
+
+    end
+  end
+end

data/lib/librato/rails/version.rb

@@ -1,5 +1,5 @@
 module Librato
   module Rails
-    VERSION = "0.9.0"
+    VERSION = "0.10.0.pre1"
   end
 end