opentrace 0.7.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fbe3de5afdb5f92afcef49d368b8f8b3714ca17fe453b168066f53a5b0e5e1ba
-  data.tar.gz: 8f749e943951c939e7daa8f93a454bb0c89646bc295c0550c680064ebf38db16
+  metadata.gz: f91e8fcf70aeeb601265b588138c85d00c5a96d034278caa4226072eb75c440d
+  data.tar.gz: ed9d094bf4af6d4545f70d464753bfd594e4d0ddf5758a977e6205bc2d6ad4ef
 SHA512:
-  metadata.gz: e3ecb7c4b649951f64e1090bb7ea06da69cb603dcd44534c9a5e71d76eb697239fddf2267cd2a5e0cff2aa1bf86dc78be6733be754df8e5c6a435967d90809a8
-  data.tar.gz: 3625d9de1cd2dda011f69283b34a17964450cda3c44c0f19431fb450e2a24328f1c260a12ea9929331a54866ac90afd07addd65e16cb2eee9e42a939807f3a69
+  metadata.gz: 56a8cea4c49c71aa18b467e041ceba338646883cc9b158d9b28efea5d741148b08e911c762f7a596b9ec7edfd93804875a14f0038e5bee08333c81afeb52865b
+  data.tar.gz: 7f66b1c9f6b55a37e1bfe2adbe2731f4e87b32eeab068287782b8abbd734a2f9930dccfb68f2fe2e84f2e67ac85798b91abe44262b7f46c3d83a3d3e439cdf97

data/lib/opentrace/breadcrumbs.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module OpenTrace
+  class Breadcrumb
+    attr_reader :category, :message, :data, :timestamp, :level
+
+    def initialize(category:, message:, data: nil, level: "info")
+      @category = category.to_s
+      @message = message.to_s
+      @data = data
+      @level = level.to_s
+      @timestamp = Process.clock_gettime(Process::CLOCK_REALTIME)
+    end
+
+    def to_h
+      h = { category: @category, message: @message, level: @level, timestamp: @timestamp }
+      h[:data] = @data if @data
+      h
+    end
+  end
+
+  class BreadcrumbBuffer
+    MAX_BREADCRUMBS = 25
+
+    def initialize
+      @buffer = []
+    end
+
+    def add(breadcrumb)
+      @buffer.shift if @buffer.size >= MAX_BREADCRUMBS
+      @buffer << breadcrumb
+    end
+
+    def to_a
+      @buffer.map(&:to_h)
+    end
+
+    def empty?
+      @buffer.empty?
+    end
+
+    def size
+      @buffer.size
+    end
+  end
+end

data/lib/opentrace/client.rb

@@ -11,14 +11,14 @@ module OpenTrace
   class Client
     MAX_QUEUE_SIZE = 1000
     PAYLOAD_MAX_BYTES = 262_144 # 256 KB (default; use config.max_payload_bytes to override)
-    POLL_INTERVAL = 0.05 # 50ms
     MAX_RATE_LIMIT_BACKOFF = 60 # Cap Retry-After at 60 seconds
     API_VERSION = 1
 
     attr_reader :stats
 
-    def initialize(config)
+    def initialize(config, sampler: nil)
       @config = config
+      @sampler = sampler
       @queue  = Thread::Queue.new
       @mutex  = Mutex.new
       @thread = nil
@@ -95,12 +95,13 @@ module OpenTrace
     end
 
     def reset_after_fork!
-      # After fork, the old thread/queue/mutex from the parent are dead.
+      # After fork, the old thread/queue/mutex/connection from the parent are dead.
       # Re-create everything cleanly in the child process.
       @pid    = Process.pid
       @queue  = Thread::Queue.new
       @mutex  = Mutex.new
       @thread = nil
+      @http   = nil # Parent's connection is unusable after fork
       @circuit_breaker.reset!
       @rate_limit_until = nil
       @auth_suspended = false
