logtail-ruby 0.1.0

data/lib/logtail/contexts/release.rb

@@ -0,0 +1,52 @@
+require "logtail/config"
+require "logtail/context"
+require "logtail/util"
+
+module Logtail
+  module Contexts
+    # @private
+    class Release < Context
+      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
+            Logtail::Config.instance.debug { "Release env vars detected, adding to context" }
+            new(commit_hash: commit_hash, created_at: created_at, version: version)
+          else
+            Logtail::Config.instance.debug { "Release env vars _not_ detected" }
+            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 containing simple objects, suitable for serialization (JSON).
+      def to_hash
+        @to_hash ||= {
+          release: Util::NonNilHashBuilder.build do |h|
+            h.add(:commit_hash, commit_hash)
+            h.add(:created_at, created_at)
+            h.add(:version, version)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/logtail/contexts/runtime.rb

@@ -0,0 +1,23 @@
+require "logtail/context"
+
+module Logtail
+  module Contexts
+    # @private
+    class Runtime < Context
+      attr_reader :thread_id
+
+      def initialize(attributes)
+        @thread_id = attributes[:thread_id]
+      end
+
+      # Builds a hash representation containing simple objects, suitable for serialization (JSON).
+      def to_hash
+        @to_hash ||= {
+          runtime: Util::NonNilHashBuilder.build do |h|
+            h.add(:thread_id, thread_id)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/logtail/contexts/session.rb

@@ -0,0 +1,24 @@
+require "logtail/context"
+require "logtail/util"
+
+module Logtail
+  module Contexts
+    # @private
+    class Session < Context
+      attr_reader :id
+
+      def initialize(attributes)
+        @id = attributes[:id]
+      end
+
+      # Builds a hash representation containing simple objects, suitable for serialization (JSON).
+      def to_hash
+        @to_hash ||= {
+          session: Util::NonNilHashBuilder.build do |h|
+            h.add(:id, id)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/logtail/contexts/system.rb

@@ -0,0 +1,29 @@
+require "logtail/context"
+require "logtail/util"
+
+module Logtail
+  module Contexts
+    # The system context tracks OS level process information, such as the process ID.
+    #
+    # @note This is tracked automatically in {CurrentContext}. When the current context
+    #   is initialized, the system context gets added automatically.
+    class System < Context
+      attr_reader :hostname, :pid
+
+      def initialize(attributes)
+        @hostname = attributes[:hostname]
+        @pid = attributes[:pid]
+      end
+
+      # Builds a hash representation containing simple objects, suitable for serialization (JSON).
+      def to_hash
+        @to_hash ||= {
+          system: Util::NonNilHashBuilder.build do |h|
+            h.add(:hostname, hostname)
+            h.add(:pid, pid)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/logtail/contexts/user.rb

@@ -0,0 +1,28 @@
+require "logtail/context"
+require "logtail/util"
+
+module Logtail
+  module Contexts
+    # @private
+    class User < Context
+      attr_reader :id, :name, :email
+
+      def initialize(attributes)
+        @id = attributes[:id]
+        @name = attributes[:name]
+        @email = attributes[:email]
+      end
+
+      # Builds a hash representation containing simple objects, suitable for serialization (JSON).
+      def to_hash
+        @to_hash ||= {
+          user: Util::NonNilHashBuilder.build do |h|
+            h.add(:id, id)
+            h.add(:name, name)
+            h.add(:email, email)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/logtail/current_context.rb

@@ -0,0 +1,168 @@
+require "socket"
+
+require "logtail/config"
+
+module Logtail
+  # 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,
+  # allowing you to relate them and filter them appropriately.
+  #
+  # @note Because context is appended to every log line, it is recommended that you limit this
+  #   to only necessary data needed to relate your log lines.
+  class CurrentContext
+    THREAD_NAMESPACE = :_logtail_current_context.freeze
+
+    class << self
+      # Implements the Singleton pattern in a thread specific way. Each thread receives
+      # its own context.
+      def instance
+        Thread.current[THREAD_NAMESPACE] ||= new
+      end
+
+      # Convenience method for {CurrentContext#add}. See {CurrentContext#add} for more info.
+      def add(*args)
+        instance.add(*args)
+      end
+
+      # Convenience method for {CurrentContext#fetch}. See {CurrentContext#fetch} for more info.
+      def fetch(*args)
+        instance.fetch(*args)
+      end
+
+      # 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
+
+      # Convenience method for {CurrentContext#with}. See {CurrentContext#with} for more info.
+      def with(*args, &block)
+        instance.with(*args, &block)
+      end
+    end
+
+    # Adds contexts but does not remove them. See {#with} for automatic maintenance and {#remove}
+    # to remove them yourself.
+    #
+    # @note Because context is included with every log line, it is recommended that you limit this
+    #   to only necessary data.
+    def add(*objects)
+      objects.each do |object|
+        hash.merge!(object.to_hash)
+      end
+      expire_cache!
+      self
+    end
+
+    # 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
+    # modify the hash accordingly.
+    def remove(*keys)
+      keys.each do |keys|
+        hash.delete(keys)
+      end
+      expire_cache!
+      self
+    end
+
+    def replace(hash)
+      @hash = hash
+      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 Logtail.
+    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. Note that individual contexts
+    # should be immutable, and we implement snapshot caching as a result of this assumption.
+    def snapshot
+      @snapshot ||= hash.clone
+    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
+    #   to only necessary data.
+    #
+    # @example Adding a custom context
+    #   Logtail::CurrentContext.with({build: {version: "1.0.0"}}) do
+    #     # ... anything logged here will include the context ...
+    #   end
+    #
+    # @note Any custom context needs to have a single root key to be valid. i.e. instead of:
+    #   Logtail::CurrentContext.with(job_id: "123", job_name: "Refresh User Account")
+    #
+    # do
+    #
+    #   Logtail::CurrentContext.with(job: {job_id: "123", job_name: "Refresh User Account"})
+    #
+    # @example Adding multiple contexts
+    #   Logtail::CurrentContext.with(context1, context2) { ... }
+    def with(*objects)
+      old_hash = hash.clone
+      begin
+        add(*objects)
+        yield
+      ensure
+        replace(old_hash)
+      end
+    end
+
+    private
+      # The internal hash that is maintained. Use {#with} and {#add} for hash maintenance.
+      def hash
+        @hash ||= build_initial_hash
+      end
+
+      # Builds the initial hash. This is extract into a method to support a threaded
+      # environment. Each thread holds it's own context and also needs to instantiate
+      # it's hash properly.
+      def build_initial_hash
+        new_hash = {}
+
+        # Release context
+        release_context = Util::NonNilHashBuilder.build do |h|
+          h.add(:commit_hash, ENV['RELEASE_COMMIT'] || ENV['HEROKU_SLUG_COMMIT'])
+          h.add(:created_at, ENV['RELEASE_CREATED_AT'] || ENV['HEROKU_RELEASE_CREATED_AT'])
+          h.add(:version, ENV['RELEASE_VERSION'] || ENV['HEROKU_RELEASE_VERSION'])
+        end
+
+        if release_context != {}
+          new_hash.merge!({release: release_context})
+        end
+
+        # System context
+        hostname = Socket.gethostname
+        pid = Process.pid
+        system_context = Contexts::System.new(hostname: hostname, pid: pid)
+        new_hash.merge!(system_context.to_hash)
+
+        # Runtime context
+        thread_object_id = Thread.current.object_id
+        runtime_context = {thread_id: thread_object_id}
+        new_hash.merge!({runtime: runtime_context})
+
+        new_hash
+      end
+
+      # Hook to clear any caching implement in this class
+      def expire_cache!
+        @snapshot = nil
+      end
+  end
+end

data/lib/logtail/event.rb

@@ -0,0 +1,36 @@
+module Logtail
+  # Base class for `Logtail::Events::*`
+  # @private
+  class Event
+    attr_reader :message, :metadata
+    def initialize(message, metadata)
+      @message = message || ""
+      @metadata = metadata || {}
+    end
+
+    # This ensures that Logtail events get logged as messages if they are passed to
+    # the standard ::Logger.
+    #
+    # See: https://github.com/ruby/ruby/blob/f6e77b9d3555c1fbaa8aab1cdc0bd6bde95f62c6/lib/logger.rb#L615
+    def inspect
+      message
+    end
+
+    def to_json(options = {})
+      metadata.to_json(options)
+    end
+
+    def to_hash
+      metadata
+    end
+    alias to_h to_hash
+
+    def to_msgpack(*args)
+      metadata.to_msgpack(*args)
+    end
+
+    def to_s
+      message
+    end
+  end
+end

data/lib/logtail/events.rb

@@ -0,0 +1,10 @@
+require "logtail/events/controller_call"
+require "logtail/events/error"
+require "logtail/events/sql_query"
+require "logtail/events/template_render"
+
+module Logtail
+  # Namespace for all Logtail supported events.
+  module Events
+  end
+end

data/lib/logtail/events/controller_call.rb

@@ -0,0 +1,44 @@
+require "logtail/util"
+require "logtail/event"
+
+module Logtail
+  module Events
+    # @private
+    class ControllerCall < Logtail::Event
+      attr_reader :controller, :action, :params, :params_json, :format
+
+      def initialize(attributes)
+        @controller = attributes[:controller]
+        @action = attributes[:action]
+        @params = attributes[:params]
+
+        if @params
+          @params_json = @params.to_json
+        end
+
+        @format = attributes[:format]
+      end
+
+      def message
+        message = "Processing by #{controller}##{action}"
+        if !message.nil?
+          message << " as #{format}"
+        end
+        if !params.nil? && params.length > 0
+          message << "\n  Parameters: #{params.inspect}"
+        end
+        message
+      end
+
+      def to_hash
+        {
+          controller_called: Util::NonNilHashBuilder.build do |h|
+            h.add(:controller, controller)
+            h.add(:action, action)
+            h.add(:params_json, params_json)
+          end
+        }
+      end
+    end
+  end
+end

data/lib/logtail/events/error.rb

@@ -0,0 +1,40 @@
+require "logtail/util"
+require "logtail/event"
+
+module Logtail
+  module Events
+    # @private
+    class Error < Logtail::Event
+      attr_reader :name, :error_message, :backtrace_json
+
+      def initialize(attributes)
+        @name = attributes[:name]
+        @error_message = attributes[:error_message]
+
+        if attributes[:backtrace]
+          @backtrace_json = attributes[:backtrace].to_json
+        end
+      end
+
+      def message
+        message = "#{name}"
+
+        if !error_message.nil?
+          message << " (#{error_message})"
+        end
+
+        message
+      end
+
+      def to_hash
+        {
+          error: {
+            name: name,
+            message: error_message,
+            backtrace_json: backtrace_json
+          }
+        }
+      end
+    end
+  end
+end