timber 1.0.3

data/lib/timber/events/exception.rb

@@ -0,0 +1,35 @@
+module Timber
+  module Events
+    # The exception event is used to track exceptions.
+    #
+    # @note This event should be installed automatically through probes,
+    #   such as the {Probes::ActionDispatchDebugExceptions} probe.
+    class Exception < Timber::Event
+      attr_reader :name, :exception_message, :backtrace
+
+      def initialize(attributes)
+        @name = attributes[:name] || raise(ArgumentError.new(":name is required"))
+        @exception_message = attributes[:exception_message] || raise(ArgumentError.new(":exception_message is required"))
+        @backtrace = attributes[:backtrace]
+      end
+
+      def to_hash
+        {name: name, message: exception_message, backtrace: backtrace}
+      end
+      alias to_h to_hash
+
+      def as_json(_options = {})
+        {:exception => to_hash}
+      end
+
+      def message
+        message = "#{name} (#{exception_message}):"
+        if backtrace.is_a?(Array) && backtrace.length > 0
+          message << "\n\n"
+          message << backtrace.join("\n")
+        end
+        message
+      end
+    end
+  end
+end

data/lib/timber/events/http_request.rb

@@ -0,0 +1,50 @@
+module Timber
+  module Events
+    # The HTTP request event tracks incoming HTTP requests.
+    #
+    # @note This event should be installed automatically through probes,
+    #   such as the {Probes::ActionControllerLogSubscriber} probe.
+    class HTTPRequest < Timber::Event
+      attr_reader :host, :method, :path, :port, :query_params, :content_type,
+        :remote_addr, :referrer, :request_id, :user_agent
+
+      def initialize(attributes)
+        @host = attributes[:host] || raise(ArgumentError.new(":host is required"))
+        @method = attributes[:method] || raise(ArgumentError.new(":method is required"))
+        @path = attributes[:path] || raise(ArgumentError.new(":path is required"))
+        @port = attributes[:port]
+        @query_params = attributes[:query_params]
+        @content_type = attributes[:content_type]
+        @remote_addr = attributes[:remote_addr]
+        @referrer = attributes[:referrer]
+        @request_id = attributes[:request_id]
+        @user_agent = attributes[:user_agent]
+      end
+
+      def to_hash
+        {host: host, method: method, path: path, port: port, query_params: query_params,
+          headers: {content_type: content_type, remote_addr: remote_addr, referrer: referrer,
+            request_id: request_id, user_agent: user_agent}}
+      end
+      alias to_h to_hash
+
+      def as_json(_options = {})
+        hash = to_hash
+        hash[:headers] = Util::Hash.compact(hash[:headers])
+        hash = Util::Hash.compact(hash)
+        {:http_request => hash}
+      end
+
+      def message
+        'Started %s "%s" for %s' % [
+        method,
+        path,
+        remote_addr]
+      end
+
+      def status_description
+        Rack::Utils::HTTP_STATUS_CODES[status]
+      end
+    end
+  end
+end

data/lib/timber/events/http_response.rb

@@ -0,0 +1,36 @@
+module Timber
+  module Events
+    # The HTTP response event tracks outgoing HTTP request responses.
+    #
+    # @note This event should be installed automatically through probes,
+    #   such as the {Probes::ActionControllerLogSubscriber} probe.
+    class HTTPResponse < Timber::Event
+      attr_reader :status, :time_ms, :additions
+
+      def initialize(attributes)
+        @status = attributes[:status] || raise(ArgumentError.new(":status is required"))
+        @time_ms = attributes[:time_ms] || raise(ArgumentError.new(":time_ms is required"))
+        @additions = attributes[:additions]
+      end
+
+      def to_hash
+        {status: status, time_ms: time_ms}
+      end
+      alias to_h to_hash
+
+      def as_json(_options = {})
+        {:http_response => to_hash}
+      end
+
+      def message
+        message = "Completed #{status} #{status_description} in #{time_ms}ms"
+        message << " (#{additions.join(" | ".freeze)})" unless additions.empty?
+        message
+      end
+
+      def status_description
+        Rack::Utils::HTTP_STATUS_CODES[status]
+      end
+    end
+  end
+end

data/lib/timber/events/sql_query.rb

