trailer 0.1.4

data/lib/trailer.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'trailer/concern'
+require 'trailer/configuration'
+require 'trailer/middleware/rack'
+require 'trailer/middleware/sidekiq'
+require 'trailer/railtie' if defined?(Rails::Railtie)
+require 'trailer/recorder'
+require 'trailer/version'
+
+module Trailer
+  class Error < StandardError; end
+
+  class << self
+    attr_accessor :config
+
+    # Accepts a block for configuring things.
+    def configure
+      self.config ||= Configuration.new
+      yield(config) if block_given?
+
+      # Instantiate a new recorder after configuration.
+      @storage = config.storage.new if enabled?
+    end
+
+    # Returns true if tracing is enabled, false otherwise.
+    def enabled?
+      config&.enabled == true
+    end
+
+    # Returns a new recorder instance.
+    def new
+      return unless enabled?
+
+      raise Trailer::Error, 'Trailer.configure must be run before recording' if @storage.nil?
+
+      Trailer::Recorder.new(@storage)
+    end
+  end
+end

data/lib/trailer/concern.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'trailer/utility'
+
+module Trailer
+  module Concern
+    # Traces the given block, with an event name, plus optional resource and tags.
+    #
+    # @param event    [String]                    - Describes the generic kind of operation being done (eg. 'web_request', or 'parse_request').
+    # @param resource [ApplicationRecord, String] - *Ideally just pass an ActiveRecord instance here.*
+    #                                               The resource being operated on, or its name. Usually domain-specific, such as a model
+    #                                               instance, query, etc (eg. current_user, 'Article#submit', 'http://example.com/articles').
+    # @param tags     Hash                        - Extra tags which should be tracked (eg. { method: 'GET' }).
+    def trace_event(event, resource = nil, **tags, &block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      return yield block unless Trailer.enabled?
+
+      event = Trailer::Utility.resource_name(event) unless event.is_a?(String)
+
+      unless resource.nil?
+        resource_name   = resource if resource.is_a?(String)
+        resource_name ||= Trailer::Utility.resource_name(resource)
+
+        # If column_names() is available, we are probably looking at an ActiveRecord instance.
+        if resource.class.respond_to?(:column_names)
+          resource.class.column_names.each do |field|
+            tags[field] ||= resource.public_send(field) if field.match?(Trailer.config.auto_tag_fields)
+          end
+        elsif resource.respond_to?(:to_h)
+          # This handles other types of data, such as GraphQL input objects.
+          resource.to_h.stringify_keys.each do |key, value|
+            tags[key] ||= value if key.to_s.match?(Trailer.config.auto_tag_fields) || Trailer.config.tag_fields.include?(key)
+          end
+        end
+
+        # Tag fields that have been explicitly included.
+        Trailer.config.tag_fields.each do |field|
+          tags[field] ||= resource.public_send(field) if resource.respond_to?(field)
+        end
+
+        tags["#{resource_name}_id"] ||= resource.id if resource.respond_to?(:id)
+      end
+
+      # Record the ID of the current user, if configured.
+      if Trailer.config.current_user_method && respond_to?(Trailer.config.current_user_method, true)
+        user = send(Trailer.config.current_user_method)
+        tags["#{Trailer.config.current_user_method}_id"] = user.id if user&.respond_to?(:id)
+      end
+
+      # Record how long the operation takes, in milliseconds.
+      started_at      = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      result          = yield block
+      tags[:duration] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1_000).ceil
+
+      # Put the keys in alphabetical order, with the event and resource first.
+      sorted = { event: event, resource: resource_name }.merge(tags.sort_by { |key, _val| key.to_s }.to_h)
+      RequestStore.store[:trailer].write(sorted)
+
+      result
+    end
+
+    # Traces the given block with optional resource and tags. It will generate an event name based on the
+    # calling class, and pass the information on to trace_event().
+    #
+    # @param resource [ApplicationRecord, String] - *Ideally just pass an ActiveRecord instance here.*
+    #                                               The resource being operated on, or its name. Usually domain-specific, such as a model
+    #                                               instance, query, etc (eg. current_user, 'Article#submit', 'http://example.com/articles').
+    # @param tags     Hash                        - Extra tags which should be tracked (eg. { method: 'GET' }).
+    def trace_class(resource = nil, **tags, &block)
+      trace_event(self.class.name, resource, **tags) do
+        yield block
+      end
+    end
+
+    # Traces the given block with optional resource and tags. It will generate an event name based on the
+    # calling method and class, and pass the information on to trace_event().
+    #
+    # @param resource [ApplicationRecord, String] - *Ideally just pass an ActiveRecord instance here.*
+    #                                               The resource being operated on, or its name. Usually domain-specific, such as a model
+    #                                               instance, query, etc (eg. current_user, 'Article#submit', 'http://example.com/articles').
+    # @param tags     Hash                        - Extra tags which should be tracked (eg. { method: 'GET' }).
+    def trace_method(resource = nil, **tags, &block)
+      calling_klass  = self.class.name
+      calling_method = caller(1..1).first[/`.*'/][1..-2]
+      trace_event("#{calling_klass}##{calling_method}", resource, **tags) do
+        yield block
+      end
+    end
+  end
+end

data/lib/trailer/configuration.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'trailer/storage/cloud_watch'
+
+module Trailer
+  class Configuration
+    attr_accessor :application_name,
+                  :auto_tag_fields,
+                  :aws_access_key_id,
+                  :aws_region,
+                  :aws_secret_access_key,
+                  :current_user_method,
+                  :enabled,
+                  :environment,
+                  :storage,
+                  :host_name,
+                  :service_name,
+                  :tag_fields
+
+    # Constructor.
+    def initialize
+      # The global application or company name.
+      @application_name      = ENV['TRAILER_APPLICATION_NAME']
+      # When tracing ActiveRecord instances, we can tag our trace with fields matching this regex.
+      @auto_tag_fields       = /(_id|_at)$/.freeze
+      # AWS access key with CloudWatch write permission.
+      @aws_access_key_id     = ENV['AWS_ACCESS_KEY_ID']
+      # The AWS region to log to.
+      @aws_region            = ENV.fetch('AWS_REGION', 'us-east-1')
+      # The AWS secret.
+      @aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+      # Allows tracing to be explicitly disabled.
+      @enabled               = true
+      # The environment that the application is running (eg. 'production', 'test').
+      @environment           = ENV['TRAILER_ENV'] || ENV['RAILS_ENV'] || ENV['RACK_ENV']
+      # Optional - the name of the individual host or server within the service.
+      @host_name             = ENV['TRAILER_HOST_NAME']
+      # The name of the service within the application.
+      @service_name          = ENV['TRAILER_SERVICE_NAME']
+      # The storage backend class to use.
+      @storage               = Trailer::Storage::CloudWatch
+      # Optional - When tracing ActiveRecord instances, we can tag our trace with these fields explicitly.
+      @tag_fields            = %w[name]
+    end
+  end
+end

data/lib/trailer/middleware/rack.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Trailer
+  module Middleware
+    class Rack
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        if Trailer.enabled?
+          RequestStore.store[:trailer] ||= Trailer.new
+          RequestStore.store[:trailer].start
+        end
+        @app.call(env)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        RequestStore.store[:trailer].add_exception(e) if Trailer.enabled?
+        raise e
+      ensure
+        RequestStore.store[:trailer].finish if Trailer.enabled?
+      end
+    end
+  end
+end

data/lib/trailer/middleware/sidekiq.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Trailer
+  module Middleware
+    class Sidekiq
+      def call(_worker, _job, _queue)
+        if Trailer.enabled?
+          RequestStore.store[:trailer] ||= Trailer.new
+          RequestStore.store[:trailer].start
+        end
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        RequestStore.store[:trailer].add_exception(e) if Trailer.enabled?
+        raise e
+      ensure
+        RequestStore.store[:trailer].finish if Trailer.enabled?
+      end
+    end
+  end
+end

data/lib/trailer/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Trailer
+  class Railtie < ::Rails::Railtie
+    initializer 'trailer.insert_middleware' do |app|
+      # Rack middleware.
+      app.config.middleware.insert_after RequestStore::Middleware, Trailer::Middleware::Rack if defined?(RequestStore::Middleware)
+
+      # Sidekiq middleware.
+      if defined?(::Sidekiq)
+        ::Sidekiq.configure_server do |config|
+          config.server_middleware do |chain|
+            chain.add Trailer::Middleware::Sidekiq
+          end
+        end
+      end
+    end
+  end
+end

data/lib/trailer/recorder.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Trailer
+  class Recorder
+    # Constructor.
+    #
+    # @param storage [Object] A storage instance. See https://github.com/Shuttlerock/trailer#storage
+    def initialize(storage)
+      @storage = storage
+    end
+
+    # Records the exception class and message on the current trace.
+    #
+    # @param err [Exception] The exception to record.
+    def add_exception(err)
+      write({ exception: err.class.name, message: err.message, trace: err.backtrace[0..9] })
+    end
+
+    # Finish tracing, and flush storage.
+    def finish
+      storage.async.flush
+      @trace_id = nil
+    end
+
+    # Create a new trace ID to link log entries.
+    def start
+      raise Trailer::Error, 'finish() must be called before a new trace can be started' unless @trace_id.nil?
+
+      # See https://github.com/aws/aws-xray-sdk-ruby/blob/1869ca5/lib/aws-xray-sdk/model/segment.rb#L26-L30
+      @trace_id = %(1-#{Time.now.to_i.to_s(16)}-#{SecureRandom.hex(12)})
+    end
+
+    # Write the given hash to storage.
+    #
+    # @param data [Hash] A key-value hash of trace data to write to storage.
+    def write(data)
+      raise Trailer::Error, 'start() must be called before write()' if @trace_id.nil?
+      raise Trailer::Error, 'data must be an instance of Hash' unless data.is_a?(Hash)
+      raise Trailer::Error, 'could not convert data to JSON' unless data.respond_to?(:to_json)
+
+      # Include some standard tags.
+      data[:environment]  ||= Trailer.config.environment
+      data[:host_name]    ||= Trailer.config.host_name
+      data[:service_name] ||= Trailer.config.service_name
+
+      storage.async.write(data.compact.merge(trace_id: trace_id))
+    end
+
+    private
+
+    attr_accessor :storage, :trace_id
+  end
+end

data/lib/trailer/storage/cloud_watch.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'aws-sdk-cloudwatchlogs'
+require 'concurrent'
+
+module Trailer
+  module Storage
+    class CloudWatch
+      include Concurrent::Async
+
+      # Constructor.
+      def initialize
+        self.messages = []
+        self.client   = Aws::CloudWatchLogs::Client.new(region: Trailer.config.aws_region, credentials: credentials)
+        ensure_log_group
+        ensure_log_stream
+      end
+
+      # Queues the given hash for writing to CloudWatch.
+      #
+      # @param data [Hash] A key-value hash of trace data to write to storage.
+      def write(data)
+        messages << {
+          timestamp: (Time.now.utc.to_f.round(3) * 1000).to_i,
+          message:   data&.to_json,
+        }.compact
+      end
+
+      # Sends all of the queued messages to CloudWatch, and resets the messages queue.
+      #
+      # See https://stackoverflow.com/a/36901509
+      def flush
+        return if messages.empty?
+
+        events = {
+          log_group_name:  Trailer.config.application_name,
+          log_stream_name: Trailer.config.application_name,
+          log_events:      messages,
+          sequence_token:  sequence_token,
+        }
+
+        response            = client.put_log_events(events)
+        self.sequence_token = response&.next_sequence_token
+        self.messages       = []
+      rescue Aws::CloudWatchLogs::Errors::InvalidSequenceTokenException
+        # Only one client at a time can write to the log. If another client has written before we get a chance,
+        # the sequence token is invalidated, and we need to get a new one.
+        self.sequence_token = log_stream[:upload_sequence_token]
+        retry
+      end
+
+      private
+
+      attr_accessor :client, :messages, :sequence_token
+
+      # Returns an AWS credentials instance for writing to CloudWatch.
+      def credentials
+        Aws::Credentials.new(Trailer.config.aws_access_key_id, Trailer.config.aws_secret_access_key)
+      end
+
+      # Creates the log group, if it doesn't already exist. Ideally we would paginate here in case
+      # the account has a lot of log groups with the same prefix, but it seems unlikely to happen.
+      def ensure_log_group
+        existing = client.describe_log_groups.log_groups.find do |group|
+          group.log_group_name == Trailer.config.application_name
+        end
+
+        client.create_log_group(log_group_name: Trailer.config.application_name) unless existing
+      rescue Aws::CloudWatchLogs::Errors::ResourceAlreadyExistsException
+        # No need to do anything - probably caused by lack of pagination.
+      end
+
+      # Create the log stream, if it doesn't already exist.
+      # Ideally we would paginate here in case the account has a lot of log streams.
+      def ensure_log_stream
+        if (existing = log_stream)
+          self.sequence_token = existing.upload_sequence_token
+        else
+          client.create_log_stream(
+            log_group_name:  Trailer.config.application_name,
+            log_stream_name: Trailer.config.application_name,
+          )
+        end
+      rescue Aws::CloudWatchLogs::Errors::ResourceAlreadyExistsException
+        # No need to do anything - probably caused by lack of pagination.
+      end
+
+      # Returns the current log stream, if one exists.
+      def log_stream
+        client.describe_log_streams(
+          log_group_name:         Trailer.config.application_name,
+          log_stream_name_prefix: Trailer.config.application_name,
+        ).log_streams.find do |stream|
+          stream.log_stream_name == Trailer.config.application_name
+        end
+      end
+    end
+  end
+end

data/lib/trailer/utility.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Trailer
+  class Utility
+    class << self
+      # Copied from ActiveSupport::Inflector to avoid introducing an extra dependency.
+      #
+      # @param path [String] The path to demodulize.
+      #
+      # @see https://apidock.com/rails/ActiveSupport/Inflector/demodulize
+      #
+      # Removes the module part from the expression in the string.
+      #
+      #   demodulize('ActiveSupport::Inflector::Inflections') # => "Inflections"
+      #   demodulize('Inflections')                           # => "Inflections"
+      #   demodulize('::Inflections')                         # => "Inflections"
+      #   demodulize('')                                      # => ""
+      def demodulize(path)
+        path = path.to_s
+        if (i = path.rindex('::'))
+          path[(i + 2)..]
+        else
+          path
+        end
+      end
+
+      # Copied from ActiveSupport::Inflector to avoid introducing an extra dependency.
+      #
+      # @param camel_cased_word [String] The word to underscore.
+      #
+      # @see https://apidock.com/rails/v5.2.3/ActiveSupport/Inflector/underscore
+      #
+      # Makes an underscored, lowercase form from the expression in the string.
+      #
+      # Changes '::' to '/' to convert namespaces to paths.
+      #
+      #   underscore('ActiveModel')         # => "active_model"
+      #   underscore('ActiveModel::Errors') # => "active_model/errors"
+      def underscore(camel_cased_word)
+        return camel_cased_word unless /[A-Z-]|::/.match?(camel_cased_word)
+
+        word = camel_cased_word.to_s.gsub('::', '/')
+        word.gsub!(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+        word.gsub!(/([a-z\d])([A-Z])/, '\1_\2')
+        word.tr!('-', '_')
+        word.downcase!
+        word
+      end
+
+      # Creates a name for the given resource instance, suitable for recording in the trace.
+      #
+      # @param resource [Object] The resource instance to derive a name for.
+      def resource_name(resource)
+        return if resource.nil?
+
+        underscore(demodulize(resource.class.name))
+      end
+    end
+  end
+end