koderift-rails 1.3.4 → 2.1.0

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.1.0'
   end
 end

data/lib/koderift/rails.rb

@@ -4,6 +4,11 @@ require 'koderift/rails/version'
 require 'koderift/rails/configuration'
 require 'koderift/rails/instrumentation'
 require 'koderift/rails/lograge_config'
+require 'koderift/rails/event'
+require 'koderift/rails/breadcrumb'
+require 'koderift/rails/scope'
+require 'koderift/rails/capture'
+require 'koderift/rails/tracing'
 require 'koderift/rails/controller'
 require 'koderift/rails/rum_helper'
 require 'koderift/rails/railtie' if defined?(::Rails::Railtie)
@@ -21,7 +26,189 @@ module Koderift
 
       def reset!
         @configuration = Configuration.new
+        Capture.reset_rate_limiter!
+        Scope.reset!
+        Breadcrumbs.clear
+        RumHelper.reset_warnings!
       end
+
+      # ---------------------------------------------------------------- capture
+
+      def capture_exception(error, **options, &block)
+        Capture.exception(error, **options, &block)
+      end
+
+      def capture_message(text, **options, &block)
+        Capture.message(text, **options, &block)
+      end
+
+      def capture_event(event)
+        Capture.event(event)
+      end
+
+      def last_event_id
+        Capture.last_event_id
+      end
+
+      def initialized?
+        Capture.initialized?
+      end
+
+      def exception_captured?(error)
+        Capture.exception_captured?(error)
+      end
+
+      # ------------------------------------------------------------------ scope
+
+      def get_current_scope
+        Scope.current
+      end
+
+      def configure_scope
+        yield Scope.current if block_given?
+        Scope.current
+      end
+
+      def with_scope
+        Scope.push
+        begin
+          yield Scope.current
+        ensure
+          Scope.pop
+        end
+      end
+
+      def set_user(user)
+        Scope.current.set_user(user)
+      end
+
+      def set_tags(tags)
+        Scope.current.set_tags(tags)
+      end
+
+      def set_tag(key, value)
+        Scope.current.set_tag(key, value)
+      end
+
+      def set_extras(extras)
+        Scope.current.set_extras(extras)
+      end
+
+      def set_extra(key, value)
+        Scope.current.set_extra(key, value)
+      end
+
+      def set_context(key, value)
+        Scope.current.set_context(key, value)
+      end
+
+      def add_breadcrumb(crumb)
+        Breadcrumbs.add(crumb)
+      end
+
+      # ---------------------------------------------------------------- tracing
+
+      def start_transaction(name: nil, op: nil, &block)
+        Tracing.start_transaction(name: name, op: op, &block)
+      end
+
+      def with_child_span(op: nil, description: nil, &block)
+        Tracing.with_child_span(op: op, description: description, &block)
+      end
+    end
+  end
+
+  # Sentry-shaped constant, so `Sentry::Breadcrumb.new(...)` becomes
+  # `Koderift::Breadcrumb.new(...)` under the same find-and-replace that
+  # rewrites the method calls.
+  Breadcrumb = Rails::Breadcrumb
+
+  # The migration surface. An app instrumented with Sentry swaps the namespace
+  # and keeps its call sites, including the idiom this API was built for:
+  #
+  #   event_id = Koderift.capture_exception(error)&.event_id
+  #
+  # Delegators are written out rather than metaprogrammed so the signatures are
+  # greppable and `method(:capture_exception).parameters` tells the truth.
+  class << self
+    def capture_exception(error, **options, &block)
+      Rails.capture_exception(error, **options, &block)
+    end
+
+    def capture_message(text, **options, &block)
+      Rails.capture_message(text, **options, &block)
+    end
+
+    def capture_event(event)
+      Rails.capture_event(event)
+    end
+
+    def last_event_id
+      Rails.last_event_id
+    end
+
+    def initialized?
+      Rails.initialized?
+    end
+
+    def exception_captured?(error)
+      Rails.exception_captured?(error)
+    end
+
+    def get_current_scope
+      Rails.get_current_scope
+    end
+
+    def configure_scope(&block)
+      Rails.configure_scope(&block)
+    end
+
+    def with_scope(&block)
+      Rails.with_scope(&block)
+    end
+
+    def set_user(user)
+      Rails.set_user(user)
+    end
+
+    def set_tags(tags)
+      Rails.set_tags(tags)
+    end
+
+    def set_tag(key, value)
+      Rails.set_tag(key, value)
+    end
+
+    def set_extras(extras)
+      Rails.set_extras(extras)
+    end
+
+    def set_extra(key, value)
+      Rails.set_extra(key, value)
+    end
+
+    def set_context(key, value)
+      Rails.set_context(key, value)
+    end
+
+    def add_breadcrumb(crumb)
+      Rails.add_breadcrumb(crumb)
+    end
+
+    def start_transaction(name: nil, op: nil, &block)
+      Rails.start_transaction(name: name, op: op, &block)
+    end
+
+    def with_child_span(op: nil, description: nil, &block)
+      Rails.with_child_span(op: op, description: description, &block)
+    end
+
+    def configure(&block)
+      Rails.configure(&block)
+    end
+
+    def configuration
+      Rails.configuration
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: koderift-rails
 version: !ruby/object:Gem::Version
-  version: 1.3.4
+  version: 2.1.0
 platform: ruby
 authors:
 - Koderift
@@ -110,13 +110,19 @@ files:
 - README.md
 - lib/koderift-rails.rb
 - lib/koderift/rails.rb
+- lib/koderift/rails/breadcrumb.rb
+- lib/koderift/rails/capture.rb
 - lib/koderift/rails/configuration.rb
 - lib/koderift/rails/controller.rb
+- lib/koderift/rails/event.rb
 - lib/koderift/rails/instrumentation.rb
 - lib/koderift/rails/lograge_config.rb
 - lib/koderift/rails/railtie.rb
+- lib/koderift/rails/rake_integration.rb
 - lib/koderift/rails/rum_helper.rb
+- lib/koderift/rails/scope.rb
 - lib/koderift/rails/sidekiq_middleware.rb
+- lib/koderift/rails/tracing.rb
 - lib/koderift/rails/version.rb
 homepage: https://github.com/koderift/koderift-rails
 licenses: