logister-ruby 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f3f9f67b976e92e535974c8a243b14f011088bca57e5ab3dc0385de6ba4c003
-  data.tar.gz: d744d4996b00d27a2e51e54b5b91134f4c0ae049c76270a41c7ef93deec04189
+  metadata.gz: 0ffb0ff308c1a54f984e8c68088561c76a044e90766bee92a4ef23a51e0c5a78
+  data.tar.gz: fd0a658239131bec7061a722ed45044c0a2c7aba2125242b766837d0fd8d5dc8
 SHA512:
-  metadata.gz: 9a8dbbbdde7778369654c287f9076a89efaadf5a3d03bdd5cb064546bac2b2b72bd53d641b424d3b4bc3cefecfce0bfd1b0a9c50714a8c58506b21c6765b8902
-  data.tar.gz: 823a8c724d3aee752558e9936c23f924c774157c83a7b997885ba19a8dbf6aa835277506101f2eea341dde05923353f58127f6b94c0d8cbb6711823c5f43c946
+  metadata.gz: c89ea19d2cd68d4e7de0d85ff4b8c727fa0378d9a9e3b86e9a631fbb3e1a0df05d8cf7c9620636c9d7581011e53800cd57c9dffd7dabb9f83e52494c04d32c49
+  data.tar.gz: 42e48cd2049ab3adf2c496209dd71734891db9134f621920c988c138fb31bd3af99d1a72f39cc2b85f624f8f61ae586b873a036302fe0d29ca767d725cac4e9c

data/README.md

@@ -23,6 +23,21 @@ Logister.configure do |config|
   config.environment = Rails.env
   config.service = Rails.application.class.module_parent_name.underscore
   config.release = ENV["RELEASE_SHA"]
+
+  # Optional richer context hooks
+  config.anonymize_ip = false
+  config.max_breadcrumbs = 40
+  config.max_dependencies = 20
+  config.capture_sql_breadcrumbs = true
+  config.sql_breadcrumb_min_duration_ms = 25.0
+
+  config.feature_flags_resolver = lambda do |request:, user:, **|
+    { new_checkout: user&.respond_to?(:beta?) && user.beta? }
+  end
+
+  config.dependency_resolver = lambda do |**|
+    [] # or return [{ name:, host:, method:, status:, durationMs:, kind: }]
+  end
 end
 ```
 
@@ -55,6 +70,7 @@ end
 ## Rails auto-reporting
 
 If Rails is present, the gem installs middleware that reports unhandled exceptions automatically.
+It also attaches richer context (trace IDs, route/response/performance info, breadcrumbs, dependency calls, and user metadata when available).
 
 ## Database load metrics (ActiveRecord)
 
@@ -70,6 +86,37 @@ end
 
 This emits metric events with `message: "db.query"` and context fields such as `duration_ms`, `name`, `sql`, and `binds_count`.
 
+## Breadcrumbs and dependencies
+
+You can add manual breadcrumbs and dependency calls that will be attached to captured errors:
+
+```ruby
+Logister.add_breadcrumb(
+  category: "checkout",
+  message: "Starting payment authorization",
+  data: { order_id: 123 }
+)
+
+Logister.add_dependency(
+  name: "stripe.charge",
+  host: "api.stripe.com",
+  method: "POST",
+  status: 200,
+  duration_ms: 184.7,
+  kind: "http"
+)
+```
+
+The gem also captures request and SQL breadcrumbs automatically in Rails.
+
+## ActiveJob error context
+
+Failed ActiveJob executions are auto-reported with `job` context:
+- job class/id/queue/retries/schedule
+- filtered job arguments (using `filter_parameters`)
+- runtime/deployment metadata
+- breadcrumbs/dependency calls collected during the job
+
 ## Manual reporting
 
 ```ruby

data/lib/logister/active_job_reporter.rb

