logbrew-sdk 0.1.7 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f086729efb0a0a98821ef3bce8d96b71066b202beff5656917d958e4ca119479
-  data.tar.gz: 7c5eafb18cda7d001dc8c72c9646852e857a46bd4e06508abeda5a23365489a1
+  metadata.gz: 95bb6223a8ef074b3c8dd0973fe99e36734849c1b47a19f1c1ed88655888d71b
+  data.tar.gz: 4ac8224ffe4e2fae6f4262b80a3119f2574982a6c0f384c529c77c74163340fc
 SHA512:
-  metadata.gz: 583a7cdc7ccc4ea1435a31454c0d90cea390a7b9f37e1322c3f39bc84bf0b2c731aaa08abff5384675871f62082fd8fc98c5c2c7284ad89a1fb6c9b1221982e0
-  data.tar.gz: 5093fb1d5ea5540302c6a99c8d6fa7ce1b66142a55010c7d867e1f0539d1fe57525270486c59e58acd687a68bb51e44aaa62f480a3c119681648d9a876d70fbb
+  metadata.gz: f90b3564b39c4546b8a34b424b1f59e8ca5de6afaba35529e511a688712e770c92c04deb547fd7e370bfa1590688be7ce3b11ca5f04ccd7d11ecb022f37ff401
+  data.tar.gz: 3d47121b9f61ed19bbeda0e9389f3daa5137c34b88256ea9b5d3f7e47dd28b4d4c36fc7f94bf0c9e2172be0b65f72235e5e96e2923c113811e0b758158498f18

data/README.md

@@ -4,7 +4,7 @@
   <img src="https://raw.githubusercontent.com/LogBrewCo/sdk/main/assets/brand/logbrew-logo-transparent-512.png" alt="LogBrew logo" width="96" height="96">
 </p>
 
-Public Ruby SDK for building, validating, previewing, and flushing LogBrew event batches, with automatic Rails request, database, cache, view, and error capture; standard-library `Net::HTTP` delivery; opt-in standard-library `Logger` support; and manual Rack helpers.
+Public Ruby SDK for building, validating, previewing, and flushing LogBrew event batches, with automatic Rails request, database, cache, view, error, and ActiveJob capture; standard-library `Net::HTTP` delivery; opt-in standard-library `Logger` support; and manual Rack helpers.
 
 The core package has no runtime gem dependencies. Its automatic integration
 activates only inside an application that has already loaded Rails.
