koderift-rails 1.3.4 → 2.0.0

data/lib/koderift/rails/instrumentation.rb

@@ -10,11 +10,28 @@ module Koderift
       # partial render times, SQL query times, and breadcrumbs.
       # Returns a hash of captured data to be merged into the log payload.
       def self.capture
+        state = start_capture
+        begin
+          yield
+        ensure
+          stop_capture(state)
+        end
+        build_result(state)
+      end
+
+      # capture's three phases, exposed separately so a unit of work that is
+      # NOT a block runs through the same subscriptions rather than a parallel
+      # implementation. Tracing::Transaction is that caller: it has to be
+      # started and finished by two separate calls to mirror Sentry's
+      # start_transaction / finish, which a block-shaped API cannot express.
+      def self.start_capture
+        config         = Koderift::Rails.configuration
         partials       = []
         queries        = []
         search_queries = []
         breadcrumbs    = []
-        config         = Koderift::Rails.configuration
+        custom_spans   = []
+        external_calls = []
 
         partial_sub = ActiveSupport::Notifications.subscribe('render_partial.action_view') do |*args|
           event      = ActiveSupport::Notifications::Event.new(*args)
@@ -73,36 +90,54 @@ module Koderift
           search_queries << { index: 'multi_search', duration_ms: duration }
         end
 
-        external_calls = []
+        # Published for the same reason external_calls is: code that runs
+        # somewhere else entirely — the Net::HTTP patch, Koderift.add_breadcrumb,
+        # Koderift.with_child_span — has no other way to find the collection
+        # belonging to the unit of work currently in flight on this thread.
+        Thread.current[:koderift_breadcrumbs]     = breadcrumbs
+        Thread.current[:koderift_custom_spans]    = custom_spans
         Thread.current[:koderift_external_calls]  = external_calls
         Thread.current[:koderift_external_config] = config
 
-        begin
-          yield
-        ensure
-          ActiveSupport::Notifications.unsubscribe(partial_sub)
-          ActiveSupport::Notifications.unsubscribe(query_sub)
-          ActiveSupport::Notifications.unsubscribe(search_sub)
-          ActiveSupport::Notifications.unsubscribe(multi_search_sub)
-          Thread.current[:koderift_external_calls]  = nil
-          Thread.current[:koderift_external_config] = nil
+        {
+          config:         config,
+          partials:       partials,
+          queries:        queries,
+          search_queries: search_queries,
+          breadcrumbs:    breadcrumbs,
+          custom_spans:   custom_spans,
+          external_calls: external_calls,
+          subscriptions:  [partial_sub, query_sub, search_sub, multi_search_sub]
+        }
+      end
+
+      def self.stop_capture(state)
+        state[:subscriptions].each do |sub|
+          ActiveSupport::Notifications.unsubscribe(sub)
         end
+        Thread.current[:koderift_breadcrumbs]     = nil
+        Thread.current[:koderift_custom_spans]    = nil
+        Thread.current[:koderift_external_calls]  = nil
+        Thread.current[:koderift_external_config] = nil
+        state
+      end
 
+      def self.build_result(state)
         spans = []
 
-        partials.each_with_index do |p, i|
+        state[:partials].each_with_index do |p, i|
           spans << { type: 'partial', name: p[:partial], duration_ms: p[:duration_ms], sequence: i }
         end
 
-        queries.each_with_index do |q, i|
+        state[:queries].each_with_index do |q, i|
           spans << { type: 'sql', name: q[:sql], duration_ms: q[:duration_ms], sequence: i }
         end
 
-        search_queries.each_with_index do |s, i|
+        state[:search_queries].each_with_index do |s, i|
           spans << { type: 'search', name: s[:index], duration_ms: s[:duration_ms], sequence: i }
         end
 
-        external_calls.each_with_index do |c, i|
+        state[:external_calls].each_with_index do |c, i|
           spans << {
             type:        'http',
             name:        "#{c[:host]}#{c[:endpoint]}",
@@ -112,12 +147,22 @@ module Koderift
           }
         end
 