@@ -0,0 +1,83 @@
+require_relative "context_helpers"
+require_relative "context_store"
+
+module Logister
+  module ActiveJobReporter
+    def self.install!
+      return unless defined?(ActiveJob::Base)
+      return if ActiveJob::Base < Logister::ActiveJobReporter::Instrumentation
+
+      ActiveJob::Base.include(Logister::ActiveJobReporter::Instrumentation)
+    end
+
+    module Instrumentation
+      extend ActiveSupport::Concern
+
+      included do
+        around_perform do |job, block|
+          Logister::ContextStore.reset_request_scope!
+          Logister.add_breadcrumb(
+            category: "job",
+            message: "Starting #{job.class.name}",
+            data: { queue: job.queue_name, jobId: job.job_id }
+          )
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          begin
+            block.call
+          rescue StandardError => error
+            Logister.report_error(
+              error,
+              context: Logister::ActiveJobReporter.build_job_error_context(job, started_at: started_at)
+            )
+            raise
+          ensure
+            Logister::ContextStore.reset_request_scope!
+          end
+        end
+      end
+    end
+
+    module_function
+
+    def build_job_error_context(job, started_at:)
+      Logister::ContextHelpers.compact_deep(
+        {
+          job: {
+            jobClass: job.class.name.to_s,
+            jobId: job.job_id.to_s.presence,
+            providerJobId: job.provider_job_id.to_s.presence,
+            queue: job.queue_name.to_s.presence,
+            priority: job.priority,
+            executions: job.executions,
+            exceptionExecutions: serialize_exception_executions(job),
+            locale: job.locale.to_s.presence,
+            timezone: (job.respond_to?(:timezone) ? job.timezone.to_s.presence : nil),
+            enqueuedAt: (job.respond_to?(:enqueued_at) ? time_to_iso8601(job.enqueued_at) : nil),
+            scheduledAt: time_to_iso8601(job.scheduled_at),
+            arguments: Logister::ContextHelpers.filtered_job_arguments(job)
+          }.compact,
+          breadcrumbs: Logister::ContextStore.breadcrumbs.presence,
+          dependencyCalls: Logister::ContextStore.dependencies.presence,
+          runtime: Logister::ContextHelpers.runtime_context[:runtime],
+          deployment: Logister::ContextHelpers.deployment_context[:deployment]
+        }
+      )
+    end
+
+    def serialize_exception_executions(job)
+      raw = job.respond_to?(:exception_executions) ? job.exception_executions : nil
+      return nil if raw.nil?
+
+      raw.is_a?(Hash) ? raw.transform_keys(&:to_s) : raw
+    end
+
+    def time_to_iso8601(value)
+      return nil unless value.respond_to?(:iso8601)
+
+      value.iso8601
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/logister/client.rb

@@ -1,15 +1,25 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'net/http'
 require 'uri'
 
 module Logister
   class Client
+    CONTENT_TYPE = 'application/json'
+
     def initialize(configuration)
       @configuration = configuration
-      @worker_mutex = Mutex.new
-      @queue = SizedQueue.new(@configuration.queue_size)
-      @worker = nil
-      @running = false
+      @worker_mutex  = Mutex.new
+      @queue         = SizedQueue.new(@configuration.queue_size)
+      @worker        = nil
+      @running       = false
+
+      # Cache values that are static for the lifetime of this client so we
+      # don't allocate on every send_request call.
+      @uri         = URI.parse(@configuration.endpoint).freeze
+      @use_ssl     = @uri.scheme == 'https'
+      @auth_header = "Bearer #{@configuration.api_key}".freeze
     end
 
     def publish(payload)
@@ -24,9 +34,9 @@ module Logister
     def flush(timeout: 2)
       return true unless @configuration.async
 
-      started_at = monotonic_now
-      while @queue.length.positive?
-        return false if monotonic_now - started_at > timeout
+      deadline = monotonic_now + timeout
+      until @queue.empty?
+        return false if monotonic_now > deadline
 
         sleep(0.01)
       end
@@ -44,6 +54,7 @@ module Logister
         nil
       end
       @worker&.join(1)