@@ -23,7 +23,7 @@ needed:
 
 ```ruby
 # Gemfile
-gem "logbrew-sdk", "~> 0.1.7"
+gem "logbrew-sdk", "~> 0.1.9"
 ```
 
 ```bash
@@ -53,7 +53,19 @@ frames. Handled Rails reports use `rails.error_reporter` with `handled: true`.
 It does not record concrete request paths, query strings, request or response
 bodies, arbitrary headers, authorization values, cookies, user IDs, exception
 messages, raw backtrace text, source snippets, locals, arguments, or absolute
-paths. Exception messages and raw backtrace text are separate opt-ins:
+paths. Exception messages and raw backtrace text are separate opt-ins.
+
+ActiveJob needs no extra initializer. Each enqueue and execution emits a
+producer or worker span, including bounded adapter identity, retry count, and
+queue wait. A versioned W3C carrier keeps retries and supported queue adapters
+on one trace. A retryable failure remains span evidence; only an unexpected
+terminal `StandardError` creates an unhandled `rails.active_job` issue with
+sanitized structured frames. The adapter does not capture job IDs, queue names,
+arguments, serialized payloads, exception messages, or raw backtraces by
+default. When ActiveJob uses LogBrew's Sidekiq middleware, the inner carrier
+suppresses duplicate Sidekiq spans and issues.
+
+The explicit Rails capture settings are:
 
 | Environment variable | Default | Purpose |
 | --- | --- | --- |

data/lib/logbrew/queue_carrier.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module LogBrew
+  # Bounded W3C carrier shared by explicit and framework-owned queue adapters.
+  module QueueCarrier
+    KEY = "logbrew".freeze
+    VERSION = 1
+    MAX_ENQUEUED_AT_MS = 9_007_199_254_740_991
+    MAX_QUEUE_WAIT_MS = 604_800_000
+
+    module_function
+
+    def create(context, enqueued_at_ms: wall_time_ms)
+      {
+        "version" => VERSION,
+        "traceparent" => Trace.create_headers(context).fetch("traceparent"),
+        "enqueuedAtMs" => enqueued_at_ms
+      }
+    end
+
+    def read(value)
+      keys = %w[enqueuedAtMs traceparent version]
+      return unless value.is_a?(Hash) && value.size == keys.length && keys.all? { |key| value.key?(key) }
+      return unless value["version"] == VERSION
+      return unless value["traceparent"].is_a?(String) && value["traceparent"].bytesize <= 55
+      return unless value["enqueuedAtMs"].is_a?(Integer) && value["enqueuedAtMs"].between?(0, MAX_ENQUEUED_AT_MS)
+
+      Traceparent.parse(value["traceparent"])
+      value
+    rescue SdkError
+      nil
+    end
+
+    def child_context(carrier)
+      parsed = carrier && Traceparent.parse(carrier.fetch("traceparent"))
+      return Trace.create_root if parsed.nil?
+
+      Trace.create(
+        trace_id: parsed.trace_id,
+        span_id: Trace.generate_span_id,
+        parent_span_id: parsed.parent_span_id,
+        trace_flags: parsed.trace_flags
+      )
+    end
+
+    def queue_wait_ms(carrier)
+      return if carrier.nil?
+
+      [[wall_time_ms - carrier.fetch("enqueuedAtMs"), 0].max, MAX_QUEUE_WAIT_MS].min
+    end
+
+    def wall_time_ms
+      (Time.now.to_f * 1000.0).floor
+    end
+  end
+end

data/lib/logbrew/rails.rb

@@ -8,8 +8,6 @@ module LogBrew
   # Process-safe Rails integration installed by RailsRailtie.
   module Rails
     class << self
-      attr_reader :runtime
-
       def install(application:, environment: ENV)
         @installation_mutex ||= Mutex.new
         @installation_mutex.synchronize do
@@ -80,6 +78,9 @@ module LogBrew
       if runtime.configuration.enabled?
         LogBrew::Rails.const_get(:RequestOperations).install(::ActiveSupport::Notifications)
       end
+      ::ActiveSupport.on_load(:active_job) do
+        prepend LogBrew::Rails::ActiveJobExtension unless ancestors.include?(LogBrew::Rails::ActiveJobExtension)
+      end
       middleware = application.config.middleware
       if defined?(::ActionDispatch::ShowExceptions)
         middleware.insert_after(

data/lib/logbrew/rails_integration.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "../logbrew" unless defined?(LogBrew::Client)
+require_relative "queue_carrier"
 require "uri"
 
 module LogBrew
   module Rails
+    singleton_class.attr_reader :runtime
+
     # Immutable, environment-derived settings for the automatic Rails adapter.
     class Configuration
       DEFAULT_ENDPOINT = LogBrew::HttpTransport::DEFAULT_ENDPOINT
@@ -395,6 +398,173 @@ module LogBrew
       end
     end
 
+    # One privacy-bounded producer or worker operation for ActiveJob.
+    class ActiveJobOperation
+      attr_reader :context
+
+      def self.create(runtime, job, kind, carrier: nil)
+        client = runtime&.client
+        return if client.nil?
+
+        new(runtime, client, job, kind, carrier)
+      rescue StandardError => error
+        runtime&.report_error("active_job_capture", error)
+        nil
+      end
+
+      def initialize(runtime, client, job, kind, carrier)
+        @runtime = runtime
+        @client = client
+        @kind = kind
+        @context = kind == :enqueue ? OperationTracing.child_context : QueueCarrier.child_context(QueueCarrier.read(carrier))
+        @job_class = bounded_identifier(job.class.name, "ActiveJob")
+        @adapter = bounded_identifier(job.class.respond_to?(:queue_adapter_name) ? job.class.queue_adapter_name : nil, "active_job")
+        @retry_count = normalized_retry_count(job.respond_to?(:executions) ? job.executions : nil)
+        @queue_wait_ms = kind == :perform ? QueueCarrier.queue_wait_ms(QueueCarrier.read(carrier)) : nil
+        @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        @timestamp = Time.now.utc.iso8601(6)
+        @finished = false
+      end
+
+      def around
+        result = Trace.with_context(@context) { yield }
+        finish
+        result
+      rescue Exception => error # rubocop:disable Lint/RescueException
+        finish(error)
+        raise
+      end
+
+      def finish(error = nil)
+        return if @finished
+
+        @finished = true
+        options = {
+          timestamp: @timestamp,
+          source: "rails.active_job",
+          system: @adapter,
+          operation: @kind.to_s,
+          metadata: operation_metadata
+        }
+        OperationTracing.capture_span(@client, "queue", "active_job.#{@kind}", @context, @started_at, options, error)
+      rescue StandardError => capture_error
+        @runtime.report_error("active_job_capture", capture_error)
+      end
+
+      def capture_terminal_issue(error)
+        return unless error.is_a?(StandardError)
+
+        metadata = operation_metadata.merge(
+          "source" => "rails.active_job",
+          "handled" => false,
+          "mechanism" => "rails.active_job",
+          "issueGroupingKey" => grouping_key(error),
+          "issueGroupingSource" => "exception_type_job_file"
+        )
+        attributes = IssueDiagnostics.from_exception(
+          error,
+          title: IssueDiagnostics.safe_exception_type(error),
+          message: @runtime.configuration.capture_exception_messages? ? error.message : nil,
+          mechanism_type: "rails.active_job",
+          handled: false,
+          metadata: metadata
+        )
+        Trace.with_context(@context) do
+          @client.issue("ruby_active_job_issue_#{@context.span_id}", Time.now.utc.iso8601, attributes)
+        end
+      rescue StandardError => capture_error
+        @runtime.report_error("active_job_capture", capture_error)
+      end
+
+      private
+
+      def operation_metadata
+        @runtime.metadata.merge("activeJob.class" => @job_class).tap do |metadata|
+          metadata["retryCount"] = @retry_count unless @retry_count.nil?
+          metadata["queueWaitMs"] = @queue_wait_ms unless @queue_wait_ms.nil?
+        end
+      end
+
+      def grouping_key(error)
+        frame = IssueDiagnostics.stack_frames_from_exception(error).first
+        file = frame.nil? ? "" : frame.fetch("filename")
+        values = [IssueDiagnostics.safe_exception_type(error), @job_class, file]
+        "rails-active-job-#{Digest::SHA256.hexdigest(values.join("\n"))}"
+      end
+
+      def bounded_identifier(value, fallback)
+        text = value.to_s
+        text.match?(/\A[A-Za-z_][A-Za-z0-9_:.-]{0,254}\z/) ? text : fallback
+      end
+
+      def normalized_retry_count(value)
+        [[value, 0].max, 1_000].min if value.is_a?(Integer)
+      end
+    end
+    private_constant :ActiveJobOperation
+
+    # Adapter-neutral ActiveJob tracing installed through the Rails lazy-load hook.
+    module ActiveJobExtension
+      def enqueue(options = {})
+        operation = ActiveJobOperation.create(LogBrew::Rails.runtime, self, :enqueue)
+        return super if operation.nil?
+
+        previous = @logbrew_enqueue_operation
+        @logbrew_enqueue_operation = operation
+        operation.around { super }
+      ensure
+        @logbrew_enqueue_operation = previous unless operation.nil?
+      end
+
+      def serialize
+        payload = super
+        operation = @logbrew_enqueue_operation
+        return payload if operation.nil?
+
+        begin
+          payload[QueueCarrier::KEY] = QueueCarrier.create(operation.context)
+        rescue StandardError => error
+          LogBrew::Rails.runtime&.report_error("active_job_capture", error)
+        end
+        payload
+      end
+
+      def deserialize(payload)
+        result = super
+        begin
+          @logbrew_queue_carrier = QueueCarrier.read(payload[QueueCarrier::KEY]) if payload.is_a?(Hash)
+        rescue StandardError => error
+          LogBrew::Rails.runtime&.report_error("active_job_capture", error)
+        end
+        result
+      end
+
+      def perform_now
+        operation = ActiveJobOperation.create(LogBrew::Rails.runtime, self, :perform, carrier: @logbrew_queue_carrier)
+        return super if operation.nil?
+
+        previous = @logbrew_perform_operation
+        @logbrew_perform_operation = operation
+        begin
+          Trace.with_context(operation.context) { super }
+        rescue Exception => error # rubocop:disable Lint/RescueException
+          operation.finish(error)
+          operation.capture_terminal_issue(error)
+          raise
+        ensure
+          unless operation.nil?
+            operation.finish
+            @logbrew_perform_operation = previous
+          end
+        end
+      end
+
+      def _perform_job
+        operation = @logbrew_perform_operation
+        operation.nil? ? super : operation.around { super }
+      end
+    end
+
     # Buffers only the slowest request-local framework operations without raw
     # SQL, cache keys, absolute paths, or exception messages.
     module RequestOperations

data/lib/logbrew/sidekiq.rb

@@ -1,16 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "../logbrew"
+require_relative "queue_carrier"
 
 module LogBrew
   # Explicit Sidekiq middleware for app-owned client and server chains.
   module Sidekiq
-    CARRIER_KEY = "logbrew".freeze
-    CARRIER_VERSION = 1
-    MAX_QUEUE_WAIT_MS = 604_800_000
     MAX_RETRY_COUNT = 1_000
     MAX_REPORTED_FAILURES = 1_024
-    private_constant :CARRIER_KEY, :CARRIER_VERSION, :MAX_QUEUE_WAIT_MS, :MAX_RETRY_COUNT, :MAX_REPORTED_FAILURES
+    private_constant :MAX_RETRY_COUNT, :MAX_REPORTED_FAILURES
 
     class TraceOperation
       attr_reader :context, :traceparent
@@ -197,17 +195,13 @@ module LogBrew
       def around_client(job)
         return yield unless capture_enabled?
         return yield unless job.is_a?(Hash)
-        return yield if job.key?(CARRIER_KEY)
+        return yield if active_job_wrapper?(job) || job.key?(QueueCarrier::KEY)
 
         operation = prepare_operation(name: "sidekiq.enqueue", source: "sidekiq.client", continue_current: true)
         return yield if operation.nil?
 
         begin
-          job[CARRIER_KEY] = {
-            "version" => CARRIER_VERSION,
-            "traceparent" => operation.traceparent,
-            "enqueuedAtMs" => wall_time_ms
-          }
+          job[QueueCarrier::KEY] = QueueCarrier.create(operation.context)
         rescue StandardError => error
           report_capture_error(error)
           return yield
@@ -218,16 +212,17 @@ module LogBrew
       def around_server(job)
         return yield unless capture_enabled?
         return yield unless job.is_a?(Hash)
+        return yield if active_job_wrapper?(job)
 
         begin
-          carrier = read_carrier(job[CARRIER_KEY])
+          carrier = QueueCarrier.read(job[QueueCarrier::KEY])
           retry_count = normalized_retry_count(job["retry_count"], job.key?("retry_count"))
           operation = prepare_operation(
             name: "sidekiq.perform",
             source: "sidekiq.server",
             carrier: carrier,
             retry_count: retry_count,
-            queue_wait_ms: queue_wait_ms(carrier)
+            queue_wait_ms: QueueCarrier.queue_wait_ms(carrier)
           )
         rescue StandardError => error
           report_capture_error(error)
@@ -328,15 +323,9 @@ module LogBrew
       end
 
       def prepare_operation(name:, source:, carrier: nil, retry_count: nil, queue_wait_ms: nil, continue_current: false)
-        parsed = carrier && Traceparent.parse(carrier.fetch("traceparent"))
-        parent = parsed.nil? && continue_current ? Trace.current : parsed
-        context = if parsed
-                    Trace.create(
-                      trace_id: parsed.trace_id,
-                      span_id: Trace.generate_span_id,
-                      parent_span_id: parsed.parent_span_id,
-                      trace_flags: parsed.trace_flags
-                    )
+        parent = continue_current ? Trace.current : nil
+        context = if carrier
+                    QueueCarrier.child_context(carrier)
                   elsif parent
                     Trace.create(
                       trace_id: parent.trace_id,
@@ -360,18 +349,12 @@ module LogBrew
         nil
       end
 
-      def read_carrier(value)
-        return nil unless value.is_a?(Hash)
-        keys = %w[enqueuedAtMs traceparent version]
-        return nil unless value.size == keys.length && keys.all? { |key| value.key?(key) }
-        return nil unless value["version"] == CARRIER_VERSION
-        return nil unless value["traceparent"].is_a?(String) && value["traceparent"].bytesize <= 55
-        return nil unless value["enqueuedAtMs"].is_a?(Integer) && value["enqueuedAtMs"].between?(0, 9_007_199_254_740_991)
-
-        Traceparent.parse(value["traceparent"])
-        value
-      rescue SdkError
-        nil
+      def active_job_wrapper?(job)
+        wrapped = job["wrapped"]
+        arguments = job["args"]
+        payload = arguments.first if arguments.is_a?(Array)
+        wrapped.is_a?(String) && payload.is_a?(Hash) && payload["job_class"] == wrapped &&
+          !QueueCarrier.read(payload[QueueCarrier::KEY]).nil?
       end
 
       def normalized_retry_count(value, present)
@@ -392,17 +375,6 @@ module LogBrew
         retry_count >= [limit - 1, 0].max
       end
 
-      def queue_wait_ms(carrier)
-        return nil if carrier.nil?
-
-        elapsed = wall_time_ms - carrier.fetch("enqueuedAtMs")
-        [[elapsed, 0].max, MAX_QUEUE_WAIT_MS].min
-      end
-
-      def wall_time_ms
-        (Time.now.to_f * 1000.0).floor
-      end
-
       def capture_span(operation, error)
         @client.span(
           "ruby_sidekiq_span_#{operation.context.span_id}",

data/lib/logbrew/trace.rb

@@ -240,7 +240,7 @@ module LogBrew
 
     private
 
-    def capture_request_span(env, status_code, elapsed_ms, status)
+    def capture_request_span(env, status_code, elapsed_ms, status, timestamp)
       context = rack_trace_context(env)
       attributes = {
         name: request_name(env),
@@ -252,31 +252,21 @@ module LogBrew
       }
       attributes[:parentSpanId] = context.parent_span_id if context && context.parent_span_id
 
-      @client.span(next_event_id("span"), logbrew_timestamp, attributes)
+      @client.span(next_event_id("span"), timestamp, attributes)
     end
 
     def trace_id(env)
-      context = rack_trace_context(env)
-      return context.trace_id if context
-
-      super
+      rack_trace_context(env)&.trace_id || super
     end
 
     def span_id(env)
-      context = rack_trace_context(env)
-      return context.span_id if context
-
-      super
+      rack_trace_context(env)&.span_id || super
     end
 
     def request_metadata(env, status_code)
       Trace.add_metadata(super, rack_trace_context(env))
     end
 
-    def exception_metadata(env, error)
-      Trace.add_metadata(super, rack_trace_context(env))
-    end
-
     def rack_trace_context(env)
       trace = env["logbrew.trace"] if env.respond_to?(:[])
       trace.is_a?(TraceContext) ? trace : Trace.current

data/lib/logbrew/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module LogBrew
-  VERSION = "0.1.7"
+  VERSION = "0.1.9"
 end

data/lib/logbrew.rb

@@ -45,9 +45,9 @@ module LogBrew
       metadata.each_with_object({}) { |(key, value), copied| copied[key.to_s] = value if primitive_metadata_value?(value) }
     end
 
-    def logbrew_timestamp
+    def logbrew_timestamp(precision = nil)
       timestamp = @timestamp_provider.respond_to?(:call) ? @timestamp_provider.call : Time.now
-      timestamp.respond_to?(:iso8601) ? timestamp.iso8601 : timestamp.to_s
+      timestamp.respond_to?(:iso8601) ? timestamp.iso8601(*[precision].compact) : timestamp.to_s
     end
 
     def capture_safely
@@ -412,36 +412,42 @@ module LogBrew
 
     def call(env)
       started_at = monotonic_time
-      begin
-        response = @app.call(env)
+      started_timestamp, timestamp_error = request_timestamp
+      response = begin
+        @app.call(env)
       rescue StandardError => error
-        status_code = exception_status_code(error)
-        capture_safely do
-          capture_exception_issue(env, error) if status_code >= 500
-          capture_request_span(env, status_code, duration_ms(started_at), status_code >= 500 ? "error" : "ok")
-          flush_if_configured
-        end
+        capture_request(env, exception_status_code(error), started_at, started_timestamp, timestamp_error, error)
         raise
       end
+      capture_request(env, rack_status(response), started_at, started_timestamp, timestamp_error)
+      response
+    end
+
+    private
 
-      status_code = rack_status(response)
+    def capture_request(env, status_code, started_at, timestamp, timestamp_error, error = nil)
       capture_safely do
-        capture_request_span(env, status_code, duration_ms(started_at), status_code >= 500 ? "error" : "ok")
+        raise timestamp_error unless timestamp_error.nil?
+        capture_exception_issue(env, error, logbrew_timestamp(6)) if error && status_code >= 500
+        capture_request_span(env, status_code, duration_ms(started_at), status_code >= 500 ? "error" : "ok", timestamp)
         flush_if_configured
       end
-      response
     end
 
-    private
+    def request_timestamp
+      [logbrew_timestamp(6), nil]
+    rescue StandardError => error
+      [nil, error]
+    end
 
     def exception_status_code(_error)
       500
     end
 
-    def capture_request_span(env, status_code, elapsed_ms, status)
+    def capture_request_span(env, status_code, elapsed_ms, status, timestamp)
       @client.span(
         next_event_id("span"),
-        logbrew_timestamp,
+        timestamp,
         name: request_name(env),
         traceId: trace_id(env),
         spanId: span_id(env),
@@ -451,7 +457,7 @@ module LogBrew
       )
     end
 
-    def capture_exception_issue(env, error)
+    def capture_exception_issue(env, error, timestamp)
       attributes = IssueDiagnostics.from_exception(
         error,
         message: @include_exception_message ? error.message : nil,
@@ -459,7 +465,7 @@ module LogBrew
         handled: false,
         metadata: exception_metadata(env, error)
       )
-      @client.issue(next_event_id("issue"), logbrew_timestamp, attributes)
+      @client.issue(next_event_id("issue"), timestamp, attributes)
     end
 
     def next_event_id(kind)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.7
+  version: 0.1.9
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-13 00:00:00.000000000 Z
+date: 2026-08-17 00:00:00.000000000 Z
 dependencies: []
 description: Public LogBrew Ruby SDK with typed issue diagnostics, automatic Rails
   request/error capture, and standard-library delivery.
@@ -38,6 +38,7 @@ files:
 - lib/logbrew/operation_tracing.rb
 - lib/logbrew/persistent_event_store.rb
 - lib/logbrew/product_timeline.rb
+- lib/logbrew/queue_carrier.rb
 - lib/logbrew/rails.rb
 - lib/logbrew/rails_integration.rb
 - lib/logbrew/sidekiq.rb