+        state[:custom_spans].each_with_index do |c, i|
+          spans << {
+            type:        'custom',
+            name:        c[:name],
+            duration_ms: c[:duration_ms],
+            detail:      c[:detail],
+            sequence:    i
+          }.compact
+        end
+
         {
           spans:         spans,
-          query_count:   queries.size,
-          partial_count: partials.size,
-          search_count:  search_queries.size,
-          breadcrumbs:   breadcrumbs.last(config.max_breadcrumbs)
+          query_count:   state[:queries].size,
+          partial_count: state[:partials].size,
+          search_count:  state[:search_queries].size,
+          breadcrumbs:   state[:breadcrumbs].last(state[:config].max_breadcrumbs)
         }
       end
 

data/lib/koderift/rails/lograge_config.rb

@@ -46,9 +46,14 @@ module Koderift
       end
 
       def self.format_backtrace(exception)
-        return nil unless exception&.backtrace&.any?
+        format_frames(exception&.backtrace)
+      end
 
-        backtrace = exception.backtrace
+      # Split out from format_backtrace so a caller holding a raw backtrace
+      # array -- Capture, when given an explicit `backtrace:` -- gets the same
+      # frame selection instead of a second, subtly different implementation.
+      def self.format_frames(backtrace)
+        return nil unless backtrace.is_a?(Array) && backtrace.any?
 
         leading = backtrace.first(LEADING_FRAMES)
 

data/lib/koderift/rails/railtie.rb

@@ -34,6 +34,20 @@ module Koderift
         end
       end
 
+      # Capture uncaught rake task failures. Rake is loaded before the Rails
+      # environment under `bundle exec rake` / `bin/rails <task>`, so the
+      # constant is present by the time initializers run; under a web server it
+      # is not, and the guard makes this a no-cost skip.
+      initializer 'koderift.rake_integration', after: :load_config_initializers do
+        next unless Koderift::Rails.configuration.enabled
+        next unless defined?(::Rake::Application)
+
+        require 'koderift/rails/rake_integration'
+        unless ::Rake::Application.include?(Koderift::Rails::RakeIntegration)
+          ::Rake::Application.prepend(Koderift::Rails::RakeIntegration)
+        end
+      end
+
       # Register Sidekiq server middleware lazily when Sidekiq is present.
       initializer 'koderift.sidekiq_middleware', after: :load_config_initializers do
         next unless Koderift::Rails.configuration.enabled

data/lib/koderift/rails/rake_integration.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Koderift
+  module Rails
+    # Captures uncaught rake task failures.
+    #
+    # This closes the largest blind spot in the product for scheduled work. A
+    # rake task that raises writes its backtrace to STDERR, which under cron
+    # goes to a mail spool or /dev/null — never to production.log — so the log
+    # agent has never seen it and Koderift has never reported it. The tasks
+    # most likely to fail unnoticed are exactly the ones nobody has touched in
+    # a year.
+    #
+    # Rake::Application#display_error_message is the hook Sentry uses for the
+    # same purpose. We capture and then call super, so Rake's own error output
+    # is completely unchanged — anything already scraping that output, or a
+    # human reading the cron mail, sees exactly what it saw before.
+    module RakeIntegration
+      def display_error_message(exception)
+        Koderift::Rails::RakeIntegration.report(exception)
+        super
+      end
+
+      # A clean `exit` inside a task reaches this hook as a SystemExit. It is
+      # the task finishing, not failing, and reporting it would file an error
+      # for every well-behaved task that exits explicitly.
+      def self.report(exception)
+        return if exception.is_a?(SystemExit)
+
+        Koderift.capture_exception(exception, component: task_name, action: 'rake')
+      rescue StandardError
+        nil
+      end
+
+      def self.task_name
+        name = ::Rake.application.top_level_tasks.first.to_s
+        name.empty? ? 'rake' : name
+      rescue StandardError
+        'rake'
+      end
+    end
+  end
+end

