timberio 1.0.0.beta1 → 1.0.0

data/lib/timber/logger.rb

@@ -1,20 +1,143 @@
 require "logger"
 
 module Timber
-  # A simple interface to instantiate a logger. It does a couple of things:
-  # 1. Simplifies Rails logger instantiation across Rails versions. This
-  #    helps with simplifying the Readme / install instructions.
-  # 2. Serves as a placeholder should we want to extend the logger and add
-  #    Timber specific functionality.
-  module Logger
-    def self.new(logger_or_logdev = nil)
-      logger = if logger_or_logdev.is_a?(::Logger)
-        logger_or_logdev
-      else
-        Frameworks.logger(logger_or_logdev)
+  # The Timber Logger behaves exactly like `::Logger`, except that it supports a transparent API
+  # for logging structured messages. It ensures your log messages are communicated properly
+  # with the Timber.io API.
+  #
+  # To adhere to our no code debt / no lock-in promise, the Timber Logger will *never* deviate
+  # from the `::Logger` interface. That is, it will *never* add methods, or alter any
+  # method signatures. This ensures Timber can be removed without consequence.
+  #
+  # @example Basic example (the original ::Logger interface remains untouched):
+  #   logger.info "Payment rejected for customer #{customer_id}"
+  #
+  # @example Using a map
+  #   # The :message, :type, and :data keys are required
+  #   logger.info message: "Payment rejected", type: :payment_rejected, data: {customer_id: customer_id, amount: 100}
+  #
+  # @example Using a Struct (a simple, more structured way, to define events)
+  #   PaymentRejectedEvent = Struct.new(:customer_id, :amount, :reason) do
+  #     def message; "Payment rejected for #{customer_id}"; end
+  #     def type; :payment_rejected; end
+  #   end
+  #   Logger.info PaymentRejectedEvent.new("abcd1234", 100, "Card expired")
+  #
+  # @example Using typed Event classes
+  #   # Event implementation is left to you. Events should be simple classes.
+  #   # The only requirement is that it responds to #to_timber_event and return the
+  #   # appropriate Timber::Events::* type.
+  #   class Event
+  #     def to_hash
+  #       hash = {}
+  #       instance_variables.each { |var| hash[var.to_s.delete("@")] = instance_variable_get(var) }
+  #       hash
+  #     end
+  #     alias to_h to_hash
+  #
+  #     def to_timber_event
+  #       Timber::Events::Custom.new(type: type, message: message, data: to_hash)
+  #     end
+  #
+  #     def message; raise NotImplementedError.new; end
+  #     def type; raise NotImplementedError.new; end
+  #   end
+  #
+  #   class PaymentRejectedEvent < Event
+  #     attr_accessor :customer_id, :amount
+  #     def initialize(customer_id, amount)
+  #       @customer_id = customer_id
+  #       @amount = amount
+  #     end
+  #     def message; "Payment rejected for customer #{customer_id}"; end
+  #     def type; :payment_rejected_event; end
+  #   end
+  #
+  #   Logger.info PymentRejectedEvent.new("abcd1234", 100)
+  #
+  class Logger < ::Logger
+    # @private
+    class Formatter
+      # Formatters get the formatted level from the logger.
+      SEVERITY_MAP = {
+        "DEBUG" => :debug,
+        "INFO" => :info,
+        "WARN" => :warn,
+        "ERROR" => :error,
+        "FATAL" => :datal,
+        "UNKNOWN" => :unknown
+      }
+
+      private
+        def build_log_entry(severity, time, progname, msg)
+          level = SEVERITY_MAP.fetch(severity)
+          context = CurrentContext.instance.snapshot
+          event = Events.build(msg)
+          if event
+            LogEntry.new(level, time, progname, event.message, context, event)
+          else
+            LogEntry.new(level, time, progname, msg, context, nil)
+          end
+        end
+    end
+
+    # Structures your log messages into JSON.
+    #
+    #   logger = Timber::Logger.new(STDOUT)
+    #   logger.formatter = Timber::JSONFormatter.new
+    #
+    # Example message:
+    #
+    #   {"level":"info","dt":"2016-09-01T07:00:00.000000-05:00","message":"My log message"}
+    #
+    class JSONFormatter < Formatter
+      def call(severity, time, progname, msg)
+        # use << for concatenation for performance reasons
+        build_log_entry(severity, time, progname, msg).to_json() << "\n"
       end
