timber 2.0.24 → 2.1.0.rc1

data/lib/timber/config/integrations.rb

@@ -0,0 +1,63 @@
+require "timber/config/integrations/rack"
+require "timber/integrations/action_controller"
+require "timber/integrations/action_view"
+require "timber/integrations/active_record"
+require "timber/integrations/rack"
+
+module Timber
+  class Config
+    # Convenience module for accessing the various `Timber::Integrations::*` classes
+    # through the {Timber::Config} object. Timber couples configuration with the class
+    # responsibls for implementing it. This provides for a tighter design, but also
+    # requires the user to understand and access the various classes. This module aims
+    # to provide a simple ruby-like configuration interface for internal Timber classes.
+    #
+    # For example:
+    #
+    #     config = Timber::Config.instance
+    #     config.integrations.active_record.silence = true
+    module Integrations
+      extend self
+
+      # Convenience method for accessing the {Timber::Integrations::ActionController} class
+      # specific configuration.
+      #
+      # @example
+      #   config = Timber::Config.instance
+      #   config.integrations.action_controller.silence = true
+      def action_controller
+        Timber::Integrations::ActionController
+      end
+
+      # Convenience method for accessing the {Timber::IIntegrations::ActionView} class
+      # specific configuration.
+      #
+      # @example
+      #   config = Timber::Config.instance
+      #   config.integrations.action_view.silence = true
+      def action_view
+        Timber::Integrations::ActionView
+      end
+
+      # Convenience method for accessing the {Timber::IIntegrations::ActiveRecord} class
+      # specific configuration.
+      #
+      # @example
+      #   config = Timber::Config.instance
+      #   config.integrations.active_record.silence = true
+      def active_record
+        Timber::Integrations::ActiveRecord
+      end
+
+      # Convenience method for accessing the various `Timber::IIntegrations::Rack::*`
+      # classes. See {Rack} for a list of methods available.
+      #
+      # @example
+      #   config = Timber::Config.instance
+      #   config.integrations.rack.http_events.enabled = true
+      def rack
+        Rack
+      end
+    end
+  end
+end

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

@@ -0,0 +1,74 @@
+module Timber
+  class Config
+    module Integrations
+      # Convenience module for accessing the various `Timber::Integrations::Rack::*` classes
+      # through the {Timber::Config} object. Timber couples configuration with the class
+      # responsibls for implementing it. This provides for a tighter design, but also
+      # requires the user to understand and access the various classes. This module aims
+      # to provide a simple ruby-like configuration interface for internal Timber classes.
+      #
+      # For example:
+      #
+      #     config = Timber::Config.instance
+      #     config.integrations.rack.http_events.enabled = false
+      module Rack
+        extend self
+
+        # Convenience method for accessing the {Timber::Integrations::Rack::ExceptionEvent}
+        # middleware class specific configuration. See {Timber::Integrations::Rack::ExceptionEvent}
+        # for a list of methods available.
+        #
+        # @example
+        #   config = Timber::Config.instance
+        #   config.integrations.rack.exception_event.enabled = false
+        def exception_event
+          Timber::Integrations::Rack::ExceptionEvent
+        end
+
+        # Convenience method for accessing the {Timber::Integrations::Rack::HTTPContext}
+        # middleware class specific configuration. See {Timber::Integrations::Rack::HTTPContext}
+        # for a list of methods available.
+        #
+        # @example
+        #   config = Timber::Config.instance
+        #   config.integrations.rack.http_context.enabled = false
+        def http_context
+          Timber::Integrations::Rack::HTTPContext
+        end
+
+        # Convenience method for accessing the {Timber::Integrations::Rack::HTTPEvents}
+        # middleware class specific configuration. See {Timber::Integrations::Rack::HTTPEvents}
+        # for a list of methods available.
+        #
+        # @example
+        #   config = Timber::Config.instance
+        #   config.integrations.rack.http_events.enabled = false
+        def http_events
+          Timber::Integrations::Rack::HTTPEvents
+        end
+
+        # Convenience method for accessing the {Timber::Integrations::Rack::SessionContext}
+        # middleware class specific configuration. See {Timber::Integrations::Rack::SessionContext}
+        # for a list of methods available.
+        #
+        # @example
+        #   config = Timber::Config.instance
+        #   config.integrations.rack.session_context.enabled = false
+        def session_context
+          Timber::Integrations::Rack::SessionContext
+        end
+
+        # Convenience method for accessing the {Timber::Integrations::Rack::UserContext}
+        # middleware class specific configuration. See {Timber::Integrations::Rack::UserContext}
+        # for a list of methods available.
+        #
+        # @example
+        #   config = Timber::Config.instance
+        #   config.integrations.rack.user_context.enabled = false
+        def user_context
+          Timber::Integrations::Rack::UserContext
+        end
+      end
+    end
+  end
+end

