logbrew-sdk 0.1.2 → 0.1.4

data/lib/logbrew.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "digest"
 require "json"
 require "logger"
 require "net/http"
@@ -8,6 +9,8 @@ require "time"
 require "timeout"
 require "uri"
 
+require_relative "logbrew/version"
+
 module LogBrew
   SEVERITY_VALUES = %w[trace debug info warn warning error fatal critical].freeze
   SEVERITY_ALIASES = {
@@ -39,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"
@@ -369,6 +377,7 @@ module LogBrew
       event_id_prefix: DEFAULT_EVENT_ID_PREFIX,
       metadata: nil,
       timestamp_provider: nil,
+      include_exception_message: true,
       include_exception_backtrace: false,
       on_error: nil,
       raise_errors: false
@@ -384,10 +393,12 @@ module LogBrew
       @event_id_prefix = event_id_prefix
       @metadata = metadata || {}
       @timestamp_provider = timestamp_provider
+      @include_exception_message = include_exception_message
       @include_exception_backtrace = include_exception_backtrace
       @on_error = on_error
       @raise_errors = raise_errors
       @next_event_number = 0
+      @event_id_mutex = Mutex.new
     end
 
     def call(env)
@@ -428,19 +439,21 @@ module LogBrew
     end
 
     def capture_exception_issue(env, error)
-      @client.issue(
-        next_event_id("issue"),
-        logbrew_timestamp,
-        title: error.class.name,
-        level: "error",
-        message: error.message,
+      attributes = IssueDiagnostics.from_exception(
+        error,
+        message: @include_exception_message ? error.message : nil,
+        mechanism_type: exception_mechanism_type,
+        handled: false,
         metadata: exception_metadata(env, error)
       )
+      @client.issue(next_event_id("issue"), logbrew_timestamp, attributes)
     end
 
     def next_event_id(kind)
-      @next_event_number += 1
-      "#{@event_id_prefix}_#{kind}_#{@next_event_number}"
+      @event_id_mutex.synchronize do
+        @next_event_number += 1
+        "#{@event_id_prefix}_#{kind}_#{@next_event_number}"
+      end
     end
 
     def logbrew_timestamp
@@ -491,12 +504,39 @@ module LogBrew
 
     def exception_metadata(env, error)
       request_metadata(env, 500).tap do |metadata|
-        metadata["exceptionType"] = error.class.name
-        metadata["exceptionMessage"] = error.message
+        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?
 
@@ -573,6 +613,7 @@ module LogBrew
       event_id_prefix: DEFAULT_EVENT_ID_PREFIX,
       metadata: nil,
       timestamp_provider: nil,
+      include_exception_message: true,
       include_exception_backtrace: false,
       on_error: nil,
       raise_errors: false
@@ -586,23 +627,36 @@ module LogBrew
       @event_id_prefix = event_id_prefix
       @metadata = metadata || {}
       @timestamp_provider = timestamp_provider
+      @include_exception_message = include_exception_message
       @include_exception_backtrace = include_exception_backtrace
       @on_error = on_error
       @raise_errors = raise_errors
       @next_event_number = 0
+      @event_id_mutex = Mutex.new
     end
 
     def report(error, handled: true, severity: :error, context: nil, source: nil, **_options)
       capture_safely do
-        @next_event_number += 1
-        @client.issue(
-          "#{@event_id_prefix}_#{@next_event_number}",
-          logbrew_timestamp,
-          title: error_title(error),
-          level: issue_level(severity),
-          message: error_message(error),
-          metadata: rails_metadata(error, handled, severity, context, source)
-        )
+        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
     end
@@ -629,6 +683,13 @@ module LogBrew
       error.inspect
     end
 
+    def next_event_id
+      @event_id_mutex.synchronize do
+        @next_event_number += 1
+        "#{@event_id_prefix}_#{@next_event_number}"
+      end
+    end
+
     def issue_level(severity)
       SEVERITY_TO_ISSUE_LEVEL.fetch(severity.to_s, "error")
     end
@@ -654,11 +715,30 @@ module LogBrew
     end
 
     def add_exception_metadata(metadata, exception)
-      metadata["exceptionType"] = exception.class.name
-      metadata["exceptionMessage"] = exception.message
+      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)
@@ -745,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)
 
@@ -776,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,
@@ -796,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
 
@@ -846,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
@@ -940,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)
@@ -1021,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,
@@ -1203,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)
@@ -1276,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")
@@ -1291,11 +1405,12 @@ module LogBrew
       with_metadata(
         {
           "name" => name,
+          "description" => description,
           "kind" => kind,
           "value" => value,
           "unit" => unit,
           "temporality" => temporality
-        },
+        }.compact,
         attributes
       )
     end
@@ -1308,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?
@@ -1318,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.2
+  version: 0.1.4
 platform: ruby
 authors:
 - LogBrew
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-08-10 00:00:00.000000000 Z
 dependencies: []
-description: Public LogBrew Ruby SDK for building, validating, and flushing event
-  batches.
+description: Public LogBrew Ruby SDK with typed issue diagnostics, automatic Rails
+  request/error capture, and standard-library delivery.
 email:
 executables: []
 extensions: []
@@ -22,24 +22,34 @@ 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
 - examples/sidekiq_tracing.rb
+- lib/logbrew-sdk.rb
 - lib/logbrew.rb
 - lib/logbrew/automatic_delivery.rb
 - lib/logbrew/bounded_event_queue.rb
 - 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
+- lib/logbrew/rails.rb
+- lib/logbrew/rails_integration.rb
 - 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
 - lib/logbrew/worker_lifecycle.rb
 homepage: https://github.com/LogBrewCo/sdk
 licenses: