logbrew-sdk 0.1.11 → 0.1.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e4d8cebbc9fcb274134dda84b6de6b086a4dc6cdc119b80f02c3458624ca1587
-  data.tar.gz: c35a55684af97f05ef24f3626412f471c12af7cef0bcc7468430393dfbfccfdd
+  metadata.gz: 9f4065e8e726690a78d3b682ba49d4c35d931e4e81619ea2ff11a4170f4572cc
+  data.tar.gz: 29252ab423d8a184ed96724a76d57aafca1fd4008c383df86f44721eb6b511cf
 SHA512:
-  metadata.gz: e9f385c563b7de3bd38294d83e5aa9b3e72c57efb21cf6b22c59de8c5c0328d3a117dbbbee2bf42a91a36d98d97ece63afb2997661968a902f525c932351e5de
-  data.tar.gz: ae840cec0095218353192f4af76c00b4ec80707e4bc208c03ba6ae654e2c98158c2af8c198d68e1d279a84df944382e654312a599d7311cd8ad4a6eb519e8d8a
+  metadata.gz: 972aaa22ee930144da4508ce6a80e3e149a6b1cdad744178e3c5056349c43974b7681769d1b2338ce318547de5fefc6122d6c9066481858698e3d54a954603a4
+  data.tar.gz: 0c7acd8d564f9bda21ce4b44d541e6b4d3417eb3afd46adb57487ed6802a72953ecd19449a0c8f8546f01bc7315c63731e949e87376091737e89beb58d2b082a

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, error, ActiveJob, and outbound `Net::HTTP` capture; standard-library 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; trace-correlated Rails application logs by explicit opt-in; 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.11"
+gem "logbrew-sdk", "~> 0.1.13"
 ```
 
 ```bash
@@ -57,19 +57,29 @@ 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.
+queue wait. Enqueue spans use `queue.publish`; worker spans use `queue.process`.
+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.
 
+Set `LOGBREW_CAPTURE_RAILS_LOGS=true` to add application-owned `Rails.logger`
+messages to the active request or ActiveJob trace. The adapter keeps the app's
+configured logger, output, level, return value, and lazy block behavior intact.
+It captures only calls originating from files below `Rails.root`; framework,
+gem, startup, and out-of-trace logs remain local. Messages are limited to 2,048
+characters and include `messageState: captured` or `messageState: truncated`.
+Log messages are application-provided telemetry and can contain sensitive
+values, so enable this only after the application applies its normal filtering.
+
 The explicit Rails capture settings are:
 
 | Environment variable | Default | Purpose |
@@ -84,6 +94,7 @@ The explicit Rails capture settings are:
 | `LOGBREW_FLUSH_INTERVAL_MS` | `5000` | Automatic delivery interval from 10 to 3600000 ms |
 | `LOGBREW_FLUSH_THRESHOLD` | `100` | Queue size from 1 to 1000 that requests an earlier flush |
 | `LOGBREW_CAPTURE_EXCEPTION_MESSAGES` | `false` | Opt in to exception message capture |
+| `LOGBREW_CAPTURE_RAILS_LOGS` | `false` | Opt in to bounded application-origin logs on active request and job traces |
 | `LOGBREW_INCLUDE_EXCEPTION_BACKTRACE` | `false` | Opt in to raw exception backtrace text; sanitized structured frames are always captured |
 
 `LOGBREW_API_KEY` and `LOGBREW_INGEST_KEY` are not Rails aliases. If either is
@@ -735,7 +746,14 @@ Registration is app-owned, idempotent, and reversible with `unregister_client` a
 
 The client middleware adds one bounded `logbrew` carrier containing only a version, W3C `traceparent`, and enqueue time. Valid retries keep that carrier without creating another enqueue span. The server middleware continues a valid carrier or starts a fresh trace when it is absent or malformed, returns the caller trace state after every result, and records bounded queue-wait and execution timing. Set `max_retries` to the same default retry limit used by your Sidekiq configuration; per-job integer or disabled retry settings are honored. Retryable failures keep only error spans, while the terminal escaped failure adds one deduplicated fixed-title issue and preserves the original exception.
 
-Sidekiq spans contain only fixed source, sampled state, bounded retry count, bounded queue-wait duration, execution duration, status, and real cancellation. The integration does not capture job arguments, payload fields, job identifiers, worker names, queue values, connection data, exception messages or stacks, baggage, or tracestate. Capture failures are advisory and never replace job execution or retry behavior. Create fresh clients and instrumentation after `fork`; inherited instances fail closed without changing jobs.
+Sidekiq producer spans use `queue.publish`, and worker spans use `queue.process`.
+They contain only fixed source, sampled state, bounded retry count, bounded
+queue-wait duration, execution duration, status, and real cancellation. The
+integration does not capture job arguments, payload fields, job identifiers,
+worker names, queue values, connection data, exception messages or stacks,
+baggage, or tracestate. Capture failures are advisory and never replace job
+execution or retry behavior. Create fresh clients and instrumentation after
+`fork`; inherited instances fail closed without changing jobs.
 
 ## Persistent Worker Delivery
 