@@ -0,0 +1,26 @@
+module Timber
+  module Events
+    # The SQL query event tracks sql queries to your database.
+    #
+    # @note This event should be installed automatically through probes,
+    #   such as the {Probes::ActiveRecordLogSubscriber} probe.
+    class SQLQuery < Timber::Event
+      attr_reader :sql, :time_ms, :message
+
+      def initialize(attributes)
+        @sql = attributes[:sql] || raise(ArgumentError.new(":sql is required"))
+        @time_ms = attributes[:time_ms] || raise(ArgumentError.new(":time_ms is required"))
+        @message = attributes[:message] || raise(ArgumentError.new(":message is required"))
+      end
+
+      def to_hash
+        {sql: sql, time_ms: time_ms}
+      end
+      alias to_h to_hash
+
+      def as_json(_options = {})
+        {:sql_query => to_hash}
+      end
+    end
+  end
+end

data/lib/timber/events/template_render.rb

@@ -0,0 +1,26 @@
+module Timber
+  module Events
+    # The template render event track template renderings and their performance.
+    #
+    # @note This event should be installed automatically through probes,
+    #   such as the {Probes::ActionViewLogSubscriber} probe.
+    class TemplateRender < Timber::Event
+      attr_reader :message, :name, :time_ms
+
+      def initialize(attributes)
+        @message = attributes[:message] || raise(ArgumentError.new(":message is required"))
+        @name = attributes[:name] || raise(ArgumentError.new(":name is required"))
+        @time_ms = attributes[:time_ms] || raise(ArgumentError.new(":time_ms is required"))
+      end
+
+      def to_hash
+        {name: name, time_ms: time_ms}
+      end
+      alias to_h to_hash
+
+      def as_json(_options = {})
+        {:template_render => to_hash}
+      end
+    end
+  end
+end

data/lib/timber/events.rb

@@ -0,0 +1,37 @@
+require "timber/events/controller_call"
+require "timber/events/custom"
+require "timber/events/exception"
+require "timber/events/http_request"
+require "timber/events/http_response"
+require "timber/events/sql_query"
+require "timber/events/template_render"
+
+module Timber
+  module Events
+    # Protocol for casting objects into a `Timber::Event`.
+    #
+    # @example Casting a hash
+    #   Timber::Events.build({type: :custom_event, message: "My log message", data: {my: "data"}})
+    def self.build(obj)
+      if obj.is_a?(::Timber::Event)
+        obj
+      elsif obj.respond_to?(:to_timber_event)
+        obj.to_timber_event
+      elsif obj.is_a?(Hash) && obj.key?(:message) && obj.key?(:type) && obj.key?(:data)
+        Events::Custom.new(
+          type: obj[:type],
+          message: obj[:message],
+          data: obj[:data]
+        )
+      elsif obj.is_a?(Struct) && obj.respond_to?(:message) && obj.respond_to?(:type)
+        Events::Custom.new(
+          type: obj.type,
+          message: obj.message,
+          data: obj.respond_to?(:hash) ? obj.hash : obj.to_h # ruby 1.9.3 does not have to_h
+        )
+      else
+        nil
+      end
+    end
+  end
+end

data/lib/timber/frameworks/rails.rb

@@ -0,0 +1,13 @@
+module Timber
+  module Frameworks
+    module Rails
+      # Installs Timber into your Rails app automatically.
+      class Railtie < ::Rails::Railtie
+        config.timber = Config.instance
+        config.before_initialize do
+          Probes.insert!(config.app_middleware, ::Rails::Rack::Logger)
+        end
+      end
+    end
+  end
+end

data/lib/timber/frameworks.rb

@@ -0,0 +1,19 @@
+require "logger"
+
+# Attempt to require Rails. We can not list it as a gem
+# dependency because we want to support multiple frameworks.
+begin
+  require("rails")
+rescue LoadError
+end
+
+if defined?(::Rails) && defined?(::Rails::Railtie)
+  require 'timber/frameworks/rails'
+end
+
+module Timber
+  # Namespace for installing Timber into frameworks
+  # @private
+  module Frameworks
+  end
+end

data/lib/timber/log_devices/http.rb

