logbrew-sdk 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d461f01e0341b81cbdd17c4903f50726cd7966f26e50d7fd6fbef97a8fbf83dc
-  data.tar.gz: 42efb0bf7c1312d5c0bb3337885b00de0921e043952e8c57d6571391110e2c7d
+  metadata.gz: 4e89660190354962ae56323ce67dd3192d2b6ac7fc52f73fefe8cca3e4cffe31
+  data.tar.gz: d92f16257ab1911e72f025f0b1fa29a85138e522653a68fdd4466e8f5c0311c7
 SHA512:
-  metadata.gz: d7f55a9b0a8f8813762a2f497382a78c6678d22972ffe8bd0512359c53a8927491ea4fd7fc5bc92b40aaefab156cd8a57e27a090eedbd012c4b786360d1c6514
-  data.tar.gz: bc21387db2691a355300645a333d4f57f878815415e6b52d1d56d7f38a5bca6be4eb27a4e205ba65ce777d9d05b04e018feeacb752a0ba5df7db5f1ecc83fab4
+  metadata.gz: 83d428f770034749b2c6717eb7fae953a21671bd050406822f341e7f06494af15849d1ac58b259ab08c2910f161e7bf8321fa3b3b6867b8bb14b048883b0a684
+  data.tar.gz: b60cd4f0f853c45fd656d16605b23bafa4fd2396f56be9c2be7ba8da3aa358a33510082f0ca49a45222690caea01bc1b5c3997ab30819ada8a8bde311963a617

data/README.md

@@ -23,7 +23,7 @@ needed:
 
 ```ruby
 # Gemfile
-gem "logbrew-sdk", "~> 0.1.4"
+gem "logbrew-sdk", "~> 0.1.6"
 ```
 
 ```bash
@@ -479,8 +479,11 @@ rescue RuntimeError => error
 end
 ```
 
-The typed payload exposes exception type, mechanism and handled state, up to 32
-newest-first stack frames, and up to 64 oldest-to-newest breadcrumbs. Generated
+The typed payload exposes exception type, mechanism and handled state, a
+bounded parent-first Ruby `cause` chain, up to 32 newest-first stack frames,
+and up to 64 oldest-to-newest breadcrumbs. Automatic node messages are marked
+redacted, per-node stack availability is explicit, and cycles, unsafe cause
+access, or the eight-node cap mark truncation. Generated
 frames contain only basename, positive coordinates, and bounded function
 identity. Explicit frames can also carry module, `inApp`, and debug ID. A
 breadcrumb accepts a stable category/type, normalized level, bounded message,
@@ -494,6 +497,8 @@ and manual structured frame projection never captures raw backtrace strings,
 source code, locals, arguments, or absolute paths. The raw Rails/Rack backtrace
 option is separate and remains off by default. Run
 `make -C examples run-issue-diagnostics` for a complete inspectable payload.
+Rails, Rack, and Sidekiq issue capture reuse this same graph. See the shared
+[exception-chain contract](../../docs/exception-chain-evidence.md).
 
 ## Metrics
 

data/lib/logbrew/issue_diagnostics.rb

@@ -11,7 +11,10 @@ module LogBrew
   module IssueDiagnostics
     MAX_STACK_FRAMES = 32
     MAX_BREADCRUMBS = 64
+    MAX_EXCEPTIONS = 8
     MAX_EXCEPTION_TYPE = 256
+    MAX_EXCEPTION_MESSAGE = 1_024
+    MAX_EXCEPTION_MODULE = 512
     MAX_MECHANISM_TYPE = 64
     MAX_FRAME_FILENAME = 2_048
     MAX_FRAME_FUNCTION = 256
@@ -71,10 +74,17 @@ module LogBrew
         )
       }
       attributes["message"] = message unless message.nil?
+      root_stack = include_stack_frames ? stack_evidence_from_exception(error) : nil
       if include_stack_frames
-        frames = stack_frames_from_exception(error)
+        frames = root_stack.fetch(:frames)
         attributes["stackFrames"] = frames unless frames.empty?
       end
