logbrew-sdk 0.1.3 → 0.1.4

data/lib/logbrew.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "logger"
 require "net/http"
@@ -41,6 +42,11 @@ module LogBrew
     end
   end
 
+  require_relative "logbrew/telemetry_context_value"
+  require_relative "logbrew/telemetry_resource"
+  require_relative "logbrew/telemetry_context"
+  require_relative "logbrew/telemetry"
+
   require_relative "logbrew/event_batcher"
   require_relative "logbrew/persistent_event_store"
   require_relative "logbrew/bounded_event_queue"
@@ -433,12 +439,13 @@ module LogBrew
     end
 
     def capture_exception_issue(env, error)
-      attributes = {
-        title: error.class.name,
-        level: "error",
+      attributes = IssueDiagnostics.from_exception(
+        error,
+        message: @include_exception_message ? error.message : nil,
+        mechanism_type: exception_mechanism_type,
+        handled: false,
         metadata: exception_metadata(env, error)
-      }
-      attributes[:message] = error.message if @include_exception_message
+      )
       @client.issue(next_event_id("issue"), logbrew_timestamp, attributes)
     end
 
@@ -497,12 +504,39 @@ module LogBrew
 
     def exception_metadata(env, error)
       request_metadata(env, 500).tap do |metadata|
-        metadata["exceptionType"] = error.class.name
+        exception_type = IssueDiagnostics.safe_exception_type(error)
+        frames = IssueDiagnostics.stack_frames_from_exception(error)
+        first_frame = frames.first
+        metadata["exceptionType"] = exception_type
+        metadata["errorName"] = exception_type
+        metadata["handled"] = false
+        metadata["mechanism"] = exception_mechanism_type
+        metadata["issueGroupingKey"] = exception_grouping_key(env, exception_type, first_frame)
+        metadata["issueGroupingSource"] = "exception_type_route_file"
+        unless first_frame.nil?
+          metadata["errorFrameFile"] = first_frame.fetch("filename")
+          metadata["errorFrameLine"] = first_frame.fetch("line")
+        end
         metadata["exceptionMessage"] = error.message if @include_exception_message
         metadata["exceptionBacktrace"] = error.backtrace.join("\n") if @include_exception_backtrace && error.backtrace
       end
     end
 
+    def exception_mechanism_type
+      "rack.middleware"
+    end
+
+    def exception_grouping_prefix
+      "rack-exception"
+    end
+
+    def exception_grouping_key(env, exception_type, first_frame)
+      route = request_path(env)
+      frame_file = first_frame.nil? ? "" : first_frame.fetch("filename")
+      material = [exception_type, route, frame_file].join("\n")
+      "#{exception_grouping_prefix}-#{Digest::SHA256.hexdigest(material)}"
+    end
+
     def rack_status(response)
       return response[0].to_i if response.respond_to?(:[]) && !response[0].nil?
 
@@ -603,12 +637,25 @@ module LogBrew
 
     def report(error, handled: true, severity: :error, context: nil, source: nil, **_options)
       capture_safely do
-        attributes = {
-          title: error_title(error),
-          level: issue_level(severity),
-          metadata: rails_metadata(error, handled, severity, context, source)
-        }
-        attributes[:message] = error_message(error) if @include_exception_message
+        attributes = if error.is_a?(Exception)
+                       IssueDiagnostics.from_exception(
+                         error,
+                         title: error_title(error),
+                         level: issue_level(severity),
+                         message: @include_exception_message ? error_message(error) : nil,
+                         mechanism_type: "rails.error_reporter",
+                         handled: handled,
+                         metadata: rails_metadata(error, handled, severity, context, source)
+                       )
+                     else
+                       {
+                         title: error_title(error),
+                         level: issue_level(severity),
+                         metadata: rails_metadata(error, handled, severity, context, source)
+                       }.tap do |fallback|
+                         fallback[:message] = error_message(error) if @include_exception_message
+                       end
+                     end
         @client.issue(next_event_id, logbrew_timestamp, attributes)
         flush_if_configured
       end