@@ -140,9 +141,21 @@ module OpenTrace
         next if batch.empty?
 
         send_batch(batch)
+
+        # Adjust backpressure based on queue depth
+        if @sampler
+          queue_pct = @queue.size.to_f / MAX_QUEUE_SIZE
+          if queue_pct > 0.75
+            @sampler.increase_backpressure!
+          elsif queue_pct < 0.25
+            @sampler.decrease_backpressure!
+          end
+        end
       end
     rescue Exception # rubocop:disable Lint/RescueException
       # Swallow all errors including thread kill
+    ensure
+      close_http
     end
 
     def rate_limited?
@@ -188,16 +201,14 @@ module OpenTrace
     end
 
     def pop_with_timeout(timeout)
-      deadline = Time.now + [timeout, 0].max
-      loop do
-        begin
-          return @queue.pop(true)
-        rescue ThreadError
-          return nil if Time.now >= deadline || @queue.closed?
-          sleep(POLL_INTERVAL)
-        end
+      if timeout <= 0
+        # Deadline already passed — still try a non-blocking pop in case
+        # items arrived while we were busy (e.g. during version check).
+        @queue.pop(true)
+      else
+        @queue.pop(timeout: timeout)
       end
-    rescue ClosedQueueError
+    rescue ThreadError, ClosedQueueError
       nil
     end
 
@@ -212,8 +223,25 @@ module OpenTrace
       # Disable HTTP tracking for our own calls to prevent infinite recursion
       Fiber[:opentrace_http_tracking_disabled] = true
 
-      # Apply per-payload truncation
-      batch = batch.map { |p| fit_payload(p) }.compact
+      # Materialize deferred entries + apply before_send filter + truncate
+      batch = batch.filter_map do |item|
+        payload = PayloadBuilder.materialize(item, @config)
+        next nil unless payload
+        if @config.before_send
+          payload = @config.before_send.call(payload) rescue payload
+          unless payload
+            @stats.increment(:dropped_filtered)
+            next nil
+          end
+        end
+        # PII scrubbing (runs on background thread)
+        if @config.pii_scrubbing && payload[:metadata]
+          active_patterns = build_pii_patterns
+          PiiScrubber.scrub!(payload[:metadata], patterns: active_patterns)
+        end
+
+        fit_payload(payload)
+      end
       return if batch.empty?
 
       json = JSON.generate(batch)
@@ -227,7 +255,11 @@ module OpenTrace
         return
       end
 
-      response = send_with_retry(json)
+      response = if @config.transport == :unix_socket
+                   unix_socket_send(json)
+                 else
+                   send_with_retry(json)
+                 end
       handle_response(response, batch, json.bytesize)
     rescue StandardError
       @circuit_breaker.record_failure
@@ -251,6 +283,7 @@ module OpenTrace
         @stats.increment(:delivered, batch.size)
         @stats.increment(:batches_sent)
         @stats.increment(:bytes_sent, bytes)
+        @config.after_send&.call(batch.size, bytes) rescue nil
       when Net::HTTPTooManyRequests
         handle_rate_limit(response, batch)
       when Net::HTTPUnauthorized
@@ -330,7 +363,6 @@ module OpenTrace
     end
 
     def http_post(json, batch_id: nil)
-      http = build_http(@uri)
       request = Net::HTTP::Post.new(@uri.request_uri)
       request["Authorization"] = "Bearer #{@config.api_key}"
       request["Content-Type"]  = "application/json"
@@ -345,7 +377,37 @@ module OpenTrace
         request.body = json
       end
 
