timber 2.0.24 → 2.1.0.rc1

data/lib/timber/integrations/active_record/log_subscriber.rb

@@ -1,3 +1,5 @@
+require "timber/integrator"
+
 module Timber
   module Integrations
     module ActiveRecord

data/lib/timber/integrations/active_record/log_subscriber/timber_log_subscriber.rb

@@ -4,6 +4,8 @@
 require "active_record"
 require "active_record/log_subscriber"
 
+require "timber/integrator"
+
 module Timber
   module Integrations
     module ActiveRecord
@@ -16,6 +18,8 @@ module Timber
         # @private
         class TimberLogSubscriber < ::ActiveRecord::LogSubscriber
           def sql(event)
+            return true if silence?
+
             r = super(event)
 
             if @message
@@ -38,6 +42,10 @@ module Timber
             def debug(message)
               @message = message
             end
+
+            def silence?
+              ActiveRecord.silence?
+            end
         end
       end
     end

data/lib/timber/integrations/rack.rb

@@ -7,10 +7,20 @@ require "timber/integrations/rack/user_context"
 module Timber
   module Integrations
     module Rack
-      # All available middlewares. The order is relevant. Middlewares that set
+      # Enable / disable all Rack middlewares with a single setting.
+      def self.enabled=(value)
+        ExceptionEvent.enabled = value
+        HTTPContext.enabled = value
+        HTTPEvents.enabled = value
+        SessionContext.enabled = value
+        UserContext.enabled = value
+      end
+
+      # All enabled middlewares. The order is relevant. Middlewares that set
       # context are added first so that context is included in subsequent log lines.
       def self.middlewares
-        @middlewares ||= [HTTPContext, SessionContext, UserContext, HTTPEvents, ExceptionEvent]
+        @middlewares ||= [HTTPContext, SessionContext, UserContext,
+          HTTPEvents, ExceptionEvent].select(&:enabled?)
       end
     end
   end

data/lib/timber/integrations/rack/exception_event.rb

@@ -1,10 +1,21 @@
+begin
+  require "action_dispatch/middleware/exception_wrapper"
+rescue Exception
+end
+
+require "timber/integrations/rack/middleware"
+
 module Timber
   module Integrations
     module Rack
-      # Reponsible for capturing exceptions events within a Rack stack.
-      class ExceptionEvent
-        def initialize(app)
-          @app = app
+      # A Rack middleware that is reponsible for capturing exceptions events
+      # {Timber::Events::Exception}.
+      class ExceptionEvent < Middleware
+        # We determine this when the app loads to avoid the overhead on a per request basis.
+        EXCEPTION_WRAPPER_TAKES_CLEANER = if Gem.loaded_specs["rails"]
+          Gem.loaded_specs["rails"].version >= Gem::Version.new('5.0.0')
+        else
+          false
         end
 
         def call(env)
@@ -12,16 +23,38 @@ module Timber
             status, headers, body = @app.call(env)
           rescue Exception => exception
             Config.instance.logger.fatal do
+              backtrace = extract_backtrace(env, exception)
+
               Events::Exception.new(
                 name: exception.class.name,
                 exception_message: exception.message,
-                backtrace: exception.backtrace
+                backtrace: backtrace
               )
             end
 
             raise exception
           end
         end
+
+        private
+          # Rails provides a backtrace cleaner, so we use it here.
+          def extract_backtrace(env, exception)
+            if defined?(::ActionDispatch::ExceptionWrapper)
+              wrapper = if EXCEPTION_WRAPPER_TAKES_CLEANER
+                request = Util::Request.new(env)
+                backtrace_cleaner = request.get_header("action_dispatch.backtrace_cleaner")
+                ::ActionDispatch::ExceptionWrapper.new(backtrace_cleaner, exception)
+              else
+                ::ActionDispatch::ExceptionWrapper.new(env, exception)
+              end
+
+              trace = wrapper.application_trace
+              trace = wrapper.framework_trace if trace.empty?
+              trace
+            else
+              exception.backtrace
+            end
+          end
       end
     end
   end

data/lib/timber/integrations/rack/http_context.rb

@@ -1,12 +1,10 @@
+require "timber/integrations/rack/middleware"
+
 module Timber
   module Integrations
     module Rack