@@ -668,11 +715,30 @@ module LogBrew
     end
 
     def add_exception_metadata(metadata, exception)
-      metadata["exceptionType"] = exception.class.name
+      exception_type = IssueDiagnostics.safe_exception_type(exception)
+      frames = IssueDiagnostics.stack_frames_from_exception(exception)
+      first_frame = frames.first
+      metadata["exceptionType"] = exception_type
+      metadata["errorName"] = exception_type
+      metadata["handled"] = metadata.fetch("rails.handled")
+      metadata["mechanism"] = "rails.error_reporter"
+      metadata["issueGroupingKey"] = rails_error_grouping_key(exception_type, metadata, first_frame)
+      metadata["issueGroupingSource"] = "exception_type_source_file"
+      unless first_frame.nil?
+        metadata["errorFrameFile"] = first_frame.fetch("filename")
+        metadata["errorFrameLine"] = first_frame.fetch("line")
+      end
       metadata["exceptionMessage"] = exception.message if @include_exception_message
       metadata["exceptionBacktrace"] = exception.backtrace.join("\n") if @include_exception_backtrace && exception.backtrace
     end
 
+    def rails_error_grouping_key(exception_type, metadata, first_frame)
+      source = metadata.fetch("rails.source", "rails")
+      frame_file = first_frame.nil? ? "" : first_frame.fetch("filename")
+      material = [exception_type, source, frame_file].join("\n")
+      "rails-exception-#{Digest::SHA256.hexdigest(material)}"
+    end
+
     def copy_metadata(metadata)
       metadata.each_with_object({}) do |(key, value), copied|
         copied[key.to_s] = value if primitive_metadata_value?(value)
@@ -759,6 +825,26 @@ module LogBrew
       value
     end
 
+    def normalize_metric_description(value)
+      unless value.is_a?(String) && value.valid_encoding?
+        raise SdkError.new(
+          "validation_error",
+          "metric description must be a non-blank string of at most 1024 non-control characters"
+        )
+      end
+      normalized = value.strip
+      invalid = normalized.each_codepoint.any? do |character|
+        character <= 0x1f || (character >= 0x7f && character <= 0x9f) || character == 0x2028 || character == 0x2029
+      end
+      if normalized.empty? || normalized.each_codepoint.count > 1024 || invalid
+        raise SdkError.new(
+          "validation_error",
+          "metric description must be a non-blank string of at most 1024 non-control characters"
+        )
+      end
+      normalized
+    end
+
     def read(attributes, key)
       return nil unless attributes.is_a?(Hash)
 
@@ -790,12 +876,26 @@ module LogBrew
       on_event_dropped: nil,
       max_batch_size: EventBatcher::DEFAULT_MAX_SIZE,
       max_batch_bytes: EventBatcher::DEFAULT_MAX_BYTES,
-      persistent_queue_path: nil
+      persistent_queue_path: nil,
+      context: nil,
+      capture_runtime_context: true
     )
       Validation.require_non_empty("api_key", api_key)
       Validation.require_non_empty("sdk_name", sdk_name)
       Validation.require_non_empty("sdk_version", sdk_version)
       raise SdkError.new("validation_error", "max_retries must be non-negative") if max_retries.negative?
+      unless context.nil? || context.is_a?(TelemetryContext)
+        raise SdkError.new("validation_error", "client context must be a LogBrew::TelemetryContext")
+      end
+      unless capture_runtime_context == true || capture_runtime_context == false
+        raise SdkError.new("validation_error", "capture_runtime_context must be a boolean")
+      end
+
+      resolved_context = if capture_runtime_context
+                           TelemetryContext.merge(TelemetryContext.runtime_defaults, context)
+                         else
+                           TelemetryContext.merge(nil, context)
+                         end
 
       new(
         api_key: api_key,
@@ -810,7 +910,8 @@ module LogBrew
         on_event_dropped: on_event_dropped,
         max_batch_size: max_batch_size,
         max_batch_bytes: max_batch_bytes,
-        persistent_queue_path: persistent_queue_path
+        persistent_queue_path: persistent_queue_path,
+        context: resolved_context
       )
     end
 