+      attributes["exceptionChain"] = exception_chain_from_exception(
+        error,
+        root_exception: attributes.fetch("exception"),
+        root_stack: root_stack,
+        include_stack_frames: include_stack_frames
+      )
       attributes["breadcrumbs"] = breadcrumbs unless breadcrumbs.nil?
       attributes["breadcrumbsTruncated"] = true if breadcrumbs_truncated
       attributes["metadata"] = metadata unless metadata.nil?
@@ -180,6 +190,13 @@ module LogBrew
         payload["message"] = message.dup
       end
       payload["exception"] = validate_exception(read_value(attributes, "exception")) if has_key?(attributes, "exception")
+      if has_key?(attributes, "exceptionChain")
+        payload["exceptionChain"] = validate_exception_chain(
+          read_value(attributes, "exceptionChain"),
+          payload["exception"],
+          has_key?(attributes, "stackFrames") ? validate_stack_frames(read_value(attributes, "stackFrames")) : nil
+        )
+      end
       payload["stackFrames"] = validate_stack_frames(read_value(attributes, "stackFrames")) if has_key?(attributes, "stackFrames")
       payload["breadcrumbs"] = validate_breadcrumbs(read_value(attributes, "breadcrumbs")) if has_key?(attributes, "breadcrumbs")
       if has_key?(attributes, "breadcrumbsTruncated")
@@ -230,6 +247,110 @@ module LogBrew
       value
     end
 
+    def validate_exception_chain(input, legacy_exception, legacy_frames)
+      unless input.is_a?(Hash)
+        raise validation("issue exceptionChain must be an object")
+      end
+      reject_unknown_keys(input, %w[entries truncated], "issue exceptionChain")
+      entries_input = read_required(input, "entries", "issue exceptionChain entries")
+      unless entries_input.is_a?(Array) && entries_input.length.between?(1, MAX_EXCEPTIONS)
+        raise validation("issue exceptionChain entries must contain 1-8 exceptions")
+      end
+      truncated = read_required(input, "truncated", "issue exceptionChain truncated")
+      unless truncated == true || truncated == false
+        raise validation("issue exceptionChain truncated must be a boolean")
+      end
+
+      entries = entries_input.each_with_index.map do |entry_input, index|
+        validate_exception_chain_entry(entry_input, index)
+      end
+      root = entries.fetch(0)
+      root_exception = { "type" => root.fetch("type") }
+      root_exception["mechanism"] = root.fetch("mechanism") if root.key?("mechanism")
+      unless legacy_exception.is_a?(Hash) && root_exception == legacy_exception
+        raise validation("issue exceptionChain reported exception must match exception")
+      end
+      if root.fetch("stackFramesState") == "not_captured"
+        unless legacy_frames.nil?
+          raise validation("issue exceptionChain reported stack must match stackFrames")
+        end
+      elsif root["stackFrames"] != legacy_frames
+        raise validation("issue exceptionChain reported stack must match stackFrames")
+      end
+      { "entries" => entries, "truncated" => truncated }
+    end
+
+    def validate_exception_chain_entry(input, index)
+      unless input.is_a?(Hash)
+        raise validation("issue exceptionChain entry #{index} must be an object")
+      end
+      reject_unknown_keys(
+        input,
+        %w[id parentId relationship type message messageState module mechanism stackFrames stackFramesState],
+        "issue exceptionChain entry #{index}"
+      )
+      unless read_required(input, "id", "issue exceptionChain entry id") == index
+        raise validation("issue exceptionChain ids must be contiguous and match array order")
+      end
+      relationship = read_required(input, "relationship", "issue exceptionChain relationship")
+      if index.zero?
+        unless relationship == "reported" && !has_key?(input, "parentId")
+          raise validation("issue exceptionChain entry 0 must be the parentless reported exception")
+        end
+      else
+        parent_id = read_value(input, "parentId")
+        unless %w[cause context aggregate_member suppressed].include?(relationship) &&
+               parent_id.is_a?(Integer) && parent_id.between?(0, index - 1)
+          raise validation("issue exceptionChain parent relationship is invalid")
+        end
+      end
+
+      value = {
+        "id" => index,
+        "relationship" => relationship,
+        "type" => require_text(
+          "issue exceptionChain type",
+          read_required(input, "type", "issue exceptionChain type"),
+          MAX_EXCEPTION_TYPE,
+          true
+        )
+      }
+      value["parentId"] = read_value(input, "parentId") unless index.zero?
+      message_state = read_required(input, "messageState", "issue exceptionChain messageState")
+      if %w[captured truncated].include?(message_state)
+        value["message"] = require_text(
+          "issue exceptionChain message",
+          read_required(input, "message", "issue exceptionChain message"),
+          MAX_EXCEPTION_MESSAGE,
+          false
+        )
+      elsif !%w[redacted not_captured].include?(message_state) || has_key?(input, "message")
+        raise validation("issue exceptionChain message must match messageState")
+      end
+      value["messageState"] = message_state
+      if has_key?(input, "module")
+        value["module"] = require_text(
+          "issue exceptionChain module",
+          read_value(input, "module"),
+          MAX_EXCEPTION_MODULE,
+          true
+        )
+      end
+      value["mechanism"] = validate_exception_mechanism(read_value(input, "mechanism")) if has_key?(input, "mechanism")
+      stack_state = read_required(input, "stackFramesState", "issue exceptionChain stackFramesState")
+      if %w[captured truncated].include?(stack_state)
+        value["stackFrames"] = validate_stack_frames(read_required(input, "stackFrames", "issue exceptionChain stackFrames"))
+      elsif stack_state != "not_captured" || has_key?(input, "stackFrames")
+        raise validation("issue exceptionChain stackFrames must match stackFramesState")
+      end
+      value["stackFramesState"] = stack_state
+      value
+    end
+
+    def validate_exception_mechanism(mechanism)
+      validate_exception({ "type" => "Exception", "mechanism" => mechanism }).fetch("mechanism")
+    end
+
     def validate_stack_frames(input)
       unless input.is_a?(Array) && input.length.between?(1, MAX_STACK_FRAMES)
         raise validation("issue stackFrames must contain 1-32 frames")