data/lib/timber/context.rb

@@ -3,25 +3,28 @@ module Timber
   # @private
   class Context
     class << self
+      # The keyspace is the key used when storing the context.
+      # For example:
+      #
+      #     {:build => {:version => "1.0.0"}}
+      #
+      # The keyspace in the above context is `:build`. This is required
+      # because it prevents key name conflicts. Without the keyspace
+      # it very possible another context type might also have a `:version`
+      # attribute.
       def keyspace
         @keyspace || raise(NotImplementedError.new)
       end
     end
 
-    def keyspace
-      self.class.keyspace
-    end
-
+    # Returns a simple structure sufficient for encoding. We use
+    # `as_json` as the name since this is a ruby pattern.
     def as_json(options = {})
       raise NotImplementedError.new
     end
 
-    def to_json(options = {})
-      as_json.to_json(options)
-    end
-
-    def to_msgpack(*args)
-      as_json.to_msgpack(*args)
+    def keyspace
+      self.class.keyspace
     end
   end
 end

data/lib/timber/contexts.rb

@@ -1,6 +1,7 @@
 require "timber/contexts/custom"
 require "timber/contexts/http"
 require "timber/contexts/organization"
+require "timber/contexts/release"
 require "timber/contexts/runtime"
 require "timber/contexts/session"
 require "timber/contexts/system"

data/lib/timber/contexts/custom.rb

@@ -1,10 +1,22 @@
+require "timber/context"
+require "timber/util"
+
 module Timber
   module Contexts
     # Custom contexts allow you to add application specific context not covered elsewhere.
+    # Any data added this way will be included in your logs. A good example is worker job
+    # IDs. When processing a job you might add the job ID to the context, allowing you to
+    # view *all* logs generated while processing that job, not just the logs that contain
+    # the ID.
+    #
+    # Note in the example below all custom contexts must contain a root key. This is to
+    # ensure attribute names and types never clash across your contexts. It gives you
+    # much cleaner pallete to organize your data on.
     #
-    # @example Adding a context
+    # @example Adding a custom context
     #   logger.with_context(build: {version: "1.0.0"}) do
-    #     # ... anything logged here will have the context ...
+    #     # anything logged here will have the custom context above
+    #     # when this block exits the context will no longer be included
     #   end
     class Custom < Context
       @keyspace = :custom
@@ -16,7 +28,8 @@ module Timber
         @data = attributes[:data] || raise(ArgumentError.new(":data is required"))
       end
 
-      def as_json(_options = {})
+      # Builds a hash representation of containing simply objects, suitable for serialization.
+      def as_json(options = {})
         {Timber::Util::Object.try(type, :to_sym) => data}
       end
     end

data/lib/timber/contexts/http.rb

@@ -1,8 +1,14 @@
+require "timber/context"
+
 module Timber
   module Contexts
-    # The HTTP content tracks the current HTTP request being processed. This serves
-    # as join data across your logs, allowing you to query all logs for any attribute
-    # presented here. For example, viewing all logs for a given request_id.
+    # The HTTP context adds data about the current HTTP request being processed to your logs.
+    # This allows your to tail and filter by this data. A very useful piece of data this
+    # captures is the request ID. This gives you the ability to trace requests and view logs
+    # for a specific request only. For example, say you've searched your logs and found the
+    # specific line you are looking for, but it lacks context. With Timber you can simply
+    # click the request ID and "zoom out" to view all logs for that request. This gives you
+    # complete picture of how the log line in questio was generated.
     #
     # @note This context should be installed automatically through integrations,
     #   such as the {Intregrations::Rack::HTTPContext} rack middleware.
@@ -18,6 +24,7 @@ module Timber
         @request_id = attributes[:request_id]
       end
 
+      # Builds a hash representation of containing simply objects, suitable for serialization.
       def as_json(_options = {})
         {:method => method, :path => path, :remote_addr => remote_addr, :request_id => request_id}
       end

data/lib/timber/contexts/organization.rb