@@ -860,10 +961,12 @@ module LogBrew
       on_event_dropped: nil,
       max_batch_size: EventBatcher::DEFAULT_MAX_SIZE,
       max_batch_bytes: EventBatcher::DEFAULT_MAX_BYTES,
-      persistent_queue_path: nil
+      persistent_queue_path: nil,
+      context: nil
     )
       @api_key = api_key
       @sdk = sdk
+      @context = context
       @max_retries = max_retries
       @event_batcher = EventBatcher.new(sdk: sdk, max_size: max_batch_size, max_bytes: max_batch_bytes)
       event_store = nil
@@ -954,31 +1057,31 @@ module LogBrew
     end
 
     def release(id, timestamp, attributes)
-      push_event("release", id, timestamp, validate_release(attributes))
+      push_event("release", id, timestamp, validate_release(attributes), event_context(attributes))
     end
 
     def environment(id, timestamp, attributes)
-      push_event("environment", id, timestamp, validate_environment(attributes))
+      push_event("environment", id, timestamp, validate_environment(attributes), event_context(attributes))
     end
 
     def issue(id, timestamp, attributes)
-      push_event("issue", id, timestamp, validate_issue(attributes))
+      push_event("issue", id, timestamp, validate_issue(attributes), event_context(attributes))
     end
 
     def log(id, timestamp, attributes)
-      push_event("log", id, timestamp, validate_log(attributes))
+      push_event("log", id, timestamp, validate_log(attributes), event_context(attributes))
     end
 
     def span(id, timestamp, attributes)
-      push_event("span", id, timestamp, validate_span(attributes))
+      push_event("span", id, timestamp, validate_span(attributes), event_context(attributes))
     end
 
     def metric(id, timestamp, attributes)
-      push_event("metric", id, timestamp, validate_metric(attributes))
+      push_event("metric", id, timestamp, validate_metric(attributes), event_context(attributes))
     end
 
     def action(id, timestamp, attributes)
-      push_event("action", id, timestamp, validate_action(attributes))
+      push_event("action", id, timestamp, validate_action(attributes), event_context(attributes))
     end
 
     def flush(transport = nil)
@@ -1035,10 +1138,18 @@ module LogBrew
 
     private
 
-    def push_event(type, id, timestamp, attributes)
+    def push_event(type, id, timestamp, attributes, event_context)
       @automatic_delivery&.assert_process_ownership!
       Validation.require_non_empty("event id", id)
       Validation.require_timestamp(timestamp)
+      ambient_context = Telemetry.current_context
+      active_trace = defined?(LogBrew::Trace) ? LogBrew::Trace.current : nil
+      ambient_context = TelemetryContext.with_trace(ambient_context, active_trace) unless active_trace.nil?
+      merged_context = TelemetryContext.merge(
+        TelemetryContext.merge(@context, ambient_context),
+        event_context
+      )
+      attributes["context"] = merged_context.to_h unless merged_context.nil?
       event = {
         "type" => type,
         "timestamp" => timestamp,
@@ -1217,20 +1328,7 @@ module LogBrew
     end
 
     def validate_issue(attributes)
-      title = Validation.read(attributes, "title")
-      level = Validation.read(attributes, "level")
-      Validation.require_non_empty("issue title", title)
-      level = normalize_severity("issue level", level)
-      with_metadata(
-        {
-          "title" => title,
-          "level" => level
-        }.tap do |payload|
-          message = Validation.read(attributes, "message")
-          payload["message"] = message unless message.nil?
-        end,
-        attributes
-      )
+      IssueDiagnostics.validate_issue_attributes(attributes)
     end
 
     def validate_log(attributes)
@@ -1290,6 +1388,8 @@ module LogBrew
 
     def validate_metric(attributes)
       name = Validation.read(attributes, "name")
+      description_present = attributes.is_a?(Hash) && (attributes.key?("description") || attributes.key?(:description))
+      description = Validation.normalize_metric_description(Validation.read(attributes, "description")) if description_present
       kind = Validation.read(attributes, "kind")
       unit = Validation.read(attributes, "unit")
       temporality = Validation.read(attributes, "temporality")
@@ -1305,11 +1405,12 @@ module LogBrew
       with_metadata(
         {
           "name" => name,
+          "description" => description,
           "kind" => kind,
           "value" => value,
           "unit" => unit,
           "temporality" => temporality
-        },
+        }.compact,
         attributes
       )
     end