@@ -380,16 +501,98 @@ module LogBrew
       "Exception"
     end
 
+    def exception_chain_from_exception(error, root_exception:, root_stack:, include_stack_frames:)
+      entries = []
+      seen = {}
+      current = error
+      parent_id = nil
+      truncated = false
+
+      until current.nil?
+        if seen.key?(current.object_id) || entries.length >= MAX_EXCEPTIONS
+          truncated = true
+          break
+        end
+        seen[current.object_id] = true
+        id = entries.length
+        stack = id.zero? ? root_stack : (include_stack_frames ? stack_evidence_from_exception(current) : nil)
+        entry = {
+          "id" => id,
+          "relationship" => id.zero? ? "reported" : "cause",
+          "type" => safe_exception_type(current),
+          "messageState" => safe_exception_has_message?(current) ? "redacted" : "not_captured",
+          "mechanism" => id.zero? ? root_exception["mechanism"] : { "type" => "ruby.cause", "handled" => true },
+          "stackFramesState" => if stack.nil? || stack.fetch(:frames).empty?
+                                  "not_captured"
+                                elsif stack.fetch(:truncated)
+                                  "truncated"
+                                else
+                                  "captured"
+                                end
+        }
+        entry["parentId"] = parent_id unless parent_id.nil?
+        exception_module = safe_exception_module(current)
+        entry["module"] = exception_module unless exception_module.nil?
+        entry["stackFrames"] = stack.fetch(:frames) unless stack.nil? || stack.fetch(:frames).empty?
+        entries << entry
+        parent_id = id
+        current = safe_exception_cause(current)
+      end
+
+      root_frames = root_stack&.fetch(:frames)
+      root_frames = nil if root_frames&.empty?
+      validate_exception_chain(
+        { "entries" => entries, "truncated" => truncated },
+        root_exception,
+        root_frames
+      )
+    end
+
+    def stack_evidence_from_exception(error)
+      locations = safe_backtrace_locations(error)
+      frames = locations.first(MAX_STACK_FRAMES).map { |location| frame_from_location(location) }.compact
+      return { frames: frames, truncated: locations.length > MAX_STACK_FRAMES } unless frames.empty?
+
+      lines = safe_backtrace(error)
+      {
+        frames: lines.first(MAX_STACK_FRAMES).map { |line| frame_from_backtrace_line(line) }.compact,
+        truncated: lines.length > MAX_STACK_FRAMES
+      }
+    end
+
+    def safe_exception_has_message?(error)
+      message = error.message
+      message.is_a?(String) && !message.strip.empty?
+    rescue StandardError
+      false
+    end
+
+    def safe_exception_module(error)
+      name = error.class.name
+      return nil unless name.is_a?(String) && name.include?("::")
+
+      safe_generated_text(name.split("::")[0...-1].join("::"), MAX_EXCEPTION_MODULE, true, nil)
+    rescue StandardError
+      nil
+    end
+
+    def safe_exception_cause(error)
+      cause = error.cause
+      cause.is_a?(Exception) ? cause : nil
+    rescue StandardError
+      nil
+    end
+
     def safe_backtrace_locations(error)
       locations = error.backtrace_locations