@@ -1,3 +1,6 @@
+require "timber/context"
+require "timber/util"
+
 module Timber
   module Contexts
     # The organization context tracks the organization of the currently
@@ -25,6 +28,7 @@ module Timber
         @name = attributes[:name]
       end
 
+      # Builds a hash representation of containing simply objects, suitable for serialization.
       def as_json(_options = {})
         {id: Timber::Util::Object.try(id, :to_s), name: name}
       end

data/lib/timber/contexts/release.rb

@@ -0,0 +1,46 @@
+require "timber/context"
+require "timber/util"
+
+module Timber
+  module Contexts
+    # The release context tracks application releases / versions / deploys.
+    # To automatically set this context, see {.from_env}.
+    class Release < Context
+      @keyspace = :release
+
+      class << self
+        # Builds a release context based on environment variables. Simply add the
+        # `RELEASE_COMMIT`, `RELEASE_CREATED_AT`, or the `RELEASE_VERSION` env vars
+        # to get this context automatially. All are optional, but at least one
+        # must be present.
+        #
+        # If you're on Heroku, simply enable dyno metadata to get this automatically:
+        # https://devcenter.heroku.com/articles/dyno-metadata
+        def from_env
+          commit_hash = ENV['RELEASE_COMMIT'] || ENV['HEROKU_SLUG_COMMIT']
+          created_at = ENV['RELEASE_CREATED_AT'] || ENV['HEROKU_RELEASE_CREATED_AT']
+          version = ENV['RELEASE_VERSION'] || ENV['HEROKU_RELEASE_VERSION']
+
+          if commit_hash || created_at || version
+            new(commit_hash: commit_hash, created_at: created_at, version: version)
+          else
+            nil
+          end
+        end
+      end
+
+      attr_reader :commit_hash, :created_at, :version
+
+      def initialize(attributes)
+        @commit_hash = attributes[:commit_hash]
+        @created_at = attributes[:created_at]
+        @version = attributes[:version]
+      end
+
+      # Builds a hash representation of containing simply objects, suitable for serialization.
+      def as_json(_options = {})
+        {commit_hash: commit_hash, created_at: created_at, version: version}
+      end
+    end
+  end
+end

data/lib/timber/contexts/runtime.rb

@@ -1,6 +1,11 @@
+require "timber/context"
+
 module Timber
   module Contexts
-    # Tracks OS level process information, such as the process ID.
+    # The runtime context adds current runtime data to your logs, such as the file, line number,
+    # class or module name, etc. This makes it easy to tail and search your logs by their
+    # origin in your code. For example, if you are debugging a specific class, you can narrow
+    # by that class and see only it's logs.
     class Runtime < Context
       @keyspace = :runtime
 
@@ -15,6 +20,7 @@ module Timber
         @module_name = attributes[:module_name]
       end
 
+      # Builds a hash representation of containing simply objects, suitable for serialization.
       def as_json(_options = {})
         {application: application, class_name: class_name, file: file, function: function,
           line: line, module_name: module_name}

data/lib/timber/contexts/session.rb

@@ -1,6 +1,12 @@
+require "timber/context"
+require "timber/util"
+
 module Timber
   module Contexts
-    # The session context tracks the current session for the given user.
+    # The session context adds the current session ID to your logs. This allows your
+    # to tail and filter logs by specific session IDs. Moreover, it gives you a unique
+    # identifier to report on user activity by session. This way your logs can tell the
+    # story of how many time a user has engaged your site.
     #
     # @note This is tracked automatically with the {Integrations::Rack::SessionContext} rack
     #   middleware.
@@ -13,6 +19,7 @@ module Timber
         @id = attributes[:id] || raise(ArgumentError.new(":id is required"))
       end
 
+      # Builds a hash representation of containing simply objects, suitable for serialization.
       def as_json(_options = {})
         {id: Timber::Util::Object.try(id, :to_s)}
       end

data/lib/timber/contexts/system.rb

@@ -1,6 +1,9 @@
+require "timber/context"
+require "timber/util"
+
 module Timber
   module Contexts
-    # Tracks OS level process information, such as the process ID.
+    # The system context tracks OS level process information, such as the process ID.
     class System < Context
       @keyspace = :system
 
@@ -12,6 +15,7 @@ module Timber
         @pid = @pid.to_s
       end
 
+      # Builds a hash representation of containing simply objects, suitable for serialization.
       def as_json(_options = {})
         {hostname: hostname, pid: Timber::Util::Object.try(pid, :to_s)}
       end

