bitfab 0.12.5 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a66f64bbe867d0adeafbebc9984413802c8ecf8ae47007078b8a3e9d336e5bd0
-  data.tar.gz: 726943a84542d9bc5ead1cc54b0c66d726edaf57ed03703588f63fd41fb67ecd
+  metadata.gz: b0e39c364993d34e99e1d7e3c3a878e0fc6fbfe685fcb0335128bfbf7252161b
+  data.tar.gz: 54bcd62faffceac5c0f67f26f5dedbed0057061019d24d1d789f9988fbf0a44a
 SHA512:
-  metadata.gz: fb26e2388ac5585d8a74aeb8de4f2b8af12df1d6abf4c882560a96107de46afd6fa9a8c1fd99482ae5af6c49234f058f473338c00b91502494e0c078c65a052f
-  data.tar.gz: 9eedf94be719b11b2456ed0002eaeb01afc0b1ef42099850dcc4507096072efb593975a5fa92cef8a99fa224cb1873d0f6c41bfa9d343782f70989b542303da4
+  metadata.gz: 04cef22ee4135b8c43e1e35f5ead74f5650d9f49e16b818de05980d01a054b145bf4adbad1c9fc3ec01b0e17130e108df666f75bc8bc9bf4666eb23eb9ba7acc
+  data.tar.gz: bb4724aff3d7fc6a9f04e1a923fd5aaabb2e808ef2310ef2c1d51e6a246c296653c1ea85509a92e1a1b927c131074e0907c07623ade5affaa6bab8fd20b2464c

data/lib/bitfab/client.rb

@@ -39,8 +39,10 @@ module Bitfab
     # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
     # @param method_name [Symbol] the method to replay
     # @param trace_function_key [String] the trace function key for this method
-    # @param limit [Integer] maximum number of traces to replay (default: 5)
-    # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
+    # @param limit [Integer, nil] maximum number of traces to replay (default: 5).
+    #   Mutually exclusive with trace_ids: an explicit ID list already
+    #   determines how many traces replay, so passing both raises.
+    # @param trace_ids [Array<String>, nil] optional list of trace IDs to replay (max 100)
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay (stored on the experiment)
@@ -52,7 +54,7 @@ module Bitfab
     #   "all", or "marked". "all" mocks every child span; "marked" only mocks
     #   spans declared with mock_on_replay: true.
     # @return [Hash] with :items, :test_run_id, :test_run_url