data/lib/koderift/rails/scope.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'koderift/rails/breadcrumb'
+
+module Koderift
+  module Rails
+    # Sentry-compatible scope: ambient user/tags/extras/contexts merged into
+    # every capture made while it is current.
+    #
+    # The stack is thread-local, and it is RESET at the end of every request and
+    # Sidekiq job (see Controller and SidekiqMiddleware). That reset is not
+    # housekeeping: Puma and Sidekiq both reuse threads, so without it a tag set
+    # for one user's request would silently attach to the next request served by
+    # that thread.
+    class Scope
+      STACK_KEY = :koderift_scope_stack
+
+      attr_reader :user, :tags, :extras, :contexts
+      attr_accessor :level, :fingerprint, :component, :action
+
+      def initialize
+        @user        = {}
+        @tags        = {}
+        @extras      = {}
+        @contexts    = {}
+        @level       = nil
+        @fingerprint = nil
+        @component   = nil
+        @action      = nil
+      end
+
+      class << self
+        def stack
+          Thread.current[STACK_KEY] ||= [new]
+        end
+
+        def current
+          stack.last
+        end
+
+        def push
+          stack.push(current.dup)
+          current
+        end
+
+        def pop
+          stack.pop if stack.size > 1
+          current
+        end
+
+        def reset!
+          Thread.current[STACK_KEY] = nil
+        end
+
+        # Runs `block` against a temporary copy of the current scope before
+        # yielding, so `capture_exception(e) { |scope| scope.set_tags(...) }`
+        # cannot leak those tags into later captures on the same thread.
+        def with_temporary(block)
+          return yield unless block
+
+          push
+          begin
+            block.call(current)
+            yield
+          ensure
+            pop
+          end
+        end
+      end
+
+      def set_user(hash)
+        @user = stringify(hash)
+        self
+      end
+
+      def set_tags(hash)
+        @tags.merge!(stringify(hash))
+        self
+      end
+
+      def set_tag(key, value)
+        @tags[key.to_s] = value
+        self
+      end
+
+      def set_extras(hash)
+        @extras.merge!(stringify(hash))
+        self
+      end
+
+      def set_extra(key, value)
+        @extras[key.to_s] = value
+        self
+      end
+
+      def set_context(key, value)
+        @contexts[key.to_s] = value
+        self
+      end
+
+      def set_contexts(hash)
+        @contexts.merge!(stringify(hash))
+        self
+      end
+
+      def set_level(level)
+        @level = level
+        self
+      end
+
+      def set_fingerprint(fingerprint)
+        @fingerprint = fingerprint
+        self
+      end
+
+      # Sentry's transaction name is "Controller#action". Koderift stores those
+      # as two separate columns and groups errors on them, so split rather than
+      # keep the joined string.
+      def set_transaction_name(name)
+        component, _, action = name.to_s.partition('#')
+        @component = component.empty? ? nil : component
+        @action    = action.empty?    ? nil : action
+        self
+      end
+
+      def add_breadcrumb(crumb)
+        Breadcrumbs.add(crumb)
+        self
+      end
+
+      def clear_breadcrumbs
+        Breadcrumbs.clear
+        self
+      end
+
+      def clear
+        initialize
+        self
+      end
+
+      def dup
+        copy = self.class.new
+        copy.set_user(@user)
+        copy.set_tags(@tags)
+        copy.set_extras(@extras)
+        copy.set_contexts(@contexts)
+        copy.level       = @level
+        copy.fingerprint = @fingerprint
+        copy.component   = @component
+        copy.action      = @action
+        copy
+      end
+
+      private
+
+      def stringify(hash)
+        return {} unless hash.respond_to?(:each_pair)
+
+        hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/koderift/rails/sidekiq_middleware.rb

@@ -3,6 +3,7 @@
 require 'json'
 require 'securerandom'
 require 'koderift/rails/instrumentation'
