bitfab 0.51.10 → 0.57.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c37ea054aa21aac4e6e10ff309ea4b7287ccf04b2b80692b4b260577d9f59ea9
-  data.tar.gz: 75f5892300254c708c9dac68cdb2a1cf125adf162a89c275e504546dca930cd4
+  metadata.gz: 1cd6fe2aaa2d03dea82e1d6a14b63e5a60eec3169c33489ce54795840ab6db8c
+  data.tar.gz: 1637726e4aa1cfa7940ecb65e1b10684b0d1236885a3c1ddd0d3748c8c7a874f
 SHA512:
-  metadata.gz: 7436cd4d8ff50ee5dc6625b7f7f645fc8c31a60d38b80ee69dc93306b59a3d2ef781b7d5282ce6dfc857c3e4166a992c07f73faa1960bbfa84e87e675a17e1ce
-  data.tar.gz: 2a5503c884dafc47cab0d23373265ebac0810bb2672868677b5335093eb7d47ed86e4a77dcd7e828e7222db52efbbf7196d312ffb5864aceadf3833f769f0cf9
+  metadata.gz: 391ca0dbc155bf7826f8ff4245d305d6d426cd8cd330a2c92564de8eac72ee229d928faad6d74f72f3d7163cf8a950fab1c6dfc96c5ddefdbd215ba0167382a1
+  data.tar.gz: c8a4c5172ecb6f78b309303062167073384bbdd7079c5fc5618200b877526a44bd495f85b2e6120b9a602542f883b80d2872ba2519f81109d3e17d83977b301f

data/README.md