data/lib/logbrew/operation_tracing.rb

@@ -6,7 +6,11 @@ module LogBrew
     UNSAFE_METADATA = /authorization|body|broker|cache.?key|command|connection|cookie|dsn|header|host|
       \bjid\z|job.?id|key|message|param|pass#{'word'}|payload|query|sec#{'ret'}|sql|statement|
       to#{'ken'}|url|username|value/ix
-    private_constant :UNSAFE_METADATA
+    QUEUE_SEMANTICS = {
+      "enqueue" => "queue.publish", "publish" => "queue.publish", "send" => "queue.publish",
+      "receive" => "queue.receive", "perform" => "queue.process", "process" => "queue.process", "consume" => "queue.process"
+    }.freeze
+    private_constant :UNSAFE_METADATA, :QUEUE_SEMANTICS
 
     module_function
 
@@ -28,20 +32,13 @@ module LogBrew
       Validation.require_non_empty("#{kind} operation name", name)
       started_at = monotonic_time
       context = child_context
-      error = nil
-      result = nil
-
-      Trace.with_context(context) do
-        begin
-          result = yield context
-        rescue StandardError => captured
-          error = captured
-        end
+      begin
+        result = Trace.with_context(context) { yield context }
+      rescue StandardError => error
+        capture_span(client, kind, name, context, started_at, options, error)
+        raise
       end
-
-      capture_span(client, kind, name, context, started_at, options, error)
-      raise error if error
-
+      capture_span(client, kind, name, context, started_at, options, nil)
       result
     end
 
@@ -88,6 +85,7 @@ module LogBrew
         metadata["source"] = read_option(options, :source) || "#{kind}.operation"
         add_option(metadata, "#{kind}.system", read_option(options, :system))
         add_option(metadata, "#{kind}.operation", read_option(options, :operation))
+        add_option(metadata, "operation", QUEUE_SEMANTICS[read_option(options, :operation)]) if kind == "queue"
         add_option(metadata, "#{kind}.target", read_option(options, :target))
         metadata["exceptionType"] = error.class.name if error
       end

data/lib/logbrew/rails.rb

@@ -98,6 +98,7 @@ module LogBrew
       runtime = LogBrew::Rails.runtime
       next if runtime.nil? || !runtime.configuration.enabled?
 
+      LogBrew::Rails.const_get(:ApplicationLogCapture).install(::Rails.logger, runtime, application_root: ::Rails.root)
       reporter = LogBrew::Rails::ErrorReporter.new(runtime)
       if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
         ::Rails.error.subscribe(reporter)

data/lib/logbrew/rails_integration.rb

@@ -18,17 +18,13 @@ module LogBrew
       MAX_ENDPOINT_BYTES = 2_048
       LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
 
-      attr_reader(
-        :api_key,
-        :service_name,
-        :app_environment,
-        :rails_version,
-        :release,
-        :endpoint,
-        :request_timeout,
-        :flush_interval,
-        :flush_threshold
-      )
+      ATTRIBUTES = %i[
+        enabled api_key service_name app_environment rails_version release endpoint
+        request_timeout flush_interval flush_threshold capture_exception_messages
+        capture_rails_logs include_exception_backtrace
+      ].freeze
+      private_constant :ATTRIBUTES
+      attr_reader(*ATTRIBUTES.drop(1).reject { |name| name.to_s.start_with?("capture_", "include_") })
 
       def self.from_environment(environment, application_name:, rails_environment:, rails_version:)
         unless environment.respond_to?(:[]) && environment.respond_to?(:key?)
@@ -92,6 +88,7 @@ module LogBrew
             "LOGBREW_CAPTURE_EXCEPTION_MESSAGES",
             false
           ),
+          capture_rails_logs: boolean_value(environment, "LOGBREW_CAPTURE_RAILS_LOGS", false),
           include_exception_backtrace: boolean_value(
             environment,
             "LOGBREW_INCLUDE_EXCEPTION_BACKTRACE",
@@ -113,6 +110,7 @@ module LogBrew
           flush_interval: DEFAULT_FLUSH_INTERVAL_MS / 1_000.0,
           flush_threshold: DEFAULT_FLUSH_THRESHOLD,
           capture_exception_messages: false,
+          capture_rails_logs: false,
           include_exception_backtrace: false
         )
       end