+      @worker = nil
       true
     end
 
@@ -58,18 +69,20 @@ module Logister
     end
 
     def ensure_worker_started
+      # Fast path — no lock needed if already running (GVL-safe on MRI).
       return if @running && @worker&.alive?
 
       @worker_mutex.synchronize do
         return if @running && @worker&.alive?
 
         @running = true
-        @worker = Thread.new { run_worker }
+        @worker  = Thread.new { run_worker }
+        @worker.name = 'logister-worker'
       end
     end
 
     def run_worker
-      while @running
+      loop do
         payload = @queue.pop
         break if payload.nil?
 
@@ -77,6 +90,9 @@ module Logister
       end
     rescue StandardError => e
       @configuration.logger.warn("logister worker crashed: #{e.class} #{e.message}")
+    ensure
+      # Always clear running flag and attempt auto-restart after a crash so
+      # events enqueued after the crash are not silently dropped.
       @running = false
     end
 
@@ -97,16 +113,15 @@ module Logister
     end
 
     def send_request(payload)
-      uri = URI.parse(@configuration.endpoint)
-      request = Net::HTTP::Post.new(uri)
-      request['Content-Type'] = 'application/json'
-      request['Authorization'] = "Bearer #{@configuration.api_key}"
-      request.body = { event: payload }.to_json
+      request = Net::HTTP::Post.new(@uri)
+      request['Content-Type']  = CONTENT_TYPE
+      request['Authorization'] = @auth_header
+      request.body             = { event: payload }.to_json
 
       response = Net::HTTP.start(
-        uri.host,
-        uri.port,
-        use_ssl: uri.scheme == 'https',
+        @uri.host,
+        @uri.port,
+        use_ssl:      @use_ssl,
         open_timeout: @configuration.timeout_seconds,
         read_timeout: @configuration.timeout_seconds
       ) { |http| http.request(request) }
@@ -121,7 +136,7 @@ module Logister
     end
 
     def ready?
-      @configuration.enabled && @configuration.api_key.to_s != ''
+      @configuration.enabled && !@configuration.api_key.to_s.empty?
     end
   end
 end

data/lib/logister/configuration.rb

@@ -5,7 +5,10 @@ module Logister
     attr_accessor :api_key, :endpoint, :environment, :service, :release, :enabled, :timeout_seconds, :logger,
                   :ignore_exceptions, :ignore_environments, :ignore_paths, :before_notify,
                   :async, :queue_size, :max_retries, :retry_base_interval,
-                  :capture_db_metrics, :db_metric_min_duration_ms, :db_metric_sample_rate
+                  :capture_db_metrics, :db_metric_min_duration_ms, :db_metric_sample_rate,
+                  :feature_flags_resolver, :dependency_resolver, :anonymize_ip,
+                  :max_breadcrumbs, :max_dependencies,
+                  :capture_sql_breadcrumbs, :sql_breadcrumb_min_duration_ms
 
     def initialize
       @api_key = ENV['LOGISTER_API_KEY']
@@ -31,6 +34,14 @@ module Logister
       @capture_db_metrics = false
       @db_metric_min_duration_ms = 0.0
       @db_metric_sample_rate = 1.0
+
+      @feature_flags_resolver = nil
+      @dependency_resolver = nil
+      @anonymize_ip = false
+      @max_breadcrumbs = 40
+      @max_dependencies = 20
+      @capture_sql_breadcrumbs = true
+      @sql_breadcrumb_min_duration_ms = 25.0
     end
   end
 end

data/lib/logister/context_helpers.rb