@@ -235,7 +235,7 @@ class OrderPipeline
 end
 ```
 
-Capture uses `TracePoint` only during the root call. It skips Ruby/runtime code, dependency gems, Bitfab SDK internals, blocks, lambdas, and forwarding wrappers. When the root belongs to an installed application gem, that gem is the first-party boundary; neighboring dependency gems remain excluded. It follows recursion, modules, inheritance, `define_method`, and same-thread child Fibers; aliases are recorded and excluded by the name that was invoked. Child Fibers created during capture inherit node policies, trace identity, parenting, and depth limits while retaining separate call stacks. Pre-existing Fibers, `Fiber.new(storage: nil)`, and child threads do not inherit subtree context. When an inner capture ends, child Fibers retain any still-active outer capture; inherited context expires once all enclosing captures end. While a root remains active, hitting `max_spans` stops new capture but allows already-open spans in every Fiber to finish. `max_depth:`, `max_spans:`, `exclude:`, and `include_wrappers:` control the subtree. Automatically captured calls are not replay mock targets. Declare a call with `bitfab_node` when replay must substitute it. The configured node records once in each enclosing trace. Mixing explicit spans with subtree tracing raises `Bitfab::MixedTracingError`.
+Capture uses `TracePoint` only during the root call. It skips Ruby/runtime code, dependency gems, Bitfab SDK internals, blocks, lambdas, and forwarding wrappers. When the root belongs to an installed application gem, that gem is the first-party boundary; neighboring dependency gems remain excluded. It follows recursion, modules, inheritance, `define_method`, and same-thread child Fibers; aliases are recorded and excluded by the name that was invoked. Child Fibers created during capture inherit node policies, trace identity, parenting, and depth limits while retaining separate call stacks. Pre-existing Fibers, `Fiber.new(storage: nil)`, and child threads do not inherit subtree context. When an inner capture ends, child Fibers retain any still-active outer capture; inherited context expires once all enclosing captures end. While a root remains active, hitting a span limit stops new capture but allows already-open spans in every Fiber to finish. `max_depth:` (default `30`), `max_captured_subtree_spans:` (default `512`), `max_spans:` (default `2048`), `exclude:`, and `include_wrappers:` control the subtree. `max_spans:` is a strict cap on the total number of spans one trace root sends. It counts the root span itself, discovered calls, `bitfab_node` calls, nested trace roots, and spans whose capture is on or off, including spans sent without inputs and outputs because the sim plan could not be read. Nothing past it is sent. It must be at least 1, and a lower value raises `ArgumentError`. `max_captured_subtree_spans:` caps discovered calls sent with their inputs and outputs. It does not count `bitfab_node` calls, nested trace roots, or spans the loaded sim plan turned capture off for, so those keep recording past it up to `max_spans:`. Spans sent without inputs and outputs only because the sim plan could not be read still count toward it. Past it, further discovered calls with capture on record nothing. It is never higher than `max_spans:`. Once the plan has loaded, the SDK never builds the inputs or outputs of a span whose capture it turned off. The client starts reading the sim plan when it is built. A `bitfab_trace` root that starts while that first read is still running waits for it, for at most five seconds. Once the first read has finished, whether it succeeded or failed, no later root waits. Nested roots and the calls beneath a root never wait, and nothing waits when the plan is disabled. If that first read fails, spans other than each trace's root span are sent without inputs and outputs until a read succeeds, and they still count toward both limits. Automatically captured calls are not replay mock targets. Declare a call with `bitfab_node` when replay must substitute it. The configured node records once in each enclosing trace. Mixing explicit spans with subtree tracing raises `Bitfab::MixedTracingError`.
 
 When capture ends, already-open automatic calls in suspended Fibers are emitted once with a nil output and `Subtree capture ended before the call returned` as the error, unless a real error was already observed. Their inputs and parenting are retained. The SDK does not resume Fibers, and later resumption cannot add spans to the ended capture. If hot reload moves the root to an unresolved source, the last valid first-party boundary and its exclusions remain in use.
 
@@ -258,7 +258,7 @@ end
 
 Nodes support `name:`, `type:`, `capture:`, `test_run_id:`, `mock_on_replay:`, and `finalize:`. `capture: false` omits the method while attaching captured descendants to its nearest visible parent. `finalize:` changes only the recorded output, never the return value. A finalizer failure is recorded on the node without crashing the caller. The before-`def`, inline, and after-`def` forms all preserve method visibility. For external code, use `Bitfab.client.node(MyClass, :method)`.
 
-`bitfab_trace` prepares its project boundary and exclusions when the method is declared, refreshes the boundary if the root definition moves during hot reload, caches canonical source paths, and shares one `TracePoint` dispatcher across active roots on the calling thread. After `max_spans` is exhausted, it stops collecting metadata and values immediately, then stops processing events for that session once its captured calls finish. Each active root still captures and serializes its own copy of every overlapping call, so this remains a discovery tool rather than the production default. Prefer explicit `bitfab_span` declarations on hot paths. Run `mise exec -- ruby -Ilib benchmark/subtree.rb` from this package to measure the no-network caller path on your Ruby build.
+`bitfab_trace` prepares its project boundary and exclusions when the method is declared, refreshes the boundary if the root definition moves during hot reload, caches canonical source paths, and shares one `TracePoint` dispatcher across active roots on the calling thread. After a span limit is reached, it stops reading inputs and outputs immediately, then stops processing events for that session once its captured calls finish. Each active root still captures and serializes its own copy of every overlapping call, so this remains a discovery tool rather than the production default. Prefer explicit `bitfab_span` declarations on hot paths. Run `mise exec -- ruby -Ilib benchmark/subtree.rb` from this package to measure the no-network caller path on your Ruby build.
 
 ### Input/Output Capture
 

data/lib/bitfab/client.rb

@@ -379,7 +379,8 @@ module Bitfab
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
       capture_when: "always", mock_on_replay: false, independent_root: false,
       explicit_span_receiver: nil, explicit_span_method_name: nil, test_run_id: nil, finalize: nil,
-      surface: nil, on_start: nil, on_complete: nil, around_body: nil, span_data: {}, managed_root: false)
+      surface: nil, on_start: nil, on_complete: nil, around_body: nil, span_data: {}, managed_root: false,
+      result_recorded_elsewhere: false)
       # Decide at CALL time, not construction. The key may be set after the
       # client is built (env loaded later), so re-checking per call lets a
       # late-resolved key take effect.
@@ -525,7 +526,12 @@ module Bitfab
           ended_at = Bitfab.now_iso_timestamp
           recorded_result = final_result
           recorded_error = final_error
-          if finalize && final_error.nil?
+          recorded_name = recording_override&.dig(:name) || span_name
+          recorded_instrumentation = recording_override&.dig(:instrumentation) || ((surface == :trace) ? "trace" : "span")
+          content_off = content_off_by_simulation_plan?(
+            trace_id:, trace_function_key:, span_name: recorded_name, instrumentation: recorded_instrumentation
+          ) || (!parent_span_id.nil? && simulation_plan_unavailable?(instrumentation: recorded_instrumentation))
+          if finalize && final_error.nil? && !(content_off && !result_recorded_elsewhere)
             begin
               recorded_result = finalize.call(final_result)
             rescue => e
@@ -537,13 +543,13 @@ module Bitfab
           on_complete&.call(result: recorded_result, error: recorded_error, ended_at:)
 
           send_span(
-            span_data:,
-            instrumentation: recording_override&.dig(:instrumentation) || ((surface == :trace) ? "trace" : "span"),
+            span_data: content_off ? span_data.merge("content_off_by_simulation_plan" => true) : span_data,
+            instrumentation: recorded_instrumentation,
             trace_function_key:,
             trace_id:,
             span_id:,
             parent_span_id:,
-            span_name: recording_override&.dig(:name) || span_name,
+            span_name: recorded_name,
             span_type: recording_override&.dig(:type) || span_type,
             function_name: recording_override&.dig(:function_name) || function_name,
             contexts: span_contexts,
@@ -672,6 +678,32 @@ module Bitfab
       raise ArgumentError, "id must be a valid Bitfab span ID" unless id.is_a?(String) && UUID_PATTERN.match?(id)
     end
 
+    def content_off_by_simulation_plan?(trace_id:, trace_function_key:, span_name:, instrumentation: "span")
+      return false if SimulationPlan::FRAMEWORKS.include?(instrumentation)
+
+      @http_client.simulation_plan_content_off?(root_trace_function_key(trace_id, trace_function_key), span_name)
+    end
+
+    def simulation_plan_unavailable?(instrumentation: "span")
+      return false if SimulationPlan::FRAMEWORKS.include?(instrumentation)
+
+      @http_client.simulation_plan_unavailable?
+    end
+
+    def simulation_plan_content_off_names?(trace_id:, trace_function_key:)
+      @http_client.simulation_plan_content_off_names?(root_trace_function_key(trace_id, trace_function_key))
+    end
+
+    def root_trace_function_key(trace_id, trace_function_key)
+      TraceState.get(trace_id)&.dig(:trace_function_key) || trace_function_key
+    end
+
+    def wait_for_simulation_plan
+      @http_client.wait_for_simulation_plan
+    rescue
+      nil
+    end
+
     # Resolve the API key lazily, the first time a span actually needs it.
     #
     # The key is intentionally NOT read at construction: a client built when a
@@ -890,25 +922,34 @@ module Bitfab
       # 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:}
-      marshalled_input = Serialize.marshal_value(raw_input)
-      marshalled_output = Serialize.marshal_value(result)
-
-      span_data = {
-        "name" => span_name,
-        "type" => span_type,
-        "input" => human_inputs,
-        "output" => human_output,
-        "function_name" => function_name
-      }
-      span_data.merge!(extra_span_data)
-      span_data["input_serialized"] = marshalled_input if marshalled_input
-      span_data["output_serialized"] = marshalled_output if marshalled_output
+      content_off = extra_span_data["content_off_by_simulation_plan"] == true ||
+        content_off_by_simulation_plan?(trace_id:, trace_function_key:, span_name:, instrumentation:) ||
+        (!parent_span_id.nil? && simulation_plan_unavailable?(instrumentation:))
+      if content_off
+        dropped = []
+        span_data = {"name" => span_name, "type" => span_type, "function_name" => function_name}
+        span_data.merge!(extra_span_data.except(*SimulationPlan::CONTENT_KEYS))
+        span_data["content_off_by_simulation_plan"] = true
+      else
+        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
+
+        raw_input = (args.length == 1 && kwargs.empty?) ? args[0] : {args:, kwargs:}
+        marshalled_input = Serialize.marshal_value(raw_input)
+        marshalled_output = Serialize.marshal_value(result)
+
+        span_data = {
+          "name" => span_name,
+          "type" => span_type,
+          "input" => human_inputs,
+          "output" => human_output,
+          "function_name" => function_name
+        }
+        span_data.merge!(extra_span_data)
+        span_data["input_serialized"] = marshalled_input if marshalled_input
+        span_data["output_serialized"] = marshalled_output if marshalled_output
+      end
       if error
         span_data["error"] = error
         span_data["error_source"] = "code"
@@ -1172,6 +1213,7 @@ module Bitfab
     # Experimentally trace an existing method and its first-party call subtree.
     def trace(klass, method_name, name: nil, type: "custom",
       max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+      max_captured_subtree_spans: Subtree::DEFAULT_MAX_CAPTURED_SUBTREE_SPANS,
       exclude: [], include_wrappers: false, mock_on_replay_default: false)
       Bitfab::Traceable.trace(
         klass, method_name,
@@ -1180,6 +1222,7 @@ module Bitfab
         type:,
         max_depth:,
         max_spans:,
+        max_captured_subtree_spans:,
         exclude:,
         include_wrappers:,
         mock_on_replay_default:,

data/lib/bitfab/http_client.rb

@@ -55,12 +55,30 @@ module Bitfab
 
     def configure_simulation_plan(enabled: true)
       @simulation_plan = SimulationPlan.new(self, enabled:)
+      @simulation_plan.refresh
+      @simulation_plan
     end
 
     def refresh_simulation_plan
       @simulation_plan&.refresh
     end
 
+    def wait_for_simulation_plan
+      @simulation_plan&.wait_for_first_read
+    end
+
+    def simulation_plan_content_off?(trace_function_key, span_name)
+      @simulation_plan&.content_off?(trace_function_key, span_name) == true
+    end
+
+    def simulation_plan_content_off_names?(trace_function_key)
+      @simulation_plan&.content_off_names?(trace_function_key) == true
+    end
+
+    def simulation_plan_unavailable?
+      @simulation_plan&.unavailable? == true
+    end
+
     def get_simulation_plan
       get("/api/sdk/sim-plan", timeout: SimulationPlan::READ_TIMEOUT, connection_close: true)
     end
@@ -82,8 +100,8 @@ module Bitfab
       result = false
       begin
         remaining = [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
-        released = @simulation_plan.nil? || @simulation_plan.release([remaining / 2.0, SimulationPlan::READ_TIMEOUT].min)
-        @simulation_plan&.stop
+        @simulation_plan&.release([remaining / 2.0, SimulationPlan::READ_TIMEOUT].min)
+        released = @simulation_plan.nil? || @simulation_plan.stop
         remaining = [deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max
         transport = @transport_mutex.synchronize do
           current = @transport

data/lib/bitfab/otel.rb

@@ -26,7 +26,7 @@ module Bitfab
     MAX_DECOMPRESSED_REQUEST_BYTES = 8_000_000
     MAX_QUEUE_SIZE = 8_192
     DIRECT_MAX_EXPORT_BATCH_SIZE = 512
-    DIRECT_MAX_REQUEST_BATCH_SIZE = 8
+    DIRECT_MAX_REQUEST_BATCH_SIZE = 128
     DEFAULT_EXPORT_CONCURRENCY = 32
     MAX_EXPORT_CONCURRENCY = 64
     SCHEDULE_DELAY_MILLIS = 5_000

data/lib/bitfab/simulation_plan.rb

@@ -25,8 +25,8 @@ module Bitfab
         released = true
         plans.each do |plan|
           result = plan.release([deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC), 0].max)
+          result = plan.stop if stop
           released = result && released
-          plan.stop if stop
         end
         released
       end
@@ -53,6 +53,7 @@ module Bitfab
       @held = []
       @draining = Set.new
       @stopped = false
+      @first_read_finished = false
       self.class.register(self)
     end
 
@@ -71,29 +72,27 @@ module Bitfab
       refresh
       data = payload.dig("rawSpan", "span_data")
       key = payload["rootTraceFunctionKey"] || payload["traceFunctionKey"]
-      if disabled? || @stopped || key.nil? || !data.is_a?(Hash) || framework?(payload)
+      if disabled? || key.nil? || !data.is_a?(Hash) || framework?(payload)
         submit.call(payload)
         return
       end
-      held = @mutex.synchronize do
-        if @content_off.nil?
-          hold([payload, key, submit])
-          true
-        end
-      end
-      submit.call(apply(payload, key)) unless held
+      entry = [payload, key, submit]
+      ready = @mutex.synchronize { reading? ? hold(entry) : entry }
+      deliver(*ready) if ready
     end
 
     def send_trace(payload, &submit)
       refresh
-      held = @mutex.synchronize do
+      entry = [payload, nil, submit]
+      ready = @mutex.synchronize do
         id = trace_id(payload)
-        if !disabled? && !@stopped && id && (@draining.include?(id) || @held.any? { |entry| entry[1] && trace_id(entry[0]) == id })
-          hold([payload, nil, submit])
-          true
+        if !disabled? && !@stopped && id && (@draining.include?(id) || @held.any? { |held| held[1] && trace_id(held[0]) == id })
+          hold(entry)
+        else
+          entry
         end
       end
-      submit.call(payload) unless held
+      deliver(*ready) if ready
     end
 
     def release(timeout)
@@ -114,10 +113,48 @@ module Bitfab
 
     def stop
       reset_after_fork
-      @mutex.synchronize do
+      queued = @mutex.synchronize do
         @stopped = true
-        @held.clear
         @condition.broadcast
+        entries, @held = @held, []
+        entries
+      end
+      queued.each { |entry| deliver_safely(*entry) }
+      @mutex.synchronize { @held.empty? && @draining.empty? }
+    end
+
+    def content_off?(key, name)
+      reset_after_fork
+      return false if disabled? || @stopped
+
+      @mutex.synchronize { @content_off&.fetch(key, nil)&.include?(name) == true }
+    end
+
+    def content_off_names?(key)
+      reset_after_fork
+      return false if disabled? || @stopped
+
+      @mutex.synchronize { @content_off&.fetch(key, nil)&.any? == true }
+    end
+
+    def unavailable?
+      reset_after_fork
+      return false if disabled?
+
+      @mutex.synchronize { @content_off.nil? && !reading? }
+    end
+
+    def wait_for_first_read(timeout = READ_TIMEOUT)
+      reset_after_fork
+      return if disabled?
+
+      deadline = now + [timeout, 0].max
+      @mutex.synchronize do
+        while reading? && @thread
+          remaining = deadline - now
+          break unless remaining.positive?
+          @condition.wait(@mutex, remaining)
+        end
       end
     end
 
@@ -128,9 +165,7 @@ module Bitfab
       data = payload.dig("rawSpan", "span_data")
       return payload unless data.is_a?(Hash) && names&.include?(data["name"])
 
-      kept = data.except(*CONTENT_KEYS)
-      kept["content_off_by_simulation_plan"] = true
-      payload.merge("rawSpan" => payload["rawSpan"].merge("span_data" => kept))
+      without_content(payload, data)
     end
 
     private
@@ -139,6 +174,10 @@ module Bitfab
       Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    def reading?
+      @content_off.nil? && !@first_read_finished && !@stopped
+    end
+
     def trace_id(payload)
       payload["traceId"] || payload["sourceTraceId"] || payload.dig("externalTrace", "id") || payload["id"]
     end
@@ -147,19 +186,53 @@ module Bitfab
       FRAMEWORKS.include?(payload.dig("rawSpan", "span_origin", "instrumentation", "name"))
     end
 
+    def root?(payload)
+      payload.dig("rawSpan", "parent_id").nil?
+    end
+
     def hold(entry)
       @held << entry
-      if @held.length > MAX_HELD
-        @held.shift
-        Bitfab.warn_once("sim-plan-held-overflow", "Simulation plan has not loaded; dropping oldest records beyond #{MAX_HELD}")
-      end
       start_reader([@refresh_after - now, 0].max) if @thread.nil? && !@stopped && !disabled?
+      @held.shift if @held.length > MAX_HELD
+    end
+
+    def deliver(payload, key, submit)
+      submit.call(prepare(payload, key))
+    end
+
+    def deliver_safely(payload, key, submit)
+      deliver(payload, key, submit)
+    rescue => error
+      Bitfab.warn_once("sim-plan-held-span-dropped", "Held record could not be sent: #{error}")
+    end
+
+    def prepare(payload, key)
+      return payload if key.nil? || disabled?
+      return apply(payload, key) if @mutex.synchronize { @content_off }
+
+      without_unread_content(payload)
+    end
+
+    def without_unread_content(payload)
+      data = payload.dig("rawSpan", "span_data")
+      return payload if !data.is_a?(Hash) || root?(payload) || framework?(payload)
+
+      Bitfab.warn_once("sim-plan-unread-content",
+        "Sending spans without inputs and outputs because the simulation plan could not be read")
+      without_content(payload, data)
+    end
+
+    def without_content(payload, data)
+      kept = data.except(*CONTENT_KEYS)
+      kept["content_off_by_simulation_plan"] = true
+      payload.merge("rawSpan" => payload["rawSpan"].merge("span_data" => kept))
     end
 
     def start_reader(delay)
       @thread = Thread.new { read_until_loaded(delay) }
       @thread.name = "bitfab-sim-plan"
     rescue ThreadError
+      @first_read_finished = true
       @refresh_after = now + RETRY_SECONDS
     end
 
@@ -175,7 +248,7 @@ module Bitfab
     def read_once
       body = @reader.get_simulation_plan
       unless body.is_a?(Hash) && body["nodes"].is_a?(Array)
-        Bitfab.warn_once("sim-plan-unreadable", "Simulation plan response was not understood; holding content until it loads")
+        Bitfab.warn_once("sim-plan-unreadable", "Simulation plan response was not understood; sending spans without inputs and outputs until it loads")
         return
       end
       names = {}
@@ -187,49 +260,35 @@ module Bitfab
     rescue => error
       return {} if error.respond_to?(:response) && error.response&.code.to_i == 404
 
-      Bitfab.warn_once("sim-plan-unavailable", "Could not read simulation plan: #{error}; holding content until it loads")
+      Bitfab.warn_once("sim-plan-unavailable", "Could not read simulation plan: #{error}; sending spans without inputs and outputs until it loads")
       nil
     end
 
     def read_until_loaded(delay)
       pause(delay) if delay.positive?
-      loop do
-        parsed = (disabled? || @stopped) ? nil : read_once
-        finished, entries = @mutex.synchronize do
-          if parsed
-            @content_off = parsed
-            @refresh_after = now + REFRESH_SECONDS
-            queued, @held = @held, []
-            @draining = queued.filter_map { |payload, key, _| trace_id(payload) if key }.to_set
-            [true, queued]
-          elsif @content_off || disabled? || @stopped || @held.empty?
-            @refresh_after = now + RETRY_SECONDS
-            [true, []]
-          else
-            [false, []]
-          end
-        end
-        if finished
-          until entries.empty?
-            entries.each do |payload, key, submit|
-              submit.call(key ? apply(payload, key) : payload)
-            rescue => error
-              Bitfab.warn_once("sim-plan-held-span-dropped", "Held record could not be sent: #{error}")
-            end
-            entries = @mutex.synchronize do
-              queued, @held = @held, []
-              @draining.clear if queued.empty?
-              queued
-            end
-          end
-          return
+      parsed = (disabled? || @stopped) ? nil : read_once
+      entries = @mutex.synchronize do
+        @first_read_finished = true
+        @content_off = parsed if parsed
+        @refresh_after = now + (parsed ? REFRESH_SECONDS : RETRY_SECONDS)
+        queued, @held = @held, []
+        @draining = queued.filter_map { |payload, key, _| trace_id(payload) if key }.to_set
+        @condition.broadcast
+        queued
+      end
+      until entries.empty?
+        entries.each { |entry| deliver_safely(*entry) }
+        entries = @mutex.synchronize do
+          queued, @held = @held, []
+          @draining.clear if queued.empty?
+          queued
         end
-        pause(RETRY_SECONDS)
       end
     ensure
       @mutex.synchronize do
         @draining.clear
         @thread = nil
+        @first_read_finished = true
         @condition.broadcast
       end
     end

data/lib/bitfab/subtree.rb

@@ -10,7 +10,8 @@ module Bitfab
 
   module Subtree
     DEFAULT_MAX_DEPTH = 30
-    DEFAULT_MAX_SPANS = 500
+    DEFAULT_MAX_SPANS = 2048
+    DEFAULT_MAX_CAPTURED_SUBTREE_SPANS = 512
     SESSION_KEY = :bitfab_subtree_session
     DISPATCHER_KEY = :bitfab_subtree_dispatcher
     FIBER_CONTEXT_KEY = :bitfab_subtree_fiber_context
@@ -98,6 +99,10 @@ module Bitfab
         @owner = @records.find { |_, entry, _| entry }&.first unless nested_trace_key
       end
 
+      def recorded_elsewhere?
+        @records.any? { |session, entry, _| entry && !session.equal?(@owner) }
+      end
+
       def start(trace_id:, span_id:)
         @records.each do |session, entry, _|
           next unless entry
@@ -170,7 +175,7 @@ module Bitfab
     end
 
     def capture(client:, trace_function_key:, config:, max_depth:, max_spans:, include_wrappers:,
-      root_receiver:, root_method_name:, mock_on_replay_default: false)
+      root_receiver:, root_method_name:, max_captured_subtree_spans: DEFAULT_MAX_CAPTURED_SUBTREE_SPANS, mock_on_replay_default: false)
       return yield unless config.root
 
       span = SpanContext.current || ReplayContext.current_span
@@ -188,6 +193,7 @@ module Bitfab
           config:,
           max_depth:,
           max_spans:,
+          max_captured_subtree_spans:,
           include_wrappers:,
           mock_on_replay_default:,
           root_receiver:,
@@ -412,7 +418,7 @@ module Bitfab
 
       def initialize(client:, trace_function_key:, trace_id:, root_span_id:, test_run_id:,
         input_source_span_id:, config:, max_depth:, max_spans:, include_wrappers:,
-        root_receiver:, root_method_name:, mock_on_replay_default: false)
+        root_receiver:, root_method_name:, max_captured_subtree_spans: DEFAULT_MAX_CAPTURED_SUBTREE_SPANS, mock_on_replay_default: false)
         @mock_on_replay_default = mock_on_replay_default
         @client = client
         @trace_function_key = trace_function_key
@@ -427,6 +433,7 @@ module Bitfab
         @skip_root_call = true
         @max_depth = max_depth
         @max_spans = max_spans
+        @max_captured_subtree_spans = [max_captured_subtree_spans, max_spans].min
         @exclude = config.exclude
         @include_wrappers = include_wrappers
         @stacks = {}
@@ -435,7 +442,8 @@ module Bitfab
         @suppressed_depths = {}
         @owned_paths = {}
         @method_metadata = Hash.new { |owners, owner| owners[owner] = {} }
-        @spans_used = 0
+        @spans_used = 1
+        @captured_subtree_count = 0
         @truncated = false
         @exhausted = false
         @drained = false
@@ -518,14 +526,11 @@ module Bitfab
           @truncated = true
           return false
         end
-        if @spans_used >= @max_spans
-          @truncated = true
-          @exhausted = true
-          return false
-        end
+        return true if take_slot(discovered: false)
 
-        @spans_used += 1
-        true
+        @truncated = true
+        @exhausted = true
+        false
       end
 
       def configured_entry(name:, type:, args:, kwargs:, test_run_id:)
@@ -637,14 +642,10 @@ module Bitfab
           suppress(fiber_id)
           return
         end
-        if @spans_used >= @max_spans
+        content_off = content_off?(metadata.name)
+        if (limit = limit_reached(discovered: true, content_off:))
           @truncated = true
-          @exhausted = true
-          if captured_calls_drained?
-            @drained = true
-          else
-            suppress(fiber_id)
-          end
+          stop_discovery(fiber_id) unless limit == :max_captured_subtree_spans && content_off_names?
           return
         end
 
@@ -655,9 +656,10 @@ module Bitfab
           return
         end
 
-        @spans_used += 1
+        count_span(discovered: true, content_off:)
         span_id = SecureRandom.uuid
-        args, kwargs = inputs(event)
+        without_content = content_off || plan_unavailable?
+        args, kwargs = without_content ? [[], {}] : inputs(event)
         # A nested subtree root temporarily owns the ambient span context, but
         # an outer session must never parent its spans across trace boundaries.
         active_parent_span_id = if active_parent&.dig(:trace_id) == @trace_id
@@ -671,7 +673,8 @@ module Bitfab
           name: metadata.name,
           args:,
           kwargs:,
-          started_at: now
+          started_at: now,
+          span_data: without_content ? {"content_off_by_simulation_plan" => true} : nil
         )
       end
 
@@ -878,14 +881,60 @@ module Bitfab
         @suppressed_depths[fiber_id] = 1
       end
 
+      def limit_reached(discovered:, content_off: false)
+        return :max_spans if @spans_used >= @max_spans
+
+        :max_captured_subtree_spans if discovered && !content_off && @captured_subtree_count >= @max_captured_subtree_spans
+      end
+
+      def take_slot(discovered:)
+        return false if limit_reached(discovered:)
+
+        count_span(discovered:, content_off: false)
+        true
+      end
+
+      def count_span(discovered:, content_off:)
+        @spans_used += 1
+        @captured_subtree_count += 1 if discovered && !content_off
+      end
+
+      def stop_discovery(fiber_id)
+        @exhausted = true
+        if captured_calls_drained?
+          @drained = true
+        else
+          suppress(fiber_id)
+        end
+      end
+
+      def content_off?(name)
+        @client.send(:content_off_by_simulation_plan?, trace_id: @trace_id, trace_function_key: @trace_function_key,
+          span_name: name, instrumentation: "trace")
+      rescue
+        false
+      end
+
+      def content_off_names?
+        @client.send(:simulation_plan_content_off_names?, trace_id: @trace_id, trace_function_key: @trace_function_key)
+      rescue
+        false
+      end
+
+      def plan_unavailable?
+        @client.send(:simulation_plan_unavailable?, instrumentation: "trace")
+      rescue
+        false
+      end
+
       def warn_if_truncated
         return unless @truncated
 
         Bitfab.warn_once(
           "subtree-truncated:#{@trace_function_key}",
           "'#{@trace_function_key}' hit a subtree capture limit (max_depth=#{@max_depth}, " \
-          "max_spans=#{@max_spans}) and its trace is incomplete. Raise the limits, or narrow " \
-          "what is traced with exclude: [...]."
+          "max_captured_subtree_spans=#{@max_captured_subtree_spans}, max_spans=#{@max_spans}) and its trace is incomplete. " \
+          "Raise the limits, add bitfab_node to the calls that matter, or narrow what is traced with exclude: [...]."
         )
       end
 

data/lib/bitfab/traceable.rb

@@ -83,7 +83,9 @@ module Bitfab
     # beneath it record automatically as function spans.
     def self.trace(klass, method_name, trace_function_key:, name: nil, type: "custom",
       max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+      max_captured_subtree_spans: Subtree::DEFAULT_MAX_CAPTURED_SUBTREE_SPANS,
       exclude: [], include_wrappers: false, mock_on_replay_default: false, client: nil)
+      validate_trace_options!(max_spans:)
       capture_config = Subtree.prepare(root_source: source_of(klass, method_name), exclude:)
       method_name_str = method_name.to_s
       bound_client = client
@@ -95,6 +97,8 @@ module Bitfab
           Subtree.assert_surface!(:trace)
           next super(*args, **kwargs, &block) if Subtree.nested_root_suppressed?
 
+          target_client.send(:wait_for_simulation_plan) unless Subtree.current_session
+
           span_name = name || Subtree.qualified_name(self, method_name)
           managed = SpanContext.current&.dig(:recording_override)
           if managed && managed.empty? && (ReplayContext.current || SeedContext.current)
@@ -102,7 +106,7 @@ module Bitfab
             SpanContext.current[:surface] = :trace
             next Subtree.capture(
               client: target_client, trace_function_key:, config: capture_config,
-              max_depth:, max_spans:, include_wrappers:, mock_on_replay_default:,
+              max_depth:, max_spans:, max_captured_subtree_spans:, include_wrappers:, mock_on_replay_default:,
               root_receiver: self, root_method_name: method_name
             ) { super(*args, **kwargs, &block) }
           end
@@ -116,7 +120,7 @@ module Bitfab
             around_body: call.method(:run)) do
             Subtree.capture(
               client: target_client, trace_function_key:, config: capture_config,
-              max_depth:, max_spans:, include_wrappers:, mock_on_replay_default:,
+              max_depth:, max_spans:, max_captured_subtree_spans:, include_wrappers:, mock_on_replay_default:,
               root_receiver: self, root_method_name: method_name
             ) { super(*args, **kwargs, &block) }
           end
@@ -161,7 +165,7 @@ module Bitfab
               span_name:, span_type: type, function_name: method_name_str,
               args:, kwargs:, capture_when: "nested", mock_on_replay: policy,
               explicit_span_receiver: self, explicit_span_method_name: method_name,
-              test_run_id:, finalize:, surface: :trace,
+              test_run_id:, finalize:, surface: :trace, result_recorded_elsewhere: call.recorded_elsewhere?,
               on_start: call.method(:start), on_complete: call.method(:complete),
               around_body: call.method(:run)) { super(*args, **kwargs, &block) }
           end
@@ -189,6 +193,14 @@ module Bitfab
     end
     private_class_method :preserve_visibility
 
+    def self.validate_trace_options!(max_spans:)
+      return if max_spans.is_a?(Integer) && max_spans >= 1
+
+      raise ArgumentError,
+        "bitfab_trace max_spans must be an integer of at least 1 because the root span takes one slot, got #{max_spans.inspect}."
+    end
+    private_class_method :validate_trace_options!
+
     def self.validate_node_options!(capture:, mock_on_replay:)
       return unless !capture && mock_on_replay
 
@@ -293,7 +305,9 @@ module Bitfab
       # Descendants require no Bitfab declarations and record as function spans.
       def bitfab_trace(method_name, trace_function_key: nil, name: nil, type: "custom",
         max_depth: Subtree::DEFAULT_MAX_DEPTH, max_spans: Subtree::DEFAULT_MAX_SPANS,
+        max_captured_subtree_spans: Subtree::DEFAULT_MAX_CAPTURED_SUBTREE_SPANS,
         exclude: [], include_wrappers: false, mock_on_replay_default: false)
+        Traceable.send(:validate_trace_options!, max_spans:)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_trace` " \
@@ -306,6 +320,7 @@ module Bitfab
           type:,
           max_depth:,
           max_spans:,
+          max_captured_subtree_spans:,
           exclude:,
           include_wrappers:,
           mock_on_replay_default:

data/lib/bitfab/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bitfab
 version: !ruby/object:Gem::Version
-  version: 0.51.10
+  version: 0.57.0
 platform: ruby
 authors:
 - Harvest Team