-      http.request(request)
+      persistent_http.request(request)
+    rescue IOError, Errno::EPIPE, Errno::ECONNRESET, Net::OpenTimeout => _e
+      # Connection went stale — reset and retry once
+      close_http
+      persistent_http.request(request)
+    end
+
+    def unix_socket_send(json)
+      payload = if @config.compression && json.bytesize > @config.compression_threshold
+                  gzip_compress(json)
+                else
+                  json
+                end
+
+      socket = UNIXSocket.new(@config.socket_path)
+      # Protocol: 4-byte big-endian length prefix + payload
+      socket.write([payload.bytesize].pack("N"))
+      socket.write(payload)
+      socket.flush
+
+      # Read 4-byte status code response
+      response_data = socket.read(4)
+      status = response_data&.unpack1("N") || 500
+      socket.close
+
+      UnixSocketResponse.new(status)
+    rescue Errno::ECONNREFUSED, Errno::ENOENT, Errno::ENOTSOCK
+      # Socket not available — fall back to HTTP
+      send_with_retry(json)
+    rescue StandardError
+      nil
     end
 
     def retryable_response?(response)
@@ -359,13 +421,27 @@ module OpenTrace
       delay + jitter
     end
 
-    def build_http(uri)
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = (uri.scheme == "https")
-      http.open_timeout = @config.timeout
-      http.read_timeout = @config.timeout
-      http.write_timeout = @config.timeout
-      http
+    # Returns a persistent Net::HTTP connection, creating one if needed.
+    # Only called from the dispatch thread — no synchronization needed.
+    def persistent_http
+      return @http if @http&.started?
+
+      @http = Net::HTTP.new(@uri.host, @uri.port)
+      @http.use_ssl = (@uri.scheme == "https")
+      @http.open_timeout = @config.timeout
+      @http.read_timeout = @config.timeout
+      @http.write_timeout = @config.timeout
+      @http.keep_alive_timeout = 30
+      @http.start
+      @http
+    end
+
+    def close_http
+      @http&.finish
+    rescue IOError
+      # Already closed
+    ensure
+      @http = nil
     end
 
     def gzip_compress(string)
@@ -377,6 +453,22 @@ module OpenTrace
       io.string
     end
 
+    def build_pii_patterns
+      patterns = PiiScrubber::PATTERNS.dup
+      # Remove disabled patterns
+      if @config.pii_disabled_patterns
+        @config.pii_disabled_patterns.each { |name| patterns.delete(name) }
+      end
+      result = patterns.values
+      # Add custom patterns
+      if @config.pii_patterns
+        result.concat(@config.pii_patterns)
+      end
+      result
+    rescue StandardError
+      PiiScrubber::PATTERNS.values
+    end
+
     def fire_on_drop(count, reason)
       @config.on_drop&.call(count, reason)
     rescue StandardError
@@ -421,19 +513,40 @@ module OpenTrace
       end
 
       @compatibility_checked = true
-    rescue StandardError
-      # Server might not support /api/version yet — that's fine
+    rescue Exception # rubocop:disable Lint/RescueException
+      # Server might not support /api/version yet — that's fine.
+      # Broad rescue: this is best-effort and must never kill the dispatch loop.
       @compatibility_checked = true
     end
 
+    # One-shot GET for version check. Uses a throwaway connection
+    # so a failure doesn't poison the persistent connection.
     def http_get(uri)
-      http = build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+      http.write_timeout = @config.timeout
       request = Net::HTTP::Get.new(uri.request_uri)
       request["User-Agent"] = "opentrace-ruby/#{OpenTrace::VERSION}"
       request["Authorization"] = "Bearer #{@config.api_key}"
       http.request(request)
     end
 
+    # Adapts a numeric status code from Unix socket into Net::HTTP response duck type
+    UnixSocketResponse = Struct.new(:code) do
+      def is_a?(klass)
+        c = code.to_i
+        case klass.name
+        when "Net::HTTPSuccess"          then c >= 200 && c < 300
+        when "Net::HTTPTooManyRequests"  then c == 429
+        when "Net::HTTPUnauthorized"     then c == 401
+        when "Net::HTTPServerError"      then c >= 500 && c < 600
+        else super
+        end
+      end
+    end
+
     def truncate_payload(payload)
       meta = payload[:metadata]&.dup || {}
 

data/lib/opentrace/config.rb