-      logger.extend(self)
-      logger
+    end
+
+    # Structures your log messages into Timber's hybrid format, which makes
+    # it easy to read while also appending the appropriate metadata.
+    #
+    #   logger = Timber::Logger.new(STDOUT)
+    #   logger.formatter = Timber::JSONFormatter.new
+    #
+    # Example message:
+    #
+    #   My log message @timber.io {"level":"info","dt":"2016-09-01T07:00:00.000000-05:00"}
+    #
+    class HybridFormatter < Formatter
+      METADATA_CALLOUT = "@timber.io".freeze
+
+      def call(severity, time, progname, msg)
+        log_entry = build_log_entry(severity, time, progname, msg)
+        metadata = log_entry.to_json(:except => [:message])
+        # use << for concatenation for performance reasons
+        puts msg
+        log_entry.message << " " << METADATA_CALLOUT << " " << metadata << "\n"
+      end
+    end
+
+    # Creates a new Timber::Logger instances. Accepts the same arguments as `::Logger.new`.
+    # The only difference is that it default the formatter to {HybridFormatter}. Using
+    # a different formatter is easy. For example, if you prefer your logs in JSON.
+    #
+    # @example Changing your formatter
+    #   logger = Timber::Logger.new(STDOUT)
+    #   logger.formatter = Timber::Logger::JSONFormatter.new
+    def initialize(*args)
+      super(*args)
+      self.formatter = HybridFormatter.new
+    end
+
+    # Backwards compatibility with older ActiveSupport::Logger versions
+    Logger::Severity.constants.each do |severity|
+      class_eval(<<-EOT, __FILE__, __LINE__ + 1)
+        def #{severity.downcase}?                # def debug?
+          Logger::#{severity} >= level           #   DEBUG >= level
+        end                                      # end
+      EOT
     end
   end
 end

data/lib/timber/probe.rb

@@ -1,21 +1,23 @@
 module Timber
+  # Base class for `Timber::Probes::*`.
+  # @private
   class Probe
     class RequirementNotMetError < StandardError; end
 
     class << self
       def insert!(*args)
         new(*args).insert!
-        Config.logger.debug("Inserted probe #{name}")
+        Config.instance.logger.debug("Inserted probe #{name}")
         true
       # RequirementUnsatisfiedError is the only silent failure we support
       rescue RequirementNotMetError => e
-        Config.logger.debug("Failed inserting probe #{name}: #{e.message}")
+        Config.instance.logger.debug("Failed inserting probe #{name}: #{e.message}")
         false
       end
     end
 
     def insert!
-      raise NotImplementedError.new("You must implement #insert")
+      raise NotImplementedError.new
     end
   end
-end
+end

data/lib/timber/probes/action_controller_log_subscriber/log_subscriber.rb

@@ -0,0 +1,64 @@
+module Timber
+  module Probes
+    class ActionControllerLogSubscriber < Probe
+      # The log subscriber that replaces the default `ActionController::LogSubscriber`.
+      # The intent of this subscriber is to, as transparently as possible, properly
+      # track events that are being logged here. This LogSubscriber will never change
+      # default behavior / log messages.
+      class LogSubscriber < ::ActionController::LogSubscriber
+        def start_processing(event)
+          info do
+            payload = event.payload
+            params  = payload[:params].except(*INTERNAL_PARAMS)
+            format  = extract_format(payload)
+            format  = format.to_s.upcase if format.is_a?(Symbol)
+
+            Events::ControllerCall.new(
+              controller: payload[:controller],
+              action: payload[:action],
+              format: format,
+              params: params
+            )
+          end
+        end
+
+        def process_action(event)
+          info do
+            payload   = event.payload
+            additions = ActionController::Base.log_process_action(payload)
+
+            status = payload[:status]
+            if status.nil? && payload[:exception].present?
+              exception_class_name = payload[:exception].first
+              status = extract_status(exception_class_name)
+            end
+
+            Events::HTTPResponse.new(
+              status: status,
+              time_ms: event.duration,
+              additions: additions
+            )
+          end
+        end
+
+        private
+          def extract_format(payload)
+            if payload.key?(:format)
+              payload[:format] # rails > 4.X
+            elsif payload.key?(:formats)
+              payload[:formats].first # rails 3.X
+            end
+          end
+
+          def extract_status(exception_class_name)
+            if defined?(ActionDispatch::ExceptionWrapper)
+              ActionDispatch::ExceptionWrapper.status_code_for_exception(exception_class_name)
+            else
+              # Rails 3.X
+              Rack::Utils.status_code(ActionDispatch::ShowExceptions.rescue_responses[exception_class_name]) rescue nil
+            end
+          end
+      end
+    end
+  end
+end