@@ -1322,6 +1423,23 @@ module LogBrew
       with_metadata({ "name" => name, "status" => status }, attributes)
     end
 
+    def event_context(attributes)
+      return nil unless attributes.is_a?(Hash)
+
+      string_key = attributes.key?("context")
+      symbol_key = attributes.key?(:context)
+      if string_key && symbol_key
+        raise SdkError.new("validation_error", "event context must use one context field")
+      end
+      return nil unless string_key || symbol_key
+
+      value = string_key ? attributes["context"] : attributes[:context]
+      unless value.is_a?(TelemetryContext)
+        raise SdkError.new("validation_error", "event context must be a LogBrew::TelemetryContext")
+      end
+      value
+    end
+
     def with_metadata(payload, attributes)
       metadata = Validation.require_metadata(Validation.read(attributes, "metadata"))
       payload["metadata"] = metadata unless metadata.nil?
@@ -1332,6 +1450,6 @@ module LogBrew
   require_relative "logbrew/automatic_delivery"
 end
 
-%w[product_timeline traceparent trace span_events operation_tracing http_client_tracing support_ticket worker_lifecycle].each do |path|
+%w[issue_diagnostics product_timeline traceparent trace span_events operation_tracing http_client_tracing support_ticket worker_lifecycle].each do |path|
   require_relative "logbrew/#{path}"
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: logbrew-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies: []
-description: Public LogBrew Ruby SDK with automatic Rails request/error capture and
-  standard-library delivery.
+description: Public LogBrew Ruby SDK with typed issue diagnostics, automatic Rails
+  request/error capture, and standard-library delivery.
 email:
 executables: []
 extensions: []
@@ -22,6 +22,7 @@ files:
 - examples/automatic_delivery.rb
 - examples/first_useful_telemetry.rb
 - examples/http_trace_correlation.rb
+- examples/issue_diagnostics.rb
 - examples/persistent_worker_delivery.rb
 - examples/readme_example.rb
 - examples/real_user_smoke.rb
@@ -33,6 +34,7 @@ files:
 - lib/logbrew/event_batcher.rb
 - lib/logbrew/faraday_tracing.rb
 - lib/logbrew/http_client_tracing.rb
+- lib/logbrew/issue_diagnostics.rb
 - lib/logbrew/operation_tracing.rb
 - lib/logbrew/persistent_event_store.rb
 - lib/logbrew/product_timeline.rb
@@ -41,6 +43,10 @@ files:
 - lib/logbrew/sidekiq.rb
 - lib/logbrew/span_events.rb
 - lib/logbrew/support_ticket.rb
+- lib/logbrew/telemetry.rb
+- lib/logbrew/telemetry_context.rb
+- lib/logbrew/telemetry_context_value.rb
+- lib/logbrew/telemetry_resource.rb
 - lib/logbrew/trace.rb
 - lib/logbrew/traceparent.rb
 - lib/logbrew/version.rb