@@ -203,32 +201,11 @@ module LogBrew
       private_class_method :optional_text, :server_key_value, :bounded_label,
                            :optional_bounded_label, :boolean_value, :integer_value, :endpoint_value
 
-      def initialize(
-        enabled:,
-        api_key:,
-        service_name:,
-        app_environment:,
-        rails_version:,
-        release:,
-        endpoint:,
-        request_timeout:,
-        flush_interval:,
-        flush_threshold:,
-        capture_exception_messages:,
-        include_exception_backtrace:
-      )
-        @enabled = enabled
-        @api_key = api_key&.dup&.freeze
-        @service_name = service_name
-        @app_environment = app_environment
-        @rails_version = rails_version
-        @release = release
-        @endpoint = endpoint
-        @request_timeout = request_timeout
-        @flush_interval = flush_interval
-        @flush_threshold = flush_threshold
-        @capture_exception_messages = capture_exception_messages
-        @include_exception_backtrace = include_exception_backtrace
+      def initialize(**attributes)
+        raise ArgumentError, "Rails configuration attributes do not match" unless attributes.keys.sort == ATTRIBUTES.sort
+
+        ATTRIBUTES.each { |name| instance_variable_set("@#{name}", attributes.fetch(name)) }
+        @api_key = @api_key&.dup&.freeze
         freeze
       end
 
@@ -240,6 +217,10 @@ module LogBrew
         @capture_exception_messages
       end
 
+      def capture_rails_logs?
+        @capture_rails_logs
+      end
+
       def include_exception_backtrace?
         @include_exception_backtrace
       end
@@ -398,6 +379,145 @@ module LogBrew
       end
     end
 
