bitfab 0.21.0 → 0.21.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7536f774b491c131b04a135a41c5f753c7c507615e54aa675c314cff785b08df
-  data.tar.gz: 47e7804161bc40563f5aca99147ef43d2af1af6d73d22f6ad3ae3402ea4b51f4
+  metadata.gz: 910352d2c5434b3fae7c3c56ccfea74dc0a22ce35d0cb4d2cb9d463e4ba3660b
+  data.tar.gz: 2e4e07a7447b75404e753f9a2d45350edfbee088ba100aff06031cf477cbc59c
 SHA512:
-  metadata.gz: 4aed7d077e6aa0ca89e8130b526578276591e60b41ae10670dc14db4eaca6221c30481dcad84acb8d7dfd7e549b2b92aa2c5a750efa36c4df85224b01360fe19
-  data.tar.gz: d73a3933eceba9c705fdab9f8b38f9f46766e026e59cdf61ee0ca2ea49a01ec4e5029fcbc87161a0a16602a2365ef3eeddba1acff27e659bf8fcf69b08d85138
+  metadata.gz: 1d197beb80ef3dcd1e57a8aebbe3aafd39ed000cadb0e1098ca71369d69ba53d4e805626f632b3bfdfb5f0cbe36d12e34d589f0b3def09be7e397bb1363e8b5e
+  data.tar.gz: 2f35b7eeba42eb86005e8cb9af3f46654313a84bc375e3c0edbd04e716cd8c511d0d302c2626d5f679b663f3482a24d8ec9b91d9b653fb2da6412aea0da2280b

data/lib/bitfab/client.rb

@@ -8,6 +8,7 @@ require_relative "http_client"
 require_relative "replay"
 require_relative "span_context"
 require_relative "serialize"
+require_relative "warn_once"
 
 module Bitfab
   class Client
@@ -101,59 +102,93 @@ module Bitfab
       mock_on_replay: false)
       return yield unless @enabled
 
-      parent = SpanContext.current
-      replay_ctx = ReplayContext.current
-      trace_id = parent ? parent[:trace_id] : (replay_ctx&.dig(:trace_id) || SecureRandom.uuid)
-      span_id = SecureRandom.uuid
-      parent_span_id = parent&.dig(:span_id)
-      is_root_span = parent_span_id.nil?
-      started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
-      resolved_test_run_id = replay_ctx&.dig(:test_run_id)
-      resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
-      resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)
-
-      # Register trace state for root spans
-      if is_root_span && !TraceState.get(trace_id)
-        TraceState.create(
-          trace_id,
-          test_run_id: resolved_test_run_id,
-          input_source_trace_id: resolved_input_source_trace_id
-        )
-      end
+      # Span setup runs before the user's block. Tracing is a side-channel, so
+      # if anything here raises (id generation, trace-state bookkeeping, a
+      # malformed replay mock tree) the user's method must still run. On failure
+      # we clean up any partially registered trace state, warn once, and run the
+      # block untraced. `trace_id` is declared out here so the rescue can clean
+      # it up; the other locals stay visible to the real path below.
+      trace_id = nil
+      span_id = nil
+      parent_span_id = nil
+      is_root_span = nil
+      started_at = nil
+      resolved_test_run_id = nil
+      resolved_input_source_span_id = nil
+      begin
+        parent = SpanContext.current
+        replay_ctx = ReplayContext.current
+        trace_id = parent ? parent[:trace_id] : (replay_ctx&.dig(:trace_id) || SecureRandom.uuid)
+        span_id = SecureRandom.uuid
+        parent_span_id = parent&.dig(:span_id)
+        is_root_span = parent_span_id.nil?
+        started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+        resolved_test_run_id = replay_ctx&.dig(:test_run_id)
+        resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
+        resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)
+
+        # Register trace state for root spans
+        if is_root_span && !TraceState.get(trace_id)
+          TraceState.create(
+            trace_id,
+            test_run_id: resolved_test_run_id,
+            input_source_trace_id: resolved_input_source_trace_id
+          )
+        end
 
-      if is_root_span
-        @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
-      end
+        if is_root_span
+          @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
+        end
 
