logbrew-sdk 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 23bb3971a708e01fb3baa93461beb30dda7ff5a6d1b807a6f21a2c4365b718ee
-  data.tar.gz: 2254bb2a7317aa32053e43ae2463ba527c8ec4bd9d7147d31a1c085df690857d
+  metadata.gz: 8ed4c09b597bf3b6c6d2a9426c378c1ef86c3ad32b141cdbf8782d0477ba41d6
+  data.tar.gz: aae266ff513452aa9adc3e48d53ff117aa9ea80bbd6d5dd3ed35da05db2cbb9c
 SHA512:
-  metadata.gz: b516708afcb021d131aac74c02b0dae2b97d04875f45ec408ff431a5046d2c12af0e824ddddbd5e9280c934ed2a016615cabb4e9d035174c2da99e4806afbc14
-  data.tar.gz: '09b94b37beba32a8956b06295ca7ad0b4f16b0de21e1148a127797f1fd61f0c7763dc85b336ee7a8e249dbd38f02e2e878aadb855dc6beb4404584a5ae6b89d4'
+  metadata.gz: 8ba3ea392a5a0f56cd7ab4f2c7a23271424149b9fcf8eaa0527b7002403069f9368f08729531b70f4e1c98390a261f544f61f540f95b1f65bfcb0e165ad5df1f
+  data.tar.gz: e0d0b0c6f19fd4c14b1ade31e6e23f31f80928e2faeeb34875fc65ad15e1784a6fe5830e59b958f8650b09cc64965f00235e5ea83f35407a828b00f7a93d3798

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, ActiveJob, and outbound `Net::HTTP` capture; standard-library 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.8"
+gem "logbrew-sdk", "~> 0.1.10"
 ```
 
 ```bash
@@ -53,7 +53,24 @@ 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.
+
+Outbound `Net::HTTP` calls made inside an active Rails request or job trace also
+need no initializer. They propagate one W3C child and record only method,
+normalized host, status, duration, adapter source, sampled state, and exception
+type. Calls outside an active trace remain exact pass-throughs.
+
+The explicit Rails capture settings are:
 
 | Environment variable | Default | Purpose |
 | --- | --- | --- |
@@ -415,7 +432,9 @@ end
 
 ## Outbound HTTP Tracing
 
-Wrap an app-owned `Net::HTTP` connection explicitly when outbound work should become a child of the active LogBrew trace:
+The enabled Rails integration captures `Net::HTTP` automatically while a
+LogBrew trace is active. Outside Rails, wrap an app-owned connection explicitly
+when outbound work should become a child of the active trace:
 
 ```ruby
 uri = URI("https://service.example/health")
@@ -440,7 +459,15 @@ connection = Faraday.new("https://service.example") do |builder|
 end
 ```
 
-Both adapters are literal pass-throughs when `LogBrew::Trace.current` is absent. With an active parent, they propagate one W3C `traceparent`, return the caller-visible header and trace scope to their prior values, and capture one completion span per actual execution. Duplicate wrappers, nested LogBrew HTTP middleware, and SDK delivery are suppressed without process-wide hooks. Net::HTTP start blocks, response streaming, Faraday middleware ordering, responses, and exceptions retain their normal behavior; telemetry capture failures are advisory.
+Both explicit adapters are literal pass-throughs when `LogBrew::Trace.current`
+is absent. With an active parent, explicit adapters and automatic Rails
+`Net::HTTP` capture propagate one W3C `traceparent`, return caller-visible
+header and trace state, and capture one completion span per actual execution.
+Duplicate wrappers, nested LogBrew HTTP middleware, and SDK delivery are
+suppressed. Outside an enabled Rails process, the SDK does not patch
+`Net::HTTP`. Start blocks, response streaming, Faraday middleware ordering,
+responses, and exceptions retain normal behavior; capture failures are
+advisory.
 
 Outbound HTTP spans allow only method, normalized host, status code, duration, adapter source, sampled state, and exception type. They never record scheme, port, path, query, fragment, full URL, request or response headers, bodies or sizes, exception messages or stacks, authentication material, cookies, baggage, tracestate, resolved addresses, or arbitrary request options.
 

data/lib/logbrew/http_client_tracing.rb

@@ -86,35 +86,12 @@ module LogBrew
     end
 
     def request(request, body = nil, &block)
-      prepared = HttpClientTracing.prepare(
+      HttpClientTracing.capture_net_http(
+        @http,
+        request,
         client: @client,
-        source: "net_http",
         on_capture_error: @on_capture_error
-      ) do
-        [request.method, address, HttpClientTracing::NetHttpHeaderSnapshot.new(request)]
-      end
-      return @http.request(request, body, &block) unless prepared
-
-      operation, header = prepared
-      begin
-        header.inject(operation.traceparent)
-      rescue StandardError => error
-        operation.capture_error(error)
-        HttpClientTracing.reset_header(header, operation)
-        return @http.request(request, body, &block)
-      end
-
-      response = nil
-      begin
-        response = operation.around { @http.request(request, body, &block) }
-      rescue StandardError => error
-        operation.finish(error: error)
-        raise
-      ensure
-        HttpClientTracing.reset_header(header, operation)
-      end
-      operation.finish(status_code: HttpClientTracing.read_status(response, :code, operation))
-      response
+      ) { @http.request(request, body, &block) }
     end
 
     def start(*arguments)
@@ -187,6 +164,34 @@ module LogBrew
       NetHttpTracingClient.new(http, client: client, on_capture_error: on_capture_error)
     end
 
+    def capture_net_http(http, request, client:, on_capture_error: nil)
+      prepared = prepare(client: client, source: "net_http", on_capture_error: on_capture_error) do
+        [request.method, http.address, NetHttpHeaderSnapshot.new(request)]
+      end
+      return yield unless prepared
+
+      operation, header = prepared
+      begin
+        header.inject(operation.traceparent)
+      rescue StandardError => error
+        operation.capture_error(error)
+        reset_header(header, operation)
+        return yield
+      end
+
+      response = nil
+      begin
+        response = operation.around { yield }
+      rescue StandardError => error
+        operation.finish(error: error)
+        raise
+      ensure
+        reset_header(header, operation)
+      end
+      operation.finish(status_code: read_status(response, :code, operation))
+      response
+    end
+
     def prepare(client:, source:, on_capture_error: nil)
       parent = Trace.current
       return nil unless parent

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
@@ -79,6 +77,10 @@ module LogBrew
       runtime = LogBrew::Rails.install(application: application)
       if runtime.configuration.enabled?
         LogBrew::Rails.const_get(:RequestOperations).install(::ActiveSupport::Notifications)
+        LogBrew::Rails.const_get(:OutboundHttp).install
+      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)

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,197 @@ module LogBrew
       end
     end
 
+    # Adds bounded child spans to Net::HTTP calls made inside an active Rails trace.
+    module OutboundHttp
+      module Request
+        def request(request, body = nil, &block)
+          runtime = LogBrew::Rails.runtime
+          client = LogBrew::Trace.current && runtime&.client
+          return super unless client
+
+          LogBrew::HttpClientTracing.capture_net_http(
+            self,
+            request,
+            client: client,
+            on_capture_error: ->(error) { runtime.report_error("outbound_http_capture", error) }
+          ) { super(request, body, &block) }
+        end
+      end
+
+      module_function
+
+      def install
+        Net::HTTP.prepend(Request) unless Net::HTTP.ancestors.include?(Request)
+      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/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 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