data/lib/timber/probes/action_controller_log_subscriber.rb

@@ -0,0 +1,20 @@
+module Timber
+  module Probes
+    # Responsible for automatically tracking controller call and http response events
+    # for applications that use `ActionController`.
+    class ActionControllerLogSubscriber < Probe
+      def initialize
+        require "action_controller/log_subscriber"
+        require "timber/probes/action_controller_log_subscriber/log_subscriber"
+      rescue LoadError => e
+        raise RequirementNotMetError.new(e.message)
+      end
+
+      def insert!
+        return true if Util::ActiveSupportLogSubscriber.subscribed?(:action_controller, LogSubscriber)
+        Util::ActiveSupportLogSubscriber.unsubscribe(:action_controller, ::ActionController::LogSubscriber)
+        LogSubscriber.attach_to(:action_controller)
+      end
+    end
+  end
+end

data/lib/timber/probes/action_dispatch_debug_exceptions.rb

@@ -1,57 +1,81 @@
 module Timber
   module Probes
+    # Reponsible for automatically tracking exception events in Rails applications. While
+    # still preserving the default log style.
     class ActionDispatchDebugExceptions < Probe
-      module InstanceMethods
+      # For Rails >= 3.1
+      # @private
+      module DebugExceptionsInstanceMethods
         def self.included(klass)
           klass.class_eval do
             private
-              # We have to monkey patch because ruby < 2.0 does not support prepend.
-              alias_method :_timber_old_log_error, :log_error
+              def log_error(request, wrapper)
+                logger = logger(request)
+                puts logger.inspect
+                return unless logger
+
+                exception = wrapper.exception
 
-              def log_error(*args)
-                # Rails 3.0 has 1 arg, >= 3.1 uses 2 args, the last being an exception wrapper
-                exception = args.size == 1 ? args.first : args.last.exception
-                # AR only logs queries if debugging, no need to do anything otherwise
-                context = Contexts::Exception.new(exception)
-                CurrentContext.add(context) do
-                  _timber_old_log_error(*args)
-                end
+                trace = wrapper.application_trace
+                trace = wrapper.framework_trace if trace.empty?
+
+                event = Events::Exception.new(
+                  name: exception.class.name,
+                  exception_message: exception.message,
+                  backtrace: trace
+                )
+
+                logger.fatal event
               end
           end
         end
       end
 
-      attr_reader :target_class
+      # For Rails < 3.1
+      # @private
+      module ShowExceptionsInstanceMethods #:nodoc:
+        def self.included(klass)
+          klass.class_eval do
+            private
+              # We have to monkey patch because ruby < 2.0 does not support prepend.
+              alias_method :_timber_old_log_error, :log_error
 
-      def initialize
-        load_debug_exceptions
-      rescue RequirementNotMetError
-        load_show_exceptions
-      end
+              def log_error(exception)
+                return unless logger
 
-      def insert!
-        return true if target_class.include?(InstanceMethods)
-        target_class.send(:include, InstanceMethods)
+                event = Events::Exception.new(
+                  name: exception.class.name,
+                  exception_message: exception.message,
+                  backtrace: application_trace(exception)
+                )
+
+                logger.fatal event
+              end
+          end
+        end
       end
 
-      private
-        # Rails >= 3.1 logs the error here
-        def load_debug_exceptions
+      def initialize
+        begin
+          # Rails >= 3.1
           require "action_dispatch/middleware/debug_exceptions"
-          @target_class = ::ActionDispatch::DebugExceptions
-          true
-        rescue LoadError => e
-          raise RequirementNotMetError.new(e.message)
+        rescue LoadError
+          # Rails < 3.1
+          require "action_dispatch/middleware/show_exceptions"
         end