-      # Advance the per-(key, name) call counter for any non-root span under
-      # an active mock tree, even when this span won't itself be mocked.
-      # Unmarked spans must consume an index so subsequent marked siblings
-      # line up with `build_mock_tree`'s sequential numbering for the same
-      # (key, name) pair. Different (key, name) pairs have independent
-      # counters: they cannot shift each other.
-      call_index = advance_mock_counter(replay_ctx, trace_function_key, span_name, is_root_span:)
-      if call_index
-        mocked_output = check_mock_replay(
-          replay_ctx, trace_function_key, span_name, call_index, mock_on_replay:
-        )
-        if mocked_output != MOCK_REPLAY_MISS
-          send_mocked_span(
-            trace_function_key:,
-            trace_id:,
-            span_id:,
-            parent_span_id:,
-            span_name:,
-            span_type:,
-            function_name:,
-            args:,
-            kwargs:,
-            mocked_output:,
-            started_at:,
-            test_run_id: resolved_test_run_id,
-            input_source_span_id: resolved_input_source_span_id
+        # Advance the per-(key, name) call counter for any non-root span under
+        # an active mock tree, even when this span won't itself be mocked.
+        # Unmarked spans must consume an index so subsequent marked siblings
+        # line up with `build_mock_tree`'s sequential numbering for the same
+        # (key, name) pair. Different (key, name) pairs have independent
+        # counters: they cannot shift each other.
+        call_index = advance_mock_counter(replay_ctx, trace_function_key, span_name, is_root_span:)
+        if call_index
+          mocked_output = check_mock_replay(
+            replay_ctx, trace_function_key, span_name, call_index, mock_on_replay:
           )
-          return mocked_output
+          if mocked_output != MOCK_REPLAY_MISS
+            send_mocked_span(
+              trace_function_key:,
+              trace_id:,
+              span_id:,
+              parent_span_id:,
+              span_name:,
+              span_type:,
+              function_name:,
+              args:,
+              kwargs:,
+              mocked_output:,
+              started_at:,
+              test_run_id: resolved_test_run_id,
+              input_source_span_id: resolved_input_source_span_id
+            )
+            return mocked_output
+          end
+        end
+      rescue
+        # Clean up any trace state this partial setup registered so it does not
+        # leak.
+        if trace_id
+          TraceState.delete(trace_id)
+          @pending_span_mutex.synchronize { @pending_span_threads.delete(trace_id) }
         end
+        # During replay (a controlled eval) a setup failure must surface, not
+        # silently run the block untraced: swallowing it would execute real code
+        # with real side effects and skew the mock call counter, defeating the
+        # replay. The never-crash fallback is for production hosts only.
+        raise if ReplayContext.current
+
+        Bitfab.warn_once(
+          "span-setup:#{trace_function_key}",
+          "span setup failed for '#{trace_function_key}'; this call runs untraced. " \
+          "Your method still executes and returns normally."
+        )
+        return yield
       end
 
       result = nil
@@ -390,9 +425,12 @@ module Bitfab
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
       span_name:, span_type:, function_name:, contexts:, prompt:, args:, kwargs:, result:, error:,
       started_at:, ended_at:, test_run_id: nil, input_source_span_id: nil)
-      # Human-readable JSON (input/output fields)
-      human_inputs = Serialize.serialize_inputs(args, kwargs)
-      human_output = Serialize.serialize_value(result)
+      # Human-readable JSON (input/output fields). The *_with_report variants
+      # also report what could not be faithfully captured so a lossy span is
+      # marked non-replayable below instead of shipping as if it round-trips.
+      human_inputs, input_dropped = Serialize.serialize_inputs_with_report(args, kwargs)
+      human_output, output_dropped = Serialize.serialize_value_with_report(result)
+      dropped = input_dropped + output_dropped
 
       # Marshal + Base64 for full Ruby-to-Ruby object reconstruction
       raw_input = (args.length == 1 && kwargs.empty?) ? args[0] : {args:, kwargs:}
@@ -434,6 +472,18 @@ module Bitfab
       }
       payload["testRunId"] = test_run_id if test_run_id
 
+      # A value that could only be captured as a placeholder makes the span
+      # non-replayable; record it on the payload's errors (matching the Python
+      # and TypeScript SDKs) instead of shipping the lossy capture silently.
+      unless dropped.empty?
+        names = dropped.uniq.sort.join(", ")
+        payload["errors"] = [{
+          "source" => "sdk",
+          "step" => "serialization_degraded",
+          "error" => "non-replayable: could not faithfully capture #{names}"
+        }]
+      end
+
       @http_client.send_external_span(payload) # Returns the background thread
     end
 

data/lib/bitfab/http_client.rb

@@ -7,6 +7,7 @@ require "uri"
 require_relative "constants"
 require_relative "serialize"
 require_relative "version"
+require_relative "warn_once"
 
 module Bitfab
   class HttpClient
@@ -181,14 +182,13 @@ module Bitfab
     def safe_generate(payload, endpoint)
       JSON.generate(payload)
     rescue => e