data/lib/timber/contexts/user.rb

@@ -1,9 +1,15 @@
+require "timber/context"
+require "timber/util"
+
 module Timber
   module Contexts
-    # The user context tracks the currently authenticated user.
+    # The user context adds data about the currently authenticated user to your logs.
+    # By adding this context all of your logs will contain user information. This allows
+    # filter and tail logs by specific users.
     #
     # @note This is tracked automatically with the {Integrations::Rack::UserContext} rack
-    #   middleware.
+    #   middleware for supported authentication frameworks. See {Integrations::Rack::UserContext}
+    #   for more details.
     class User < Context
       @keyspace = :user
 
@@ -15,6 +21,7 @@ module Timber
         @email = attributes[:email]
       end
 
+      # Builds a hash representation of containing simply objects, suitable for serialization.
       def as_json(_options = {})
         {id: Timber::Util::Object.try(id, :to_s), name: name, email: email}
       end

data/lib/timber/current_context.rb

@@ -1,5 +1,7 @@
 require "singleton"
 
+require "timber/contexts/release"
+
 module Timber
   # Holds the current context in a thread safe memory storage. This context is
   # appended to every log line. Think of context as join data between your log lines,
@@ -13,30 +15,43 @@ module Timber
     THREAD_NAMESPACE = :_timber_current_context.freeze
 
     class << self
-      # Convenience method for {#with}. See {#with} for full details and examples.
+      # Convenience method for {CurrentContext#with}. See {CurrentContext#with} for more info.
       def with(*args, &block)
         instance.with(*args, &block)
       end
 
-      # Convenience method for {#add}. See {#add} for full details and examples.
+      # Convenience method for {CurrentContext#add}. See {CurrentContext#add} for more info.
       def add(*args)
         instance.add(*args)
       end
 
-      def hash(*args)
-        instance.hash(*args)
+      # Convenience method for {CurrentContext#fetch}. See {CurrentContext#fetch} for more info.
+      def fetch(*args)
+        instance.fetch(*args)
       end
 
-      # Convenience method for {#remove}. See {#remove} for full details and examples.
+      # Convenience method for {CurrentContext#remove}. See {CurrentContext#remove} for more info.
       def remove(*args)
         instance.remove(*args)
       end
 
+      # Convenience method for {CurrentContext#reset}. See {CurrentContext#reset} for more info.
       def reset(*args)
         instance.reset(*args)
       end
     end
 
+    # Instantiates a new object, automatically adding context based on env variables (if present).
+    # For example, the {Contexts::ReleaseContext} is automatically added if the proper environment
+    # variables are present. Please see that class for more details.
+    def initialize
+      super
+      release_context = Contexts::Release.from_env
+      if release_context
+        add(release_context)
+      end
+    end
+
     # Adds a context and then removes it when the block is finished executing.
     #
     # @note Because context is included with every log line, it is recommended that you limit this
@@ -85,12 +100,13 @@ module Timber
           hash[key] = json
         end
       end
+      expire_cache!
+      self
     end
 
-    # The internal hash that is maintained. It is recommended that you use {#with} and {#add}
-    # for hash maintenance.
-    def hash
-      Thread.current[THREAD_NAMESPACE] ||= {}
+    # Fetch a specific context by key.
+    def fetch(*args)
+      hash.fetch(*args)
     end
 
     # Removes a context. If you wish to remove by key, or some other way, use {#hash} and
@@ -113,18 +129,34 @@ module Timber
           end
         end
       end
+      expire_cache!
+      self
     end
 
     # Resets the context to be blank. Use this carefully! This will remove *any* context,
     # include context that is automatically included with Timber.
     def reset
       hash.clear
+      expire_cache!
+      self
     end
 
     # Snapshots the current context so that you get a moment in time representation of the context,
-    # since the context can change as execution proceeds.
+    # since the context can change as execution proceeds. Note that individual contexts
+    # should be immutable, and we implement snapshot caching as a result of this assumption.
     def snapshot
-      hash.clone
+      @snapshot ||= hash.clone
     end
+
+    private
+      # The internal hash that is maintained. Use {#with} and {#add} for hash maintenance.
+      def hash
+        Thread.current[THREAD_NAMESPACE] ||= {}
+      end
+
+      # Hook to clear any caching implement in this class
+      def expire_cache!
+        @snapshot = nil
+      end
   end
 end