-    def replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10,
+    def replay(receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, max_concurrency: 10,
       code_change_description: nil, code_change_files: nil, experiment_group_id: nil, mock: "none")
       Replay.run(
         self, receiver, method_name,
@@ -181,12 +183,24 @@ module Bitfab
             pending << span_thread if span_thread
             pending.each { |t| t.join(5) }
 
-            send_trace_completion(
+            completion_thread = send_trace_completion(
               trace_function_key:,
               trace_id:,
               started_at:,
               ended_at:
             )
+
+            # In replay, persistence is correctness: the replay runner joins
+            # these threads before calling complete_replay, or the server's
+            # trace-ID mapping races the uploads and every item's trace_id
+            # comes back nil. The 5s join above is best-effort only; this
+            # hands the full set (span uploads + trace completion) to the
+            # runner. No-op outside replay, where sends stay fire-and-forget.
+            persistence = ReplayContext.current&.dig(:pending_persistence)
+            if persistence
+              persistence.concat(pending)
+              persistence << completion_thread if completion_thread
+            end
           else
             @pending_span_mutex.synchronize do
               @pending_span_threads[trace_id] << span_thread if span_thread && @pending_span_threads.key?(trace_id)
@@ -312,10 +326,14 @@ module Bitfab
         payload["testRunId"] = trace_state[:test_run_id]
       end
 
-      @http_client.send_external_trace(payload)
+      completion_thread = @http_client.send_external_trace(payload)
 
       # Clean up trace state
       TraceState.delete(trace_id)
+
+      # Returned so the replay path can join it — trace completions must be
+      # persisted before complete_replay builds the trace-ID mapping.
+      completion_thread
     end
 
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,

data/lib/bitfab/http_client.rb

@@ -108,9 +108,11 @@ module Bitfab
     def start_replay(trace_function_key, limit, trace_ids: nil, code_change_description: nil,
       code_change_files: nil, experiment_group_id: nil)
       payload = {
-        "traceFunctionKey" => trace_function_key,
-        "limit" => limit
+        "traceFunctionKey" => trace_function_key
       }
+      # limit is only meaningful without trace_ids (an explicit ID list
+      # already determines the count), so it's omitted when nil.
+      payload["limit"] = limit unless limit.nil?
       payload["traceIds"] = trace_ids if trace_ids
       payload["codeChangeDescription"] = code_change_description unless code_change_description.nil?
       payload["codeChangeFiles"] = normalize_code_change_files(code_change_files) unless code_change_files.nil?

data/lib/bitfab/replay.rb

@@ -22,8 +22,12 @@ module Bitfab
 
     # Execute a block with replay context set on the current thread.
     # The context is automatically cleared when the block completes.
+    #
+    # pending_persistence, when given, collects the root span's persistence
+    # threads (span uploads + trace completion) so the replay runner can join
+    # them before complete_replay builds the trace-ID mapping.
     def with_context(test_run_id:, input_source_span_id: nil, input_source_trace_id: nil, trace_id: nil,
-      mock_tree: nil, mock_strategy: nil)
+      mock_tree: nil, mock_strategy: nil, pending_persistence: nil)
       previous = Thread.current[REPLAY_CONTEXT_KEY]
       ctx = {
         test_run_id:,
@@ -31,6 +35,7 @@ module Bitfab
         input_source_trace_id:,
         trace_id:
       }
+      ctx[:pending_persistence] = pending_persistence if pending_persistence
       if mock_tree
         ctx[:mock_tree] = mock_tree
         ctx[:mock_strategy] = mock_strategy || "none"
@@ -56,8 +61,10 @@ module Bitfab
     # @param receiver [Object, Class] an instance for instance methods, or a Class for class methods
     # @param method_name [Symbol] the method to replay
     # @param trace_function_key [String] the trace function key for this method
-    # @param limit [Integer] maximum number of traces to replay (default: 5)
-    # @param trace_ids [Array<String>, nil] optional list of trace IDs to filter
+    # @param limit [Integer, nil] maximum number of traces to replay (default: 5).
+    #   Mutually exclusive with trace_ids: an explicit ID list already
+    #   determines how many traces replay, so passing both raises.
+    # @param trace_ids [Array<String>, nil] optional list of trace IDs to replay (max 100)
     # @param max_concurrency [Integer, nil] max threads for parallel replay (default: 10)
     # @param code_change_description [String, nil] optional rationale for the
     #   code change being tested in this replay (stored on the experiment)
@@ -69,17 +76,31 @@ module Bitfab
     #   "all", or "marked". "all" mocks every child span; "marked" only mocks
     #   spans declared with mock_on_replay: true.
     # @return [Hash] with :items, :test_run_id, :test_run_url
-    def run(client, receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10,
+    def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, max_concurrency: 10,
       code_change_description: nil, code_change_files: nil, experiment_group_id: nil, mock: "none")
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
       end
+      if trace_ids
+        raise ArgumentError, "trace_ids must contain at least one trace ID." if trace_ids.empty?
+        if trace_ids.length > 100
+          raise ArgumentError, "trace_ids supports at most 100 trace IDs per replay (got #{trace_ids.length})."
+        end
+      end
+      if limit && trace_ids
+        raise ArgumentError,
+          "Pass either limit or trace_ids, not both: an explicit trace ID list already determines how many traces replay."
+      end
 
       http_client = client.instance_variable_get(:@http_client)
 
+      # limit is meaningless with explicit trace_ids (the ID list determines
+      # the count), so it's omitted from the request entirely.
+      effective_limit = trace_ids ? nil : (limit || 5)
+
       replay_data = http_client.start_replay(
         trace_function_key,
-        limit,
+        effective_limit,
         trace_ids:,
         code_change_description:,
         code_change_files:,
@@ -95,17 +116,63 @@ module Bitfab
         []
       end
 
-      Bitfab.flush_traces
-
-      begin
-        complete_response = http_client.complete_replay(test_run_id)
-        trace_id_map = complete_response&.dig("traceIds") || {}
+      # Every item joined its own trace-persistence threads (span uploads +
+      # completion) in execute_item, so all replay traces are on the server
+      # by now — no flush needed, and complete_replay's trace-ID mapping is
+      # deterministic. complete_replay failures propagate: a missing mapping
+      # means verdicts can't be persisted, which callers must hear about
+      # loudly.
+      complete_response = http_client.complete_replay(test_run_id)
+      trace_id_map = complete_response&.dig("traceIds")
+
+      if trace_id_map.nil?
+        # Older servers don't return the mapping. Preserve the legacy
+        # nil-trace_id behavior but say why.
+        warn "Bitfab: server did not return replay trace IDs; item trace_id " \
+          "will be nil (server upgrade required for verdict persistence)"
+        result_items.each { |item| item[:trace_id] = nil }
+      else
+        # Map each item's locally-generated trace ID to the server's trace
+        # row ID. A completed item with no mapping means its trace was sent
+        # but the server has no record — a nil trace_id blocks verdict
+        # persistence and the Studio experiments view downstream, so this
+        # must never be silent.
+        #
+        # Severity splits on scope:
+        # - ALL completed items missing: systemic (the replayed method is
+        #   not traced, or uploads are wholesale broken). Raise; the run's
+        #   results are unusable for persistence.
+        # - SOME completed items missing: per-item upload failure (transient
+        #   network blip, one oversized payload). Nil those items and warn
+        #   loudly, but return the run so callers can persist verdicts for
+        #   the items that landed.
+        missing = []
+        completed_count = 0
         result_items.each do |item|
-          item[:trace_id] = trace_id_map[item[:trace_id]]
+          next unless item[:trace_id]
+
+          mapped = trace_id_map[item[:trace_id]]
+          if item[:error].nil?
+            completed_count += 1
+            missing << item[:trace_id] if mapped.nil?
+          end
+          item[:trace_id] = mapped
+        end
+        if missing.any?
+          trace_count = complete_response["traceCount"]
+          server_count = trace_count.nil? ? "" : " The server persisted #{trace_count} trace(s) for this run."
+          if missing.length == completed_count
+            raise "Replay completed but the server has no persisted trace for " \
+              "any of the #{completed_count} completed item(s) " \
+              "(test_run_id #{test_run_id}).#{server_count} Trace uploads were " \
+              "joined, so either the uploads failed or the replayed method is " \
+              "not traced (no root span was emitted)."
+          end
+          warn "Bitfab: server has no persisted trace for #{missing.length} of " \
+            "#{completed_count} completed replay item(s) " \
+            "(test_run_id #{test_run_id}).#{server_count} Their trace_id is nil " \
+            "and verdicts cannot be persisted for them. Missing: #{missing.join(", ")}"
         end
-      rescue => e
-        warn "Bitfab: Failed to complete replay: #{e.message}"
-        result_items.each { |item| item[:trace_id] = nil }
       end
 
       {
@@ -270,6 +337,11 @@ module Bitfab
       fn_result = nil
       fn_error = nil
       sdk_trace_id = SecureRandom.uuid
+      # Collects the root span's persistence threads (span uploads + trace
+      # completion). Joined below so this item's trace is on the server
+      # before run() calls complete_replay — otherwise the server's trace-ID
+      # mapping races the uploads and the item's trace_id comes back nil.
+      pending_persistence = []
 
       ReplayContext.with_context(
         test_run_id:,
@@ -277,7 +349,8 @@ module Bitfab
         input_source_trace_id:,
         trace_id: sdk_trace_id,
         mock_tree:,
-        mock_strategy:
+        mock_strategy:,
+        pending_persistence:
       ) do
         fn_result = if kwargs.empty?
           receiver.send(method_name, *args)
@@ -288,6 +361,12 @@ module Bitfab
         fn_error = e.message
       end
 
+      # Wait for this item's trace (spans + completion) to be fully persisted
+      # before the item resolves. Runs on the error path too — a raising
+      # method still emits a root span whose trace must land before
+      # complete_replay. Joins are bounded by the HTTP layer's own timeouts.
+      pending_persistence.each(&:join)
+
       {
         input: args,
         result: fn_result,

data/lib/bitfab/version.rb

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

metadata

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