@@ -0,0 +1,87 @@
+require "monitor"
+require "msgpack"
+
+module Timber
+  module LogDevices
+    # A log device that buffers and sends logs to the Timber API over HTTP in intervals. The buffer
+    # uses MessagePack::Buffer, which is fast, efficient with memory, and reduces
+    # the payload size sent to Timber.
+    class HTTP
+      class DeliveryError < StandardError; end
+
+      API_URI = URI.parse("https://api.timber.io/http_frames")
+      CONTENT_TYPE = "application/json".freeze
+      CONNECTION_HEADER = "keep-alive".freeze
+      USER_AGENT = "Timber Ruby Gem/#{Timber::VERSION}".freeze
+
+      HTTPS = Net::HTTP.new(API_URI.host, API_URI.port).tap do |https|
+        https.use_ssl = true
+        https.read_timeout = 30
+        https.ssl_timeout = 10
+        if https.respond_to?(:keep_alive_timeout=)
+          https.keep_alive_timeout = 60
+        end
+        https.open_timeout = 10
+      end
+
+      DEFAULT_DELIVERY_FREQUENCY = 2.freeze
+
+      # Instantiates a new HTTP log device.
+      #
+      # @param api_key [String] The API key provided to you after you add your application to
+      #   [Timber](https://timber.io).
+      # @param [Hash] options the options to create a HTTP log device with.
+      # @option attributes [Symbol] :frequency_seconds (2) How often the client should
+      #   attempt to deliver logs to the Timber API. The HTTP client buffers logs between calls.
+      def initialize(api_key, options = {})
+        @api_key = api_key
+        @buffer = []
+        @monitor = Monitor.new
+        @delivery_thread = Thread.new do
+          at_exit { deliver }
+          loop do
+            sleep options[:frequency_seconds] || DEFAULT_DELIVERY_FREQUENCY
+            deliver
+          end
+        end
+      end
+
+      def write(msg)
+        @monitor.synchronize {
+          @buffer << msg
+        }
+      end
+
+      def close
+        @delivery_thread.kill
+      end
+
+      private
+        def deliver
+          body = @buffer.read
+
+          request = Net::HTTP::Post.new(API_URI.request_uri).tap do |req|
+            req['Authorization'] = authorization_payload
+            req['Connection'] = CONNECTION_HEADER
+            req['Content-Type'] = CONTENT_TYPE
+            req['User-Agent'] = USER_AGENT
+            req.body = body
+          end
+
+          HTTPS.request(request).tap do |res|
+            code = res.code.to_i
+            if code < 200 || code >= 300
+              raise DeliveryError.new("Bad response from Timber API - #{res.code}: #{res.body}")
+            end
+            Config.instance.logger.debug("Success! #{code}: #{res.body}")
+          end
+
+          @buffer.clear
+        end
+
+        def authorization_payload
+          @authorization_payload ||= "Basic #{Base64.strict_encode64(@api_key).chomp}"
+        end
+    end
+  end
+end

data/lib/timber/log_devices.rb

@@ -0,0 +1,8 @@
+require "timber/log_devices/http"
+
+module Timber
+  # Namespace for all log devices.
+  # @private
+  module LogDevices
+  end
+end

data/lib/timber/log_entry.rb

@@ -0,0 +1,59 @@
+module Timber
+  # Represents a new log entry into the log. This is an intermediary class between
+  # `Logger` and the log device that you set it up with.
+  class LogEntry #:nodoc:
+    DT_PRECISION = 6.freeze
+
+    attr_reader :level, :time, :progname, :message, :context, :event
+
+    # Creates a log entry suitable to be sent to the Timber API.
+    # @param severity [Integer] the log level / severity
+    # @param time [Time] the exact time the log message was written
+    # @param progname [String] the progname scope for the log message
+    # @param message [#to_json] structured data representing the log line event, this can
+    #   be anything that responds to #to_json
+    # @return [LogEntry] the resulting LogEntry object
+    def initialize(level, time, progname, message, context, event)
+      @level = level
+      @time = time.utc
+      @progname = progname
+      @message = message
+      @context = context
+      @event = event
+    end
+
+    def as_json(options = {})
+      options ||= {}
+      hash = {level: level, dt: formatted_dt, message: message}
+
+      if !event.nil?
+        hash[:event] = event
+      end
+
+      if !context.nil? && context.length > 0
+        hash[:context] = context
+      end
+
+      if options[:only]
+        hash.select do |key, _value|
+          options[:only].include?(key)
+        end
+      elsif options[:except]
+        hash.select do |key, _value|
+          !options[:except].include?(key)
+        end
+      else
+        hash
+      end
+    end
+
+    def to_json(options = {})
+      as_json(options).to_json
+    end
+
+    private
+      def formatted_dt
+        @formatted_dt ||= time.iso8601(DT_PRECISION)
+      end
+  end
+end

data/lib/timber/logger.rb

@@ -0,0 +1,142 @@
+require "logger"
+
+module Timber
+  # 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
+    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
+        log_entry.message.gsub("\n", "\\n") << " " << 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

@@ -0,0 +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.instance.logger.debug("Inserted probe #{name}")
+        true
+      # RequirementUnsatisfiedError is the only silent failure we support
+      rescue RequirementNotMetError => e
+        Config.instance.logger.debug("Failed inserting probe #{name}: #{e.message}")
+        false
+      end
+    end
+
+    def insert!
+      raise NotImplementedError.new
+    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