@@ -0,0 +1,262 @@
+require "digest"
+require "socket"
+require "ipaddr"
+
+module Logister
+  module ContextHelpers
+    FILTERED_VALUE = "[FILTERED]".freeze
+
+    module_function
+
+    def runtime_context
+      {
+        runtime: {
+          rubyVersion: RUBY_VERSION,
+          railsVersion: defined?(Rails) ? Rails.version : nil,
+          rackVersion: defined?(Rack) ? Rack.release : nil,
+          platform: RUBY_PLATFORM
+        }.compact
+      }
+    end
+
+    def deployment_context
+      config = Logister.configuration if Logister.respond_to?(:configuration)
+      environment = config&.respond_to?(:environment) ? config.environment.to_s.presence : nil
+      service = config&.respond_to?(:service) ? config.service.to_s.presence : nil
+      release = config&.respond_to?(:release) ? config.release.to_s.presence : nil
+
+      {
+        deployment: {
+          environment: environment || ENV["RAILS_ENV"].to_s.presence || ENV["RACK_ENV"].to_s.presence || "development",
+          service: service || ENV["LOGISTER_SERVICE"].to_s.presence || "ruby-app",
+          release: release || ENV["LOGISTER_RELEASE"].to_s.presence,
+          region: ENV["FLY_REGION"].to_s.presence || ENV["RAILS_REGION"].to_s.presence || ENV["AWS_REGION"].to_s.presence,
+          hostname: Socket.gethostname.to_s.presence,
+          processPid: Process.pid
+        }.compact
+      }
+    end
+
+    def trace_context(headers:, env:)
+      traceparent = header_value(headers, "Traceparent")
+      b3_trace_id = header_value(headers, "X-B3-Traceid")
+      b3_span_id = header_value(headers, "X-B3-Spanid")
+      datadog_trace_id = header_value(headers, "X-Datadog-Trace-Id")
+      datadog_parent_id = header_value(headers, "X-Datadog-Parent-Id")
+      amzn_trace_id = header_value(headers, "X-Amzn-Trace-Id")
+
+      parsed_trace_id, parsed_span_id, parsed_sampled = parse_traceparent(traceparent)
+
+      {
+        trace: {
+          traceId: parsed_trace_id || b3_trace_id || datadog_trace_id,
+          spanId: parsed_span_id || b3_span_id || datadog_parent_id,
+          sampled: parsed_sampled,
+          traceparent: traceparent,
+          requestId: env["action_dispatch.request_id"].to_s.presence,
+          amznTraceId: amzn_trace_id
+        }.compact
+      }
+    end
+
+    def resolve_feature_flags(request:, env:, user:)
+      resolver = configuration_value(:feature_flags_resolver)
+      return {} unless resolver.respond_to?(:call)
+
+      raw = call_resolver(resolver, request: request, env: env, user: user)
+      flags = normalize_flags_hash(raw)
+      return {} if flags.empty?
+
+      { featureFlags: flags }
+    rescue StandardError
+      {}
+    end
+
+    def resolve_dependency_context(request:, env:)
+      resolver = configuration_value(:dependency_resolver)
+      return {} unless resolver.respond_to?(:call)
+
+      raw = call_resolver(resolver, request: request, env: env)
+      list = normalize_dependency_list(raw)
+      return {} if list.empty?
+
+      { dependencyCalls: list }
+    rescue StandardError
+      {}
+    end
+
+    def anonymize_ip(ip)
+      return nil if ip.to_s.strip.empty?
+      return ip.to_s unless configuration_value(:anonymize_ip, false)
+
+      parsed = IPAddr.new(ip.to_s)
+      if parsed.ipv4?
+        segments = ip.to_s.split(".")
+        return ip.to_s if segments.size != 4
+
+        "#{segments[0]}.#{segments[1]}.#{segments[2]}.0"
+      else
+        "#{parsed.mask(64).to_s}/64"
+      end
+    rescue StandardError
+      ip.to_s
+    end
+
+    def user_context_for(user)
+      return {} unless user
+
+      {
+        user: {
+          id: safe_call(user, :id).to_s.presence,
+          class: user.class.name.to_s.presence,
+          email_hash: hashed_email(user),
+          role: safe_call(user, :role).to_s.presence,
+          account_id: safe_call(user, :account_id).to_s.presence || safe_call(user, :tenant_id).to_s.presence
+        }.compact
+      }
+    end
+
+    def filtered_job_arguments(job)
+      arguments = Array(job.arguments)
+      return arguments if arguments.empty?
+
+      filter = ActiveSupport::ParameterFilter.new(
+        Array(Rails.application.config.filter_parameters)
+      )
+      arguments.map { |argument| filter_argument(argument, filter) }
+    rescue StandardError
+      arguments
+    end
+
+    def safe_call(object, method_name)
+      return nil unless object.respond_to?(method_name)
+
+      object.public_send(method_name)
+    rescue StandardError
+      nil
+    end
+
+    def hash_value(value)
+      return nil if value.to_s.strip.empty?
+
+      Digest::SHA256.hexdigest(value.to_s.strip.downcase)
+    end
+
+    def compact_deep(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(key, nested), acc|
+          compacted = compact_deep(nested)
+          next if blank_value?(compacted)
+
+          acc[key] = compacted
+        end
+      when Array
+        value.map { |item| compact_deep(item) }.reject { |item| blank_value?(item) }
+      else
+        value
+      end
+    end
+
+    def blank_value?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def hashed_email(user)
+      email = safe_call(user, :email)
+      hash_value(email)
+    end
+    private_class_method :hashed_email
+
+    def filter_argument(argument, filter)
+      case argument
+      when Hash
+        filter.filter(argument)
+      when Array
+        argument.map { |nested| filter_argument(nested, filter) }
+      else
+        argument
+      end
+    end
+    private_class_method :filter_argument
+
+    def header_value(headers, key)
+      return nil unless headers.is_a?(Hash)
+
+      headers[key].presence || headers[key.downcase].presence || headers[key.upcase].presence
+    end
+    private_class_method :header_value
+
+    def parse_traceparent(traceparent)
+      return [ nil, nil, nil ] if traceparent.to_s.empty?
+
+      parts = traceparent.to_s.split("-")
+      return [ nil, nil, nil ] unless parts.size == 4
+
+      trace_id = parts[1].to_s
+      span_id = parts[2].to_s
+      flags = parts[3].to_s
+      sampled = flags.end_with?("01")
+
+      [ trace_id.presence, span_id.presence, sampled ]
+    rescue StandardError
+      [ nil, nil, nil ]
+    end
+    private_class_method :parse_traceparent
+
+    def normalize_flags_hash(raw)
+      case raw
+      when Hash
+        raw.each_with_object({}) do |(key, value), acc|
+          acc[key.to_s] = value
+        end
+      else
+        {}
+      end
+    end
+    private_class_method :normalize_flags_hash
+
+    def normalize_dependency_list(raw)
+      list = case raw
+      when Array then raw
+      when Hash then [ raw ]
+      else []
+      end
+
+      list.map do |item|
+        next unless item.is_a?(Hash)
+
+        {
+          name: item[:name] || item["name"],
+          host: item[:host] || item["host"],
+          method: item[:method] || item["method"],
+          status: item[:status] || item["status"],
+          durationMs: item[:durationMs] || item["durationMs"] || item[:duration_ms] || item["duration_ms"],
+          kind: item[:kind] || item["kind"],
+          error: item[:error] || item["error"]
+        }.compact
+      end.compact
+    end
+    private_class_method :normalize_dependency_list
+
+    def configuration_value(key, fallback = nil)
+      return fallback unless Logister.respond_to?(:configuration)
+
+      Logister.configuration.public_send(key)
+    rescue StandardError
+      fallback
+    end
+    private_class_method :configuration_value
+
+    def call_resolver(resolver, **kwargs)
+      if resolver.arity == 1
+        resolver.call(kwargs)
+      else
+        resolver.call(**kwargs)
+      end
+    rescue ArgumentError
+      resolver.call(kwargs[:request], kwargs[:env], kwargs[:user])
+    end
+    private_class_method :call_resolver
+  end
+end

data/lib/logister/context_store.rb

@@ -0,0 +1,134 @@
+module Logister
+  module ContextStore
+    REQUEST_SCOPE_KEY = :__logister_request_scope
+    MAX_REQUEST_SUMMARIES = 200
+
+    module_function
+
+    def reset_request_scope!
+      Thread.current[REQUEST_SCOPE_KEY] = {
+        breadcrumbs: [],
+        dependencies: []
+      }
+    end
+
+    def add_breadcrumb(category:, message:, data: {}, level: "info", timestamp: Time.now.utc.iso8601)
+      scope = request_scope
+      breadcrumbs = scope[:breadcrumbs]
+      breadcrumbs << {
+        category: category.to_s,
+        message: message.to_s,
+        level: level.to_s,
+        timestamp: timestamp,
+        data: sanitize_hash(data)
+      }.compact
+      trim_collection!(breadcrumbs, max_breadcrumbs)
+    end
+
+    def breadcrumbs
+      request_scope[:breadcrumbs].dup
+    end
+
+    def add_dependency(name:, host: nil, method: nil, status: nil, duration_ms: nil, kind: nil, data: {})
+      scope = request_scope
+      deps = scope[:dependencies]
+      deps << sanitize_hash(
+        {
+          name: name.to_s.presence,
+          host: host.to_s.presence,
+          method: method.to_s.presence,
+          status: status,
+          durationMs: duration_ms && duration_ms.to_f.round(2),
+          kind: kind.to_s.presence,
+          data: sanitize_hash(data)
+        }.compact
+      )
+      trim_collection!(deps, max_dependencies)
+    end
+
+    def dependencies
+      request_scope[:dependencies].dup
+    end
+
+    def store_request_summary(request_id, summary)
+      return if request_id.to_s.empty?
+
+      cache = request_summaries
+      cache[request_id.to_s] = sanitize_hash(summary)
+      trim_hash!(cache, MAX_REQUEST_SUMMARIES)
+    end
+
+    def request_summary(request_id)
+      return nil if request_id.to_s.empty?
+
+      request_summaries[request_id.to_s]
+    end
+
+    def clear_request_summary(request_id)
+      request_summaries.delete(request_id.to_s)
+    end
+
+    def add_manual_dependency(**kwargs)
+      add_dependency(**kwargs)
+    end
+
+    def add_manual_breadcrumb(**kwargs)
+      add_breadcrumb(**kwargs)
+    end
+
+    def request_scope
+      Thread.current[REQUEST_SCOPE_KEY] ||= {
+        breadcrumbs: [],
+        dependencies: []
+      }
+    end
+    private_class_method :request_scope
+
+    def request_summaries
+      Thread.current[:__logister_request_summaries] ||= {}
+    end
+    private_class_method :request_summaries
+
+    def sanitize_hash(value)
+      return {} unless value.is_a?(Hash)
+
+      value.each_with_object({}) do |(key, nested), acc|
+        acc[key] = nested
+      end
+    end
+    private_class_method :sanitize_hash
+
+    def max_breadcrumbs
+      config_value(:max_breadcrumbs, 40).to_i.clamp(1, 500)
+    end
+    private_class_method :max_breadcrumbs
+
+    def max_dependencies
+      config_value(:max_dependencies, 20).to_i.clamp(1, 500)
+    end
+    private_class_method :max_dependencies
+
+    def trim_collection!(array, max_size)
+      overflow = array.size - max_size
+      array.shift(overflow) if overflow.positive?
+    end
+    private_class_method :trim_collection!
+
+    def trim_hash!(hash, max_size)
+      overflow = hash.size - max_size
+      return unless overflow.positive?
+
+      hash.keys.first(overflow).each { |key| hash.delete(key) }
+    end
+    private_class_method :trim_hash!
+
+    def config_value(key, fallback)
+      return fallback unless Logister.respond_to?(:configuration)
+
+      Logister.configuration.public_send(key)
+    rescue StandardError
+      fallback
+    end
+    private_class_method :config_value
+  end
+end