-      begin
-        warn "Bitfab: request body to #{endpoint} held a non-serializable " \
-             "value (#{e.message}); it was stubbed so the span still sends, " \
-             "but the trace may be incomplete or not replayable. Capture a " \
-             "JSON-safe projection of this input to make it replayable."
-      rescue
-        # Never crash the host app over a log line.
-      end
+      Bitfab.warn_once(
+        "request-body-stubbed",
+        "a request body held a non-serializable value (#{e.message}); it was " \
+        "stubbed so the span still sends, but the trace may be incomplete or " \
+        "not replayable. Capture a JSON-safe projection of this input to make " \
+        "it replayable."
+      )
 
       begin
         JSON.generate(sanitize_payload(payload))
@@ -242,11 +242,11 @@ module Bitfab
       thread = Thread.new do
         block.call
       rescue => e
-        begin
-          warn "Bitfab: Failed to send request: #{e.message}"
-        rescue
-          # Never crash the host app
-        end
+        Bitfab.warn_once(
+          "send-request-failed",
+          "failed to send a request to the backend (further occurrences " \
+          "suppressed): #{e.message}"
+        )
       ensure
         @pending_threads_mutex.synchronize { @pending_threads.delete(Thread.current) }
       end

data/lib/bitfab/serialize.rb

@@ -29,28 +29,44 @@ module Bitfab
     #   Without this the wire-side JSON.dump in the http client can produce a
     #   request that times out or gets rejected, leaving a trace with zero spans.
     def serialize_value(value)
-      result = serialize_value_inner(value, 0)
-      return result unless oversized?(result)
+      serialize_value_with_report(value).first
+    end
 
-      unserializable_stub(value, "too_large")
+    # Like serialize_value, but also reports what could not be faithfully
+    # captured. Returns [result, dropped] where dropped lists the class name (or
+    # "max_depth"/"too_large") behind every placeholder the walk had to emit. A
+    # non-empty dropped means the capture is lossy, so the send boundary marks
+    # the span serialization_degraded (non-replayable) instead of shipping it as
+    # if it round-trips. Mirrors the Python/TS SDKs' report serializers.
+    def serialize_value_with_report(value)
+      dropped = []
+      result = serialize_value_inner(value, 0, dropped)
+      if oversized?(result)
+        dropped << "too_large"
+        return [unserializable_stub(value, "too_large"), dropped]
+      end
+      [result, dropped]
     rescue StandardError, SystemStackError
-      unserializable_stub(value, "unexpected_error")
+      [unserializable_stub(value, "unexpected_error"), [class_name(value)]]
     end
 
-    def serialize_value_inner(value, depth)
-      return "<unserializable: max_depth>" if depth > MAX_SERIALIZE_DEPTH
+    def serialize_value_inner(value, depth, dropped = [])
+      if depth > MAX_SERIALIZE_DEPTH
+        dropped << "max_depth"
+        return "<unserializable: max_depth>"
+      end
 
       case value
       when nil, true, false, Integer, Float, String
         value
       when Hash
         value.each_with_object({}) do |(k, v), acc|
-          acc[safe_to_s(k)] = serialize_value_inner(v, depth + 1)
+          acc[safe_to_s(k)] = serialize_value_inner(v, depth + 1, dropped)
         end
       when Array
-        value.map { |v| serialize_value_inner(v, depth + 1) }
+        value.map { |v| serialize_value_inner(v, depth + 1, dropped) }
       when Set
-        value.map { |v| serialize_value_inner(v, depth + 1) }
+        value.map { |v| serialize_value_inner(v, depth + 1, dropped) }
       when Time, DateTime
         safely_call(value, "iso8601", 3) { safe_to_s(value) }
       when Date
@@ -59,16 +75,26 @@ module Bitfab
         value.to_s
       else
         if value.respond_to?(:to_h)
-          h = safely_call(value, "to_h") { return unserializable_stub(value, "to_h_raised") }
-          serialize_value_inner(h, depth + 1)
+          h = safely_call(value, "to_h") do
+            dropped << class_name(value)
+            return unserializable_stub(value, "to_h_raised")
+          end
+          serialize_value_inner(h, depth + 1, dropped)
         elsif value.respond_to?(:to_a)
-          a = safely_call(value, "to_a") { return unserializable_stub(value, "to_a_raised") }
-          serialize_value_inner(a, depth + 1)
+          a = safely_call(value, "to_a") do
+            dropped << class_name(value)
+            return unserializable_stub(value, "to_a_raised")
+          end
+          serialize_value_inner(a, depth + 1, dropped)
         else