@@ -4,9 +4,10 @@ module OpenTrace
   class Config
     REQUIRED_FIELDS = %i[endpoint api_key service].freeze
     LEVELS = { debug: 0, info: 1, warn: 2, error: 3, fatal: 4 }.freeze
+    LEVEL_INTS = { "DEBUG" => 0, "INFO" => 1, "WARN" => 2, "ERROR" => 3, "FATAL" => 4 }.freeze
 
     attr_accessor :endpoint, :api_key, :service, :environment, :timeout, :enabled,
-                  :context, :min_level, :allowed_levels, :hostname, :pid, :git_sha,
+                  :context, :hostname, :pid, :git_sha,
                   :batch_size, :flush_interval,
                   :max_retries, :retry_base_delay, :retry_max_delay,
                   :circuit_breaker_threshold, :circuit_breaker_timeout,
@@ -14,13 +15,41 @@ module OpenTrace
                   :on_drop,
                   :compression, :compression_threshold,
                   :sql_logging, :sql_duration_threshold_ms,
-                  :ignore_paths,
                   :pool_monitoring, :pool_monitoring_interval,
                   :queue_monitoring, :queue_monitoring_interval,
                   :request_summary, :timeline, :timeline_max_events,
                   :memory_tracking, :http_tracking,
                   :max_payload_bytes,
-                  :trace_propagation
+                  :trace_propagation,
+                  :log_forwarding, :view_tracking, :cache_tracking,
+                  :deprecation_tracking, :detailed_request_log,
+                  :sample_rate, :sampler, :before_send,
+                  :sql_normalization, :log_trace_injection,
+                  :source_context, :before_breadcrumb,
+                  :pii_scrubbing, :pii_patterns, :pii_disabled_patterns,
+                  :session_tracking,
+                  :on_error, :after_send,
+                :transport, :socket_path,
+                :local_vars_capture,
+                :explain_slow_queries, :explain_threshold_ms,
+                :runtime_metrics, :runtime_metrics_interval
+
+    # Custom writers that invalidate the level cache
+    attr_reader :min_level, :allowed_levels, :ignore_paths
+
+    def min_level=(val)
+      @min_level = val
+      @level_cache = nil
+    end
+
+    def allowed_levels=(val)
+      @allowed_levels = val
+      @level_cache = nil
+    end
+
+    def ignore_paths=(val)
+      @ignore_paths = val
+    end
 
     def initialize
       @endpoint    = nil
@@ -30,7 +59,7 @@ module OpenTrace
       @timeout     = 1.0
       @enabled     = true
       @context     = nil    # nil | Hash | Proc
-      @min_level   = :debug # send everything by default
+      @min_level   = :info
       @allowed_levels = nil  # nil = use min_level threshold (backward compatible)
       @hostname       = nil
       @pid            = nil
@@ -46,20 +75,46 @@ module OpenTrace
       @on_drop        = nil # ->(count, reason) { ... }
       @compression    = true
       @compression_threshold = 1024 # only compress payloads > 1KB
-      @sql_logging    = true
+      @sql_logging    = false
       @sql_duration_threshold_ms = 0.0
-      @ignore_paths   = []
+      @ignore_paths   = %w[/up /health /healthz /ping /ready /livez /readyz]
       @pool_monitoring = false
       @pool_monitoring_interval = 30
       @queue_monitoring = false
       @queue_monitoring_interval = 60
       @request_summary = true
-      @timeline = true
+      @timeline = false
       @timeline_max_events = 200
       @memory_tracking = false
       @http_tracking = false
       @max_payload_bytes = 262_144 # 256 KB
       @trace_propagation = true