+require 'koderift/rails/scope'
 
 module Koderift
   module Rails
@@ -19,6 +20,16 @@ module Koderift
         trace_id = SecureRandom.uuid if trace_id.empty?
         Thread.current[:koderift_trace_id] = trace_id
 
+        # Ambient context for manual captures made anywhere inside the job.
+        # The jid stands in for a request id: it is what correlates a capture
+        # with the job's own log line, and what carries this job's spans into
+        # log_spans (IngestLogBatchJob drops spans on a row with no request id).
+        Thread.current[:koderift_context] = {
+          component:  job_name(job),
+          action:     'perform',
+          request_id: job['jid'].to_s
+        }
+
         start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
         begin
@@ -34,11 +45,23 @@ module Koderift
           raise
         ensure
           Thread.current[:koderift_trace_id] = nil
+          Thread.current[:koderift_context]  = nil
+          # Sidekiq reuses threads across jobs; see the same reset in Controller.
+          Koderift::Rails::Scope.reset!
         end
       end
 
       private
 
+      # The name Sidekiq's own JobLogger logs the job under. For ActiveJob,
+      # job['class'] is the adapter's wrapper (Sidekiq::ActiveJob::Wrapper,
+      # ActiveJob::QueueAdapters::SidekiqAdapter::JobWrapper) for every job, and
+      # job['wrapped'] is the job itself. Matching Sidekiq also lets the agent
+      # pair this line with Sidekiq's "done" line for the same attempt.
+      def job_name(job)
+        (job['wrapped'] || job['class']).to_s
+      end
+
       def emit_job_log(_worker, job, queue, result, duration_ms, trace_id, error:)
         config = Koderift::Rails.configuration
 