-      # Reponsible for adding the HTTP context for applications that use `Rack`.
-      class HTTPContext
-        def initialize(app)
-          @app = app
-        end
-
+      # A Rack middleware that is reponsible for adding the HTTP context {Timber::Contexts::HTTP}.
+      class HTTPContext < Middleware
         def call(env)
           request = Util::Request.new(env)
           context = Contexts::HTTP.new(

data/lib/timber/integrations/rack/http_events.rb

@@ -1,43 +1,193 @@
+require "set"
+
+require "timber/integrations/rack/middleware"
+
 module Timber
   module Integrations
     module Rack
-      # Reponsible for capturing and logging HTTP server requests and response events.
-      class HTTPEvents
-        def initialize(app)
-          @app = app
+      # A Rack middleware that is reponsible for capturing and logging HTTP server requests and
+      # response events. The {Events::HTTPServerRequest} and {Events::HTTPServerResponse} events
+      # respectively.
+      class HTTPEvents < Middleware
+        class << self
+          # Allows you to capture the HTTP request body, default is off (false).
+          #
+          # Capturing HTTP bodies can be extremely helpful when debugging issues,
+          # but please proceed with caution:
+          #
+          # 1. Capturing HTTP bodies can use quite a bit of data (this can be mitigated, see below)
+          # 2. The {Events::ControllerCall} event captures the parsed parmaters sent to
+          #    the controller. This is a parsed representation of the body, which is usually more
+          #    helpful and redundant to the body captured here.
+          #
+          # If you opt to capture bodies, you can also truncate the size to reduce the data
+          # captured. See {Events::HTTPServerRequest}.
+          #
+          # @example
+          #   Timber::Integrations::Rack::HTTPEvents.capture_request_body = true
+          def capture_request_body=(value)
+            @capture_request_body = value
+          end
+
+          # Accessor method for {#capture_request_body=}
+          def capture_request_body?
+            @capture_request_body == true
+          end
+
+          # Just like {#capture_request_body=} but for the {Events::HTTPServerResponse} event.
+          # Please see {#capture_request_body=} for more details. The documentation there also
+          # applies here.
+          def capture_response_body=(value)
+            @capture_response_body = value
+          end
+
+          # Accessor method for {#capture_response_body=}
+          def capture_response_body?
+            @capture_response_body == true
+          end
+
+          # Collapse both the HTTP request and response events into a single log line event.
+          # While we don't recommend this, it can help to reduce log volume if desired.
+          # The reason we don't recommend this, is because the logging service you use should
+          # not be so expensive that you need to strip out useful logs. It should also provide
+          # the tools necessary to properly search your logs and reduce noise. Such as viewing
+          # logs for a specific request.
+          #
+          # To provide an example. This setting turns this:
+          #
+          #   Started GET "/" for 127.0.0.1 at 2012-03-10 14:28:14 +0100
+          #   Completed 200 OK in 79ms (Views: 78.8ms | ActiveRecord: 0.0ms)
+          #
+          # Into this:
+          #
+          #   Get "/" sent 200 OK in 79ms
+          #
+          # The single event is still a {Timber::Events::HTTPServerResponse} event. Because
+          # we capture HTTP context, you still get the HTTP details, but you will not get
+          # all of the request details that the {Timber::Events::HTTPServerRequest} event would
+          # provide.
+          #
+          # @example
+          #   Timber::Integrations::Rack::HTTPEvents.collapse_into_single_event = true
+          def collapse_into_single_event=(value)
+            @collapse_into_single_event = value
+          end
+
+          # Accessor method for {#collapse_into_single_event=}.
+          def collapse_into_single_event?
+            @collapse_into_single_event == true
+          end
+
+          # This setting allows you to silence requests based on any conditions you desire.
+          # We require a block because it gives you complete control over how you want to
+          # silence requests. The first parameter being the traditional Rack env hash, the
+          # second being a [Rack Request](http://www.rubydoc.info/gems/rack/Rack/Request) object.
+          #
+          # @example
+          #   Integrations::Rack::HTTPEvents.silence_request = lambda do |rack_env, rack_request|
+          #     rack_request.path == "/_health"
+          #   end
+          def silence_request=(proc)
+            if proc && !proc.is_a?(Proc)
+              raise ArgumentError.new("The value passed to #silence_request must be a Proc")
+            end
+
+            @silence_request = proc
+          end
+
+          # Accessor method for {#silence_request=}
+          def silence_request
+            @silence_request
+          end
         end
 
         def call(env)
-          start = Time.now
           request = Util::Request.new(env)
 
-          Config.instance.logger.info do
-            Events::HTTPServerRequest.new(
-              headers: request.headers,
-              host: request.host,
-              method: request.request_method,
-              path: request.path,
-              port: request.port,
-              query_string: request.query_string,
-              request_id: request.request_id, # we insert this middleware after ActionDispatch::RequestId
-              scheme: request.scheme
-            )
+          if silenced?(env, request)
+            Config.instance.logger.silence do
+              @app.call(env)
+            end
+
+          elsif collapse_into_single_event?
+            start = Time.now
+
+            status, headers, body = @app.call(env)
+
+            Config.instance.logger.info do
+              http_context_key = Contexts::HTTP.keyspace
+              http_context = CurrentContext.fetch(http_context_key)
+              time_ms = (Time.now - start) * 1000.0
+
+              Events::HTTPServerResponse.new(
+                headers: headers,
+                http_context: http_context,
+                request_id: request.request_id,
+                status: status,
+                time_ms: time_ms
+              )
+            end
+
+            [status, headers, body]
+
+          else
+            start = Time.now
+
+            Config.instance.logger.info do
+              event_body = capture_request_body? ? request.body_content : nil
+
+              Events::HTTPServerRequest.new(
+                body: event_body,
+                headers: request.headers,
+                host: request.host,
+                method: request.request_method,
+                path: request.path,
+                port: request.port,
+                query_string: request.query_string,
+                request_id: request.request_id, # we insert this middleware after ActionDispatch::RequestId
+                scheme: request.scheme
+              )
+            end
+
+            status, headers, body = @app.call(env)
+
+            Config.instance.logger.info do
+              time_ms = (Time.now - start) * 1000.0
+              event_body = capture_response_body? ? body : nil
+
+              Events::HTTPServerResponse.new(
+                body: event_body,
+                headers: headers,
+                request_id: request.request_id,
+                status: status,
+                time_ms: time_ms
+              )
+            end
+
+            [status, headers, body]
           end
+        end
 
-          status, headers, body = @app.call(env)
+        private
+          def capture_request_body?
+            self.class.capture_request_body?
+          end
 
-          Config.instance.logger.info do
-            time_ms = (Time.now - start) * 1000.0
-            Events::HTTPServerResponse.new(
-              headers: headers,
-              request_id: request.request_id,
-              status: status,
-              time_ms: time_ms
-            )
+          def capture_response_body?
+            self.class.capture_response_body?
           end
 
-          [status, headers, body]
-        end
+          def collapse_into_single_event?
+            self.class.collapse_into_single_event?
+          end
+
+          def silenced?(env, request)
+            if !self.class.silence_request.nil?
+              self.class.silence_request.call(env, request)
+            else
+              false
+            end
+          end
       end
     end
   end

data/lib/timber/integrations/rack/middleware.rb

@@ -0,0 +1,28 @@
+module Timber
+  module Integrations
+    module Rack
+      # Base class that all Timber Rack middlewares extend. See the class level methods for
+      # configuration options.
+      class Middleware
+        class << self
+          # Easily enable / disable specific middlewares.
+          #
+          # @example
+          #   Timber::Integrations::Rack::UserContext.enabled = false
+          def enabled=(value)
+            @enabled = value
+          end
+
+          # Accessor method for {#enabled=}.
+          def enabled?
+            @enabled != false
+          end
+        end
+
+        def initialize(app)
+          @app = app
+        end
+      end
+    end
+  end
+end

data/lib/timber/integrations/rack/session_context.rb

@@ -1,12 +1,11 @@
+require "timber/integrations/rack/middleware"
+
 module Timber
   module Integrations
     module Rack
-      # Reponsible for adding the Session context for applications that use `Rack`.
-      class SessionContext
-        def initialize(app)
-          @app = app
-        end
-
+      # A Rack middleware that is responsible for adding the Session context
+      # {Timber::Contexts::Session}.
+      class SessionContext < Middleware
         def call(env)
           id = get_session_id(env)
           if id

data/lib/timber/integrations/rack/user_context.rb

@@ -1,72 +1,119 @@
+require "timber/integrations/rack/middleware"
+
 module Timber
   module Integrations
     module Rack
-      # Reponsible for adding the user context.
-      class UserContext
-        def initialize(app)
-          @app = app
+      # This is a Rack middleware responsible for setting the user context.
+      # See {Timber::Contexts::User} for more information on the user context.
+      #
+      # We use a Rack middleware because we want to set the user context as early as
+      # possible, and before the initial incoming request log line:
+      #
+      #   Started GET /welcome
+      #
+      # The above log line is logged in a request middleware, before it reaches
+      # the controller.
+      #
+      # If, for example, we set the user context in a controller, the log line above
+      # will not have the user context attached. This is because it is logged before
+      # the controller is executed. This is not ideal, and it's why we take a middleware
+      # approach here. If for some reason you cannot identify the user at the middleware
+      # level then setting it in the controller is perfectly fine, just be aware of the
+      # above downside.
+      #
+      # ## Authentication frameworks automatically detected:
+      #
+      # If you use any of the following authentication frameworks, Timber will
+      # automatically set the user context for you.
+      #
+      # * Devise, or any Warden based authentication strategy
+      # * Omniauth
+      # * Clearance
+      #
+      # Or, you can use your own custom authentication, see the {.custom_user_context}
+      # class method for more details.
+      #
+      # @note This middleware is automatically inserted for frameworks we support.
+      #   Such as Rails. See {Timber::Frameworks} for a comprehensive list.
+      class UserContext < Middleware
+        class << self
+          # The custom user context allows you to hook in and set your own custom
+          # user context. This is used in situations where either:
+          #
+          # 1. Timber does not automatically support your authentication strategy (see module level docs)
+          # 2. You need to customize your authentication beyond Timber's defaults.
+          #
+          # @example Setting your own custom user context
+          #   Timber::Integrations::Rack::UserContext.custom_user_hash = lambda do |rack_env|
+          #     rach_env['my_custom_key'].user
+          #   end
+          def custom_user_hash=(proc)
+            if proc && !proc.is_a?(Proc)
+              raise ArgumentError.new("The value passed to #custom_user_hash must be a Proc")
+            end
+
+            @custom_user_hash = proc
+          end
+
+          # Accessor method for {#custom_user_hash=}.
+          def custom_user_hash
+            @custom_user_hash
+          end
         end
 
         def call(env)
-          debug { "#{self.class.name} - Starting user context" }
           user_hash = get_user_hash(env)
           if user_hash
-            debug { "#{self.class.name} - User hash found: #{user_hash.inspect}" }
             context = Contexts::User.new(user_hash)
             CurrentContext.with(context) do
               @app.call(env)
             end
           else
-            debug { "#{self.class.name} - User hash not found" }
             @app.call(env)
           end
         end
 
         private
           def get_user_hash(env)
-            get_omniauth_user_hash(env) ||
-              get_warden_user_hash(env) ||
+            # The order is relevant here. The 'warden' key can be set, but
+            # not return a user, in which case the user data might be in the omniauth
+            # data.
+            if self.class.custom_user_hash.is_a?(Proc)
+              debug { "Obtaining user context from the custom user hash" }
+              self.class.custom_user_hash.call(env)
+            elsif (auth_hash = env['omniauth.auth'])
+              debug { "Obtaining user context from the omniauth auth hash" }
+              get_omniauth_user_hash(auth_hash)
+            elsif env[:clearance] && env[:clearance].signed_in?
+              debug { "Obtaining user context from the clearance user" }
+              user = env[:clearance].current_user
+              get_user_object_hash(user)
+            elsif env['warden'] && (user = env['warden'].user)
+              debug { "Obtaining user context from the warden user" }
+              get_user_object_hash(user)
+            else
+              debug { "Could not locate any user data" }
               nil
+            end
           end
 
-          def get_omniauth_user_hash(env)
-            if env['omniauth.auth']
-              debug { "#{self.class.name} - Omniauth hash present #{env['omniauth.auth'].inspect}" }
-              auth_hash = env['omniauth.auth']
-              info = auth_hash['info']
+          def get_omniauth_user_hash(auth_hash)
+            info = auth_hash['info']
 
-              {
-                id: auth_hash['uid'],
-                name: info['name'],
-                email: info['email']
-              }
-            else
-              debug { "#{self.class.name} - Omniauth hash not present" }
-              nil
-            end
+            {
+              id: auth_hash['uid'],
+              name: info['name'],
+              email: info['email']
+            }
           end
 
-          def get_warden_user_hash(env)
-            if env['warden']
-              debug { "#{self.class.name} - Warden object present #{env['warden'].inspect}" }
-              user = env['warden'].user
-              if user
-                debug { "#{self.class.name} - Warden user object #{env['warden'].user.inspect}" }
-                id = try_user_id(user)
-                name = try_user_name(user)
-                email = try_user_email(user)
+          def get_user_object_hash(user)
+            id = try_user_id(user)
+            name = try_user_name(user)
+            email = try_user_email(user)
 
-                if id || name || email
-                  debug { "#{self.class.name} - At least one warden user attribute was present" }
-                  {id: id, name: name, email: email}
-                else
-                  debug { "#{self.class.name} - No warden user attributes were present" }
-                  nil
-                end
-              else
-                debug { "#{self.class.name} - Warden user object not present, not logged in" }
-                nil
-              end
+            if id || name || email
+              {id: id, name: name, email: email}
             else
               nil
             end