+      @log_forwarding = false
+      @view_tracking = false
+      @cache_tracking = false
+      @deprecation_tracking = false
+      @detailed_request_log = false
+      @sample_rate = 1.0     # Float 0.0-1.0, default 1.0 (all requests)
+      @sampler     = nil     # Proc(env) -> Float, for per-endpoint rates
+      @before_send = nil     # Proc(payload) -> payload|nil, filter/drop
+      @sql_normalization = true   # Normalize SQL queries (replace literals with ?)
+      @log_trace_injection = false # Inject trace_id/request_id into Rails logger
+      @source_context = false      # Capture source code context around errors
+      @before_breadcrumb = nil     # Proc(Breadcrumb) -> Breadcrumb|nil
+      @pii_scrubbing = false       # Scrub PII from metadata before sending
+      @pii_patterns = nil          # Array of additional Regexp patterns
+      @pii_disabled_patterns = nil # Array of Symbol pattern names to skip
+      @session_tracking = false    # Extract session ID from cookies
+      @on_error = nil              # Proc(exception, metadata) — called on error capture
+      @after_send = nil            # Proc(batch_size, bytes) — called after successful delivery
+      @transport = :http              # :http | :unix_socket
+      @socket_path = "/tmp/opentrace.sock" # Unix socket path
+      @local_vars_capture = false     # Capture local variables via explicit binding
+      @explain_slow_queries = false   # Run EXPLAIN on slow SQL queries
+      @explain_threshold_ms = 100.0   # Threshold for EXPLAIN capture
+      @runtime_metrics = false        # Collect GC/runtime metrics
+      @runtime_metrics_interval = 30  # Interval in seconds
+      @level_cache = nil
     end
 
     def valid?
@@ -74,12 +129,27 @@ module OpenTrace
       LEVELS[min_level.to_s.downcase.to_sym] || 0
     end
 
+    # Hot path: single hash lookup, zero allocations for known levels.
+    # Cache is built lazily on first call and invalidated when
+    # min_level or allowed_levels change.
     def level_allowed?(level)
-      if allowed_levels
-        allowed_levels.map { |l| l.to_s.upcase }.include?(level.to_s.upcase)
-      else
-        (LEVELS[level.to_s.downcase.to_sym] || 0) >= min_level_value
+      cache = @level_cache
+      unless cache
+        build_level_cache!
+        cache = @level_cache
       end
+      key = level.to_s.upcase
+      result = cache[key]
+      return result unless result.nil?
+      # Unknown level (e.g. "UNKNOWN"): treat as severity 0
+      return false if allowed_levels # not in the allowed list
+      0 >= (LEVELS[min_level.to_s.downcase.to_sym] || 0)
+    end
+
+    # Pre-compute the level cache. Called at end of configure block
+    # and lazily when settings change afterward.
+    def finalize!
+      build_level_cache!
     end
 
     # Maps OpenTrace min_level to Ruby Logger severity constant.
@@ -96,5 +166,20 @@ module OpenTrace
     def logger_severity
       LEVEL_TO_LOGGER_SEVERITY[min_level.to_s.downcase.to_sym] || 0
     end
+
+    private
+
+    def build_level_cache!
+      min_int = LEVELS[min_level.to_s.downcase.to_sym] || 0
+      if allowed_levels
+        @level_cache = allowed_levels.each_with_object({}) do |l, h|
+          h[l.to_s.upcase] = true
+        end.freeze
+      else
+        @level_cache = LEVEL_INTS.each_with_object({}) do |(k, v), h|
+          h[k] = v >= min_int
+        end.freeze
+      end
+    end
   end
 end

data/lib/opentrace/local_vars.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module OpenTrace
+  module LocalVars
+    MAX_VARS = 10
+    MAX_VALUE_LENGTH = 500
+
+    module_function
+
+    # Capture local variables from an explicit binding.
+    # Called by the user in their rescue blocks:
+    #
+    #   rescue => e
+    #     OpenTrace.capture_binding(e, binding)
+    #     raise
+    #   end
+    #
+    # Returns: Array of { name:, value:, type: } or nil
+    def capture(binding_obj)
+      return nil unless binding_obj.is_a?(Binding)
+
+      vars = binding_obj.local_variables.first(MAX_VARS)
+      vars.filter_map do |name|
+        # Skip internal variables (_, _1, etc.)
+        next if name.to_s.start_with?("_")
+
+        value = binding_obj.local_variable_get(name)
+        {
+          name: name.to_s,
+          value: safe_inspect(value),
+          type: value.class.name
+        }
+      end
+    rescue StandardError
+      nil
+    end
+
+    def safe_inspect(value)
+      str = value.inspect
+      str.length > MAX_VALUE_LENGTH ? str[0, MAX_VALUE_LENGTH] + "..." : str
+    rescue StandardError
+      "#<uninspectable>"
+    end
+  end
+end