+    # Adds one bounded, trace-aware LogBrew sink without replacing the app logger.
+    module ApplicationLogCapture
+      MAX_MESSAGE_CHARACTERS = 2_048
+      SINK_IVAR = :@logbrew_rails_log_sink
+      ROOT_IVAR = :@logbrew_rails_application_root
+      GUARD_KEY = :logbrew_rails_log_capture
+      ORIGIN_KEY = :logbrew_rails_log_origin
+      LIBRARY_ROOT = File.expand_path("..", __dir__)
+      LOGGER_PATH = ::Logger.instance_method(:add).source_location&.first
+      LOGGER_WRAPPER_PATH = %r{/active_support/(?:broadcast_logger|tagged_logging|logger(?:_silence|_thread_safe_level)?)\.rb\z}
+      GEM_ROOTS = (defined?(::Gem) ? ::Gem.path : []).map { |root| "#{File.expand_path(root)}#{File::SEPARATOR}" }.freeze
+      LEVELS = LogBrew::Logger::SEVERITY_TO_LOGBREW_LEVEL
+      private_constant :MAX_MESSAGE_CHARACTERS, :SINK_IVAR, :ROOT_IVAR, :GUARD_KEY, :ORIGIN_KEY,
+                       :LIBRARY_ROOT, :LOGGER_PATH, :LOGGER_WRAPPER_PATH, :GEM_ROOTS, :LEVELS
+
+      class Sink < ::Logger
+        def initialize(runtime, application_root, level)
+          @runtime = runtime
+          @application_root = File.expand_path(application_root.to_s)
+          super(File::NULL)
+          self.level = level
+        end
+
+        def add(severity, message = nil, progname = nil)
+          severity ||= ::Logger::UNKNOWN
+          return true if severity < level
+
+          resolved = message.nil? ? (block_given? ? yield : progname) : message
+          ApplicationLogCapture.capture(@runtime, @application_root, severity, resolved)
+          true
+        end
+      end
+      private_constant :Sink
+
+      module LoggerTap
+        def add(severity, message = nil, progname = nil, &block)
+          severity ||= ::Logger::UNKNOWN
+          configured_progname = respond_to?(:progname) ? self.progname : nil
+          captured = message.nil? && block.nil? ? (progname || configured_progname) : message
+          wrapped = block && proc { captured = block.call }
+          result = super(severity, message, progname, &wrapped)
+          sink = instance_variable_get(SINK_IVAR)
+          if sink && severity >= level
+            sink.level = level
+            sink.add(severity, captured)
+          end
+          result
+        end
+      end
+      private_constant :LoggerTap
+
+      module BroadcastOrigin
+        def dispatch(*args, &block)
+          previous = Thread.current[ORIGIN_KEY]
+          origin = ApplicationLogCapture.application_caller?(instance_variable_get(ROOT_IVAR))
+          Thread.current[ORIGIN_KEY] = origin
+          super(*args, &block)
+        ensure
+          Thread.current[ORIGIN_KEY] = previous
+        end
+        private :dispatch
+      end
+      private_constant :BroadcastOrigin
+
+      module_function
+
+      def install(logger, runtime, application_root: nil)
+        return logger unless runtime.configuration.capture_rails_logs?
+        return logger if application_root.nil?
+        return logger unless logger.respond_to?(:add) || logger.respond_to?(:broadcast_to)
+        return logger unless logger.instance_variable_get(SINK_IVAR).nil?
+
+        level = logger.respond_to?(:level) ? logger.level : ::Logger::DEBUG
+        root = File.expand_path(application_root.to_s)
+        sink = Sink.new(runtime, root, level)
+        if logger.respond_to?(:broadcast_to)
+          logger.instance_variable_set(ROOT_IVAR, root)
+          logger.singleton_class.prepend(BroadcastOrigin)
+          logger.broadcast_to(sink)
+        else
+          logger.singleton_class.prepend(LoggerTap)
+        end
+        logger.instance_variable_set(SINK_IVAR, sink)
+        logger
+      rescue StandardError => error
+        runtime.report_error("application_log_installation", error)
+        logger
+      end
+
+      def capture(runtime, application_root, severity, message)
+        return if LogBrew::Trace.current.nil? || Thread.current[GUARD_KEY]
+        origin = Thread.current[ORIGIN_KEY]
+        origin = application_caller?(application_root) if origin.nil?
+        return unless origin
+
+        Thread.current[GUARD_KEY] = true
+        begin
+          client = runtime.client
+          return if client.nil?
+
+          text = message.is_a?(String) ? message : message.inspect
+          truncated = text.length > MAX_MESSAGE_CHARACTERS
+          metadata = runtime.metadata.merge(
+            "source" => "rails.logger",
+            "rubySeverity" => ::Logger::SEV_LABEL[severity.to_i] || "ANY",
+            "messageState" => truncated ? "truncated" : "captured"
+          )
+          client.log(
+            "ruby_rails_log_#{SecureRandom.hex(8)}",
+            Time.now.utc.iso8601(6),
+            message: text[0, MAX_MESSAGE_CHARACTERS],
+            level: LEVELS.fetch(severity.to_i, severity.to_i >= ::Logger::FATAL ? "critical" : "info"),
+            logger: "rails",
+            metadata: metadata
+          )
+        rescue StandardError => error
+          runtime.report_error("application_log_capture", error)
+        ensure
+          Thread.current[GUARD_KEY] = false
+        end
+      end
+
+      def application_caller?(application_root)
+        location = caller_locations(2, 24).find do |caller|
+          path = caller.absolute_path || caller.path
+          path && !path.start_with?(LIBRARY_ROOT) && path != LOGGER_PATH && !path.match?(LOGGER_WRAPPER_PATH)
+        end
+        return false if location.nil?
+
+        path = File.expand_path(location.absolute_path || location.path)
+        return false if GEM_ROOTS.any? { |root| path.start_with?(root) }
+
+        path == application_root || path.start_with?("#{application_root}#{File::SEPARATOR}")
+      rescue StandardError
+        false
+      end
+    end
+    private_constant :ApplicationLogCapture
+
     # Adds bounded child spans to Net::HTTP calls made inside an active Rails trace.
     module OutboundHttp
       module Request

data/lib/logbrew/sidekiq.rb

@@ -28,15 +28,12 @@ module LogBrew
 
       def around(terminal_failure: false)
         Trace.with_context(@context) do
-          begin
-            result = yield
-          rescue Exception => error # rubocop:disable Lint/RescueException
-            finish(error: error, terminal_failure: terminal_failure)
-            raise
-          else
-            finish
-            result
-          end
+          result = yield
+          finish
+          result
+        rescue Exception => error # rubocop:disable Lint/RescueException
+          finish(error: error, terminal_failure: terminal_failure)
+          raise
         end
       end
 
@@ -64,6 +61,7 @@ module LogBrew
       def span_attributes(error)
         metadata = {
           "source" => @source,
+          "operation" => @source == "sidekiq.client" ? "queue.publish" : "queue.process",
           "sampled" => @context.sampled
         }
         metadata["retryCount"] = @retry_count unless @retry_count.nil?

data/lib/logbrew/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.11
+  version: 0.1.13
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-09-02 00:00:00.000000000 Z
 dependencies: []
 description: Public LogBrew Ruby SDK with typed issue diagnostics, automatic Rails
   request/error capture, and standard-library delivery.