+          # An arbitrary object with no structured conversion: stringifying it is
+          # a lossy capture (a repr, not its data), so report it as dropped.
+          dropped << class_name(value)
           safe_to_s(value)
         end
       end
     rescue StandardError, SystemStackError
+      dropped << class_name(value)
       unserializable_stub(value, "inner_error")
     end
 
@@ -108,14 +134,27 @@ module Bitfab
 
     # Serialize function inputs (args + kwargs) for span data (human-readable).
     def serialize_inputs(args, kwargs = {})
-      serialized = args.map { |arg| serialize_value(arg) }
+      serialize_inputs_with_report(args, kwargs).first
+    end
+
+    # Like serialize_inputs, but also returns the accumulated dropped list so the
+    # send boundary can mark a lossy capture non-replayable.
+    def serialize_inputs_with_report(args, kwargs = {})
+      dropped = []
+      serialized = args.map do |arg|
+        result, arg_dropped = serialize_value_with_report(arg)
+        dropped.concat(arg_dropped)
+        result
+      end
       unless kwargs.empty?
         kw = kwargs.each_with_object({}) do |(k, v), acc|
-          acc[safe_to_s(k)] = serialize_value(v)
+          result, v_dropped = serialize_value_with_report(v)
+          dropped.concat(v_dropped)
+          acc[safe_to_s(k)] = result
         end
         serialized << kw
       end
-      serialized
+      [serialized, dropped]
     end
 
     # Marshal a value to a Base64-encoded string for Ruby-to-Ruby reconstruction.

data/lib/bitfab/traceable.rb

@@ -173,7 +173,12 @@ module Bitfab
 
         wrapper = Module.new do
           define_method(method_name) do |*args, **kwargs, &block|
-            Bitfab.client.send(:execute_span,
+            # If Bitfab was never configured, run the real method untraced
+            # rather than raising a "not configured" error into the host app.
+            client = Bitfab.client_or_nil
+            return super(*args, **kwargs, &block) unless client
+
+            client.send(:execute_span,
               trace_function_key:,
               span_name:,
               span_type: type,

data/lib/bitfab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bitfab
-  VERSION = "0.21.0"
+  VERSION = "0.21.2"
 end

data/lib/bitfab/warn_once.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Bitfab
+  # Emit a warning at most once per distinct key for the life of the process.
+  #
+  # The SDK must never crash or spam the host app, so every failure on the
+  # user's path degrades quietly: a span is dropped, a call runs untraced, a
+  # payload is stubbed. Silent is safe but undebuggable; warning on every call
+  # from a hot path is its own problem. A one-time warning per distinct issue
+  # restores the signal without the flood. Keys should identify the specific
+  # degradation (e.g. include the trace_function_key) so each distinct issue
+  # warns once, not just the first one seen.
+  @warn_once_seen = Set.new
+  @warn_once_mutex = Mutex.new
+
+  class << self
+    def warn_once(key, message)
+      @warn_once_mutex.synchronize do
+        return if @warn_once_seen.include?(key)
+
+        @warn_once_seen.add(key)
+      end
+      begin
+        warn "Bitfab: #{message}"
+      rescue Exception # rubocop:disable Lint/RescueException
+        # Logging must never crash the host app (e.g. a closed $stderr).
+      end
+    end
+
+    # Test-only: clear the dedup set so a warning can fire again.
+    def _reset_warn_once
+      @warn_once_mutex.synchronize { @warn_once_seen.clear }
+    end
+  end
+end

data/lib/bitfab.rb

@@ -2,6 +2,7 @@
 
 require_relative "bitfab/version"
 require_relative "bitfab/constants"
+require_relative "bitfab/warn_once"
 require_relative "bitfab/serialize"
 require_relative "bitfab/db_snapshot"
 require_relative "bitfab/span_context"
@@ -65,6 +66,13 @@ module Bitfab
       @client or raise "Bitfab not configured. Call Bitfab.configure(api_key: '...') first."
     end
 
+    # Returns the global client, or nil if not configured. Used on the traced
+    # call path so a method invoked before Bitfab.configure runs untraced
+    # rather than crashing the host app with a "not configured" error.
+    def client_or_nil
+      @client
+    end
+
     # Reset the global client (primarily for testing).
     def reset!
       @client = nil

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.21.2
 platform: ruby
 authors:
 - Harvest Team
@@ -127,6 +127,7 @@ files:
 - lib/bitfab/span_context.rb
 - lib/bitfab/traceable.rb
 - lib/bitfab/version.rb
+- lib/bitfab/warn_once.rb
 homepage: https://bitfab.ai
 licenses:
 - MIT