data/lib/opentrace/middleware.rb

@@ -10,6 +10,16 @@ module OpenTrace
     end
 
     def call(env)
+      # When OpenTrace is disabled, pass through with zero overhead
+      return @app.call(env) unless OpenTrace.enabled?
+
+      # Sampling: skip ALL Fiber-local setup for unsampled requests.
+      # Subscribers check Fiber-locals and return instantly when nil.
+      unless OpenTrace.sampler.sample?(env)
+        OpenTrace.send(:client).stats.increment(:sampled_out)
+        return @app.call(env)
+      end
+
       request_id = env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
       OpenTrace.current_request_id = request_id
       Fiber[:opentrace_sql_count] = 0
@@ -25,15 +35,24 @@ module OpenTrace
         Fiber[:opentrace_parent_span_id] = parent_span_id
       end
 
-      # Create RequestCollector for accumulate-and-summarize pattern
-      if OpenTrace.enabled? && OpenTrace.config.request_summary
-        collector = OpenTrace::RequestCollector.new(
-          max_timeline: OpenTrace.config.timeline_max_events
-        )
+      # Session tracking (opt-in)
+      if OpenTrace.config.session_tracking
+        session_id = extract_session_id(env)
+        Fiber[:opentrace_session_id] = session_id if session_id
+      end
+
+      # Create RequestCollector only when features that need it are enabled
+      cfg = OpenTrace.config
+      needs_collector = cfg.request_summary &&
+        (cfg.view_tracking || cfg.cache_tracking || cfg.http_tracking ||
+         cfg.timeline || cfg.memory_tracking)
+
+      if needs_collector
+        max_timeline = cfg.timeline ? cfg.timeline_max_events : 0
+        collector = OpenTrace::RequestCollector.new(max_timeline: max_timeline)
         Fiber[:opentrace_collector] = collector
 
-        # Memory snapshot before request (opt-in)
-        if OpenTrace.config.memory_tracking
+        if cfg.memory_tracking
           collector.memory_before = current_rss_mb
         end
       end
@@ -53,6 +72,10 @@ module OpenTrace
       Fiber[:opentrace_trace_id] = nil
       Fiber[:opentrace_span_id] = nil
       Fiber[:opentrace_parent_span_id] = nil
+      Fiber[:opentrace_transaction_name] = nil
+      Fiber[:opentrace_breadcrumbs] = nil
+      Fiber[:opentrace_session_id] = nil
+      Fiber[:opentrace_pending_explains] = nil
       OpenTrace.current_request_id = nil
     end
 
@@ -88,6 +111,25 @@ module OpenTrace
       [TraceContext.generate_trace_id, nil]
     end
 
+    def extract_session_id(env)
+      # Try Rack session first
+      if (session = env["rack.session"])
+        return session.id.to_s if session.respond_to?(:id) && session.id
+      end
+
+      # Fall back to session cookie
+      cookie_name = env.dig("rack.session.options", :key) || "_session_id"
+      cookies = env["HTTP_COOKIE"]
+      if cookies
+        match = cookies.match(/#{Regexp.escape(cookie_name)}=([^;]+)/)
+        return match[1] if match
+      end
+
+      nil
+    rescue StandardError
+      nil
+    end
+
     def current_rss_mb
       if RUBY_PLATFORM.include?("linux")
         # Linux: read from /proc — no fork, ~10μs