+      rescue LoadError => e
+        raise RequirementNotMetError.new(e.message)
+      end
 
-        # Rails 3.0 logs the error here
-        def load_show_exceptions
-          require "action_dispatch/middleware/show_exceptions"
-          @target_class = ::ActionDispatch::ShowExceptions
-          true
-        rescue LoadError => e
-          raise RequirementNotMetError.new(e.message)
+      def insert!
+        if defined?(::ActionDispatch::DebugExceptions)
+          return true if ::ActionDispatch::DebugExceptions.include?(DebugExceptionsInstanceMethods)
+          ::ActionDispatch::DebugExceptions.send(:include, DebugExceptionsInstanceMethods)
+        else
+          return true if ::ActionDispatch::ShowExceptions.include?(ShowExceptionsInstanceMethods)
+          ::ActionDispatch::ShowExceptions.send(:include, ShowExceptionsInstanceMethods)
         end
+      end
     end
   end
-end
+end

data/lib/timber/probes/action_view_log_subscriber/log_subscriber.rb

@@ -0,0 +1,62 @@
+module Timber
+  module Probes
+    class ActionViewLogSubscriber < Probe
+      # The log subscriber that replaces the default `ActionView::LogSubscriber`.
+      # The intent of this subscriber is to, as transparently as possible, properly
+      # track events that are being logged here. This LogSubscriber will never change
+      # default behavior / log messages.
+      class LogSubscriber < ::ActionView::LogSubscriber
+        def render_template(event)
+          info do
+            full_name = from_rails_root(event.payload[:identifier])
+            message = "  Rendered #{full_name}"
+            message << " within #{from_rails_root(event.payload[:layout])}" if event.payload[:layout]
+            message << " (#{event.duration.round(1)}ms)"
+
+            Events::TemplateRender.new(
+              name: full_name,
+              time_ms: event.duration,
+              message: message
+            )
+          end
+        end
+
+        def render_partial(event)
+          info do
+            full_name = from_rails_root(event.payload[:identifier])
+            message = "  Rendered #{full_name}"
+            message << " within #{from_rails_root(event.payload[:layout])}" if event.payload[:layout]
+            message << " (#{event.duration.round(1)}ms)"
+            message << " #{cache_message(event.payload)}" if event.payload.key?(:cache_hit)
+
+            Events::TemplateRender.new(
+              name: full_name,
+              time_ms: event.duration,
+              message: message
+            )
+          end
+        end
+
+        def render_collection(event)
+          info do
+            identifier = event.payload[:identifier] || "templates"
+            full_name = from_rails_root(identifier)
+            message = "  Rendered collection of #{full_name}" \
+              " #{render_count(event.payload)} (#{event.duration.round(1)}ms)"
+
+            Events::TemplateRender.new(
+              name: full_name,
+              time_ms: event.duration,
+              message: message
+            )
+          end
+        end
+
+        private
+          def log_rendering_start(payload)
+            # Rails, you silly. We don't need to template rendering messages :)
+          end
+      end
+    end
+  end
+end

data/lib/timber/probes/action_view_log_subscriber.rb

@@ -0,0 +1,20 @@
+module Timber
+  module Probes
+    # Reponsible for automatically tracking template rendering events in `ActionView` while
+    # still preserving the default log style.
+    class ActionViewLogSubscriber < Probe
+      def initialize
+        require "action_view/log_subscriber"
+        require "timber/probes/action_view_log_subscriber/log_subscriber"
+      rescue LoadError => e
+        raise RequirementNotMetError.new(e.message)
+      end
+
+      def insert!
+        return true if Util::ActiveSupportLogSubscriber.subscribed?(:action_view, LogSubscriber)
+        Util::ActiveSupportLogSubscriber.unsubscribe(:action_view, ::ActionView::LogSubscriber)
+        LogSubscriber.attach_to(:action_view)
+      end
+    end
+  end
+end

data/lib/timber/probes/active_record_log_subscriber/log_subscriber.rb