@@ -51,7 +74,7 @@ module Koderift
         end
 
         payload = {
-          job_class:    job['class'].to_s,
+          job_class:    job_name(job),
           jid:          job['jid'].to_s,
           queue:        queue.to_s,
           status:       error ? 500 : 200,

data/lib/koderift/rails/tracing.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'securerandom'
+require 'koderift/rails/instrumentation'
+require 'koderift/rails/capture'
+
+module Koderift
+  module Rails
+    # Sentry-compatible custom instrumentation, backed by the span pipeline the
+    # gem already has. A child span becomes a `custom` span in log_spans and
+    # renders in the APM trace next to the SQL, partial and HTTP spans.
+    module Tracing
+      TRANSACTION_KEY = :koderift_transaction
+      MAX_SPAN_NAME   = 2_000
+
+      # Handed to a with_child_span block. set_data and set_description are
+      # real: they shape the span's detail and name in the emitted trace.
+      class ChildSpan
+        attr_reader :op, :description
+
+        def initialize(op: nil, description: nil)
+          @op          = op
+          @description = description
+          @data        = {}
+        end
+
+        def set_data(key, value)
+          @data[key.to_s] = value
+          self
+        end
+
+        def set_description(value)
+          @description = value
+          self
+        end
+
+        def name
+          [@description, @op].map(&:to_s).reject(&:empty?).first || 'custom'
+        end
+
+        def detail
+          payload = @data.dup
+          payload['op'] = @op.to_s unless @op.to_s.empty?
+          payload.empty? ? nil : JSON.generate(payload)
+        rescue StandardError
+          nil
+        end
+      end
+
+      # A unit of work that is neither an HTTP request nor a Sidekiq job — the
+      # nightly rake task case. It runs through Instrumentation's subscriptions
+      # exactly as those two do, so its SQL, HTTP and custom spans reach the
+      # APM trace view.
+      class Transaction
+        attr_reader :name, :op, :request_id, :trace_id
+
+        def initialize(name:, op: nil)
+          @name     = name.to_s
+          @op       = op
+          @finished = false
+
+          # A transaction MUST carry a request_id.
+          # IngestLogBatchJob#build_span_rows does `next if request_id.blank?`,
+          # so without one every span collected here is dropped before it
+          # reaches log_spans — the trace would arrive empty, with no error
+          # anywhere to explain why.
+          @request_id = SecureRandom.uuid
+          @trace_id   = Thread.current[:koderift_trace_id] || SecureRandom.uuid
+
+          @previous_trace_id = Thread.current[:koderift_trace_id]
+          @previous_context  = Thread.current[Capture::CONTEXT_KEY]
+
+          Thread.current[:koderift_trace_id]   = @trace_id
+          Thread.current[Capture::CONTEXT_KEY] = {
+            component:  component,
+            action:     action,
+            request_id: @request_id
+          }
+
+          @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @state      = Instrumentation.start_capture
+        end
+
+        def finished?
+          @finished
+        end
+
+        def finish
+          return nil if @finished
+
+          @finished   = true
+          duration_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at) * 1000).round
+
+          Instrumentation.stop_capture(@state)
+          result = Instrumentation.build_result(@state)
+
+          Capture.transaction(
+            component:   component,
+            action:      action,
+            message:     "Completed in #{(duration_ms / 1000.0).round(1)}s",
+            duration_ms: duration_ms,
+            request_id:  @request_id,
+            trace_id:    @trace_id,
+            result:      result
+          )
+        rescue StandardError
+          nil
+        ensure
+          Thread.current[:koderift_trace_id]   = @previous_trace_id
+          Thread.current[Capture::CONTEXT_KEY] = @previous_context
+          Tracing.clear_current(self)
+        end
+
+        def component
+          part = @name.split('#').first.to_s
+          part.empty? ? 'transaction' : part
+        end
+
+        def action
+          part = @name.split('#')[1].to_s
+          return part unless part.empty?
+
+          op = @op.to_s
+          op.empty? ? 'call' : op
+        end
+      end
+
+      class << self
+        def with_child_span(op: nil, description: nil)
+          span    = ChildSpan.new(op: op, description: description)
+          started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          begin
+            yield span
+          ensure
+            elapsed = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+            record(span, elapsed)
+          end
+        end
+
+        # Returns the Transaction when called without a block, so
+        # `txn = Koderift.start_transaction(name: '...')` / `txn.finish` works
+        # as it does in Sentry. PREFER the block form: it finishes in an ensure,
+        # and an abandoned transaction leaves four ActiveSupport::Notifications
+        # subscribers attached to the process. Starting a new transaction
+        # finishes an abandoned one on the same thread, which bounds that leak
+        # to one, but does not make it free.
+        def start_transaction(name: nil, op: nil)
+          previous = Thread.current[TRANSACTION_KEY]
+          previous.finish if previous.is_a?(Transaction) && !previous.finished?
+
+          transaction = Transaction.new(name: name || op.to_s, op: op)
+          Thread.current[TRANSACTION_KEY] = transaction
+          return transaction unless block_given?
+
+          begin
+            yield transaction
+          ensure
+            transaction.finish
+          end
+        end
+
+        def current_transaction
+          Thread.current[TRANSACTION_KEY]
+        end
+
+        def clear_current(transaction)
+          return unless Thread.current[TRANSACTION_KEY].equal?(transaction)
+
+          Thread.current[TRANSACTION_KEY] = nil
+        end
+
+        private
+
+        # Outside a captured unit of work there is no array to append to, so the
+        # span is simply not recorded. That is inertness for want of a place to
+        # put it, not a stub: inside a request, job or transaction the very same
+        # call produces a real span.
+        def record(span, duration_ms)
+          spans = Thread.current[:koderift_custom_spans]
+          return nil unless spans.is_a?(Array)
+
+          name = span.name.to_s
+          spans << {
+            name:        name.length > MAX_SPAN_NAME ? name[0, MAX_SPAN_NAME] : name,
+            duration_ms: duration_ms,
+            detail:      span.detail
+          }
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/koderift/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Koderift
   module Rails
-    VERSION = '1.3.4'
+    VERSION = '2.0.0'
   end
 end