-      locations.respond_to?(:first) ? locations.first(MAX_STACK_FRAMES) : []
+      locations.respond_to?(:first) ? locations.first(MAX_STACK_FRAMES + 1) : []
     rescue StandardError
       []
     end
 
     def safe_backtrace(error)
       backtrace = error.backtrace
-      backtrace.is_a?(Array) ? backtrace.first(MAX_STACK_FRAMES) : []
+      backtrace.is_a?(Array) ? backtrace.first(MAX_STACK_FRAMES + 1) : []
     rescue StandardError
       []
     end
@@ -545,6 +748,9 @@ module LogBrew
 
     private_class_method(
       :validate_exception,
+      :validate_exception_chain,
+      :validate_exception_chain_entry,
+      :validate_exception_mechanism,
       :validate_stack_frames,
       :validate_stack_frame,
       :validate_breadcrumbs,
@@ -553,6 +759,11 @@ module LogBrew
       :validate_breadcrumb_data_value,
       :safe_backtrace_locations,
       :safe_backtrace,
+      :exception_chain_from_exception,
+      :stack_evidence_from_exception,
+      :safe_exception_has_message?,
+      :safe_exception_module,
+      :safe_exception_cause,
       :frame_from_location,
       :frame_from_backtrace_line,
       :safe_location_value,

data/lib/logbrew/rails_integration.rb

@@ -419,6 +419,15 @@ module LogBrew
         "rails-exception"
       end
 
+      def exception_status_code(error)
+        return super unless defined?(::ActionDispatch::ExceptionWrapper)
+
+        status = ::ActionDispatch::ExceptionWrapper.status_code_for_exception(error.class.name)
+        status.is_a?(Integer) && status.between?(400, 599) ? status : super
+      rescue StandardError
+        super
+      end
+
       def request_name(env)
         "#{request_method(env)} #{route_template(env)}"
       end
@@ -438,9 +447,7 @@ module LogBrew
         metadata.delete("action_dispatch.request_id")
         metadata.delete("HTTP_X_REQUEST_ID")
         metadata["source"] = "rails"
-        metadata["http.method"] = request_method(env)
         metadata["http.route"] = route_template(env)
-        metadata["http.status_code"] = status_code
         metadata["http.status_class"] = "#{status_code.to_i / 100}xx"
         controller, action = controller_and_action(env)
         metadata["rails.controller"] = controller unless controller.nil?
@@ -449,10 +456,8 @@ module LogBrew
       end
 
       def route_template(env)
-        route = bounded_route(env_value(env, "action_dispatch.route_uri_pattern"))
-        return route unless route.nil?
-
-        route = bounded_route(matched_route_pattern(env))
+        route = bounded_route(env_value(env, "action_dispatch.route_uri_pattern")) ||
+                bounded_route(matched_route_pattern(env))
         return route unless route.nil?
 
         controller, action = controller_and_action(env)

data/lib/logbrew/version.rb

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

data/lib/logbrew.rb

@@ -406,10 +406,10 @@ module LogBrew
       begin
         response = @app.call(env)
       rescue StandardError => error
+        status_code = exception_status_code(error)
         safely_capture do
-          elapsed_ms = duration_ms(started_at)
-          capture_exception_issue(env, error)
-          capture_request_span(env, 500, elapsed_ms, "error")
+          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
         raise
@@ -425,6 +425,10 @@ module LogBrew
 
     private
 
+    def exception_status_code(_error)
+      500
+    end
+
     def capture_request_span(env, status_code, elapsed_ms, status)
       @client.span(
         next_event_id("span"),

metadata

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