@@ -0,0 +1,72 @@
+module Timber
+  module Probes
+    class ActiveRecordLogSubscriber < Probe
+      # The log subscriber that replaces the default `ActiveRecord::LogSubscriber`.
+      # The intent of this subscriber is to, as transparently as possible, properly
+      # track events that are being logged here. This LogSubscriber will never change
+      # default behavior / log messages.
+      class LogSubscriber < ::ActiveRecord::LogSubscriber #:nodoc:
+        def sql(event)
+          return unless logger.debug?
+
+          self.class.runtime += event.duration
+
+          payload = event.payload
+
+          return if defined?(IGNORE_PAYLOAD_NAMES) && IGNORE_PAYLOAD_NAMES.include?(payload[:name])
+
+          name  = "#{payload[:name]} (#{event.duration.round(1)}ms)"
+          sql   = payload[:sql]
+          binds = nil
+
+          unless (payload[:binds] || []).empty?
+            binds = "  " + payload[:binds].map { |attr| render_bind(attr) }.inspect
+          end
+
+          name = colorize_payload_name(name, payload[:name])
+          sql  = color(sql, sql_color(sql), true)
+
+          message = "  #{name}  #{sql}#{binds}"
+
+          event = Events::SQLQuery.new(
+            sql: payload[:sql],
+            time_ms: event.duration,
+            message: message
+          )
+
+          debug event
+        end
+
+        private
+          def colorize_payload_name(name, payload_name)
+            if payload_name.blank? || payload_name == "SQL" # SQL vs Model Load/Exists
+              color(name, MAGENTA, true)
+            else
+              color(name, CYAN, true)
+            end
+          end
+
+          def sql_color(sql)
+            case sql
+            when /\A\s*rollback/mi
+              RED
+            when /select .*for update/mi, /\A\s*lock/mi
+              WHITE
+            when /\A\s*select/i
+              BLUE
+            when /\A\s*insert/i
+              GREEN
+            when /\A\s*update/i
+              YELLOW
+            when /\A\s*delete/i
+              RED
+            when /transaction\s*\Z/i
+              CYAN
+              else
+              MAGENTA
+            end
+          end
+      end
+    end
+  end
+end

data/lib/timber/probes/active_record_log_subscriber.rb

@@ -0,0 +1,20 @@
+module Timber
+  module Probes
+    # Reponsible for automatimcally tracking SQL query events in `ActiveRecord`, while still
+    # preserving the default log style.
+    class ActiveRecordLogSubscriber < Probe
+      def initialize
+        require "active_record/log_subscriber"
+        require "timber/probes/active_record_log_subscriber/log_subscriber"
+      rescue LoadError => e
+        raise RequirementNotMetError.new(e.message)
+      end
+
+      def insert!
+        return true if Util::ActiveSupportLogSubscriber.subscribed?(:active_record, LogSubscriber)
+        Util::ActiveSupportLogSubscriber.unsubscribe(:active_record, ::ActiveRecord::LogSubscriber)
+        LogSubscriber.attach_to(:active_record)
+      end
+    end
+  end
+end

data/lib/timber/probes/rack_http_context.rb

@@ -0,0 +1,51 @@
+module Timber
+  module Probes
+    # Reponsible for automatically adding the HTTP context for applications that use `Rack`.
+    class RackHTTPContext < Probe
+      class Middleware
+        def initialize(app)
+          @app = app
+        end
+
+        def call(env)
+          request = ::Rack::Request.new(env)
+          context = Contexts::HTTP.new(
+            method: request.request_method,
+            path: request.path,
+            remote_addr: request.ip,
+            request_id: request_id(env)
+          )
+          CurrentContext.instance.with(context) do
+            @app.call(env)
+          end
+        end
+
+        private
+          def request_id(env)
+            env["X-Request-ID"] ||
+              env["X-Request-Id"] ||
+              env["action_dispatch.request_id"]
+          end
+      end
+
+      attr_reader :middleware, :insert_before
+
+      def initialize(middleware, insert_before)
+        if middleware.nil?
+          raise RequirementNotMetError.new("The middleware class attribute is not set. " +
+            "We need a middleware to insert the probe.")
+        end
+        @middleware = middleware
+        @insert_before = insert_before
+      end
+
+      def insert!
+        var_name = :"@_timber_rack_http_inserted"
+        return true if middleware.instance_variable_defined?(var_name) && middleware.instance_variable_get(var_name) == true
+        # Rails uses a proxy :/, so we need to do this instance variable hack
+        middleware.instance_variable_set(var_name, true)
+        middleware.insert_before insert_before, Middleware
+      end
+    end
+  end
+end