bitfab 0.29.0 → 0.29.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61a89926a13fa008e693f825bb810dea734a1b17bed7ab9b9821daec3e36830f
-  data.tar.gz: 5026a5ee5252b0a9cf7a8653287e79ac626fa144bd160e7ecf138131dd8c5dba
+  metadata.gz: 1f26df032729a0c1fbad20c807e1581ec1c68bb9019e0b8f32a85237c785a6ed
+  data.tar.gz: 6acf7a7e153565cf4fb272b651f2740b4d3cb5722b67b6508552aa1b2e81d042
 SHA512:
-  metadata.gz: 803c6b775c40a3c7dad53d4b380c2b844d94c908b56e58ea899e359e674b86f553d4dd14f9c6aa1e7ad6a6552991fec8c24688a482df57f3cdedda4345a0483b
-  data.tar.gz: 4086ecadb3d8a1359632d8fee0df1b6bd6febac396b7ac0f5374259fba3c3e0b4ec347c47c3ecc2094da0c02753a780de632a08c7b946389f27a96a8af1467d5
+  metadata.gz: 5fdcbb34b7174b5308d46405c95735d0a986db51f1af6ddbeb26613ebcdd9c35fade8a40553b1f88b78dc699261146d8cd9d4d7abffda560fbf06f40527717ce
+  data.tar.gz: ea2cd76d972b4b67f1554e1baf28b2aeeaf8560d1329eeff1f6df721273ce6f6e27193d20e0c0995ea77077544a5ab6f64cbb06908276eb8a27c6a6d590171b7

data/lib/bitfab/client.rb

@@ -89,7 +89,8 @@ module Bitfab
     # @param adapt_inputs [#call, nil] optional hook to reshape recorded inputs
     #   onto the method's current signature when its shape changed after the
     #   traces were captured. Receives (args, kwargs, ctx) where ctx is
-    #   { trace_id:, source_span_id: }, and returns [new_args, new_kwargs].
+    #   { original_trace_id:, original_span_id: } (with deprecated
+    #   source_trace_id/source_span_id aliases), and returns [new_args, new_kwargs].
     # @param mock_override [Hash, Array<Hash>, nil] optional selective mock
     #   override(s), each a { match:, value: } hash. match is a callable:
     #   match.call(node) selects spans to substitute (node is
@@ -375,6 +376,9 @@ module Bitfab
               {
                 neon_branch_id: lease["neonBranchId"],
                 snapshot_timestamp: lease["snapshotTimestamp"],
+                original_trace_id: replay_ctx[:source_bitfab_trace_id],
+                # Deprecated wire alias, kept so this SDK still reports usage
+                # against servers that predate the rename.
                 source_trace_id: replay_ctx[:source_bitfab_trace_id],
                 accessed: replay_ctx[:db_snapshot_accessed] == true
               }
@@ -542,10 +546,11 @@ module Bitfab
     # db_snapshot_usage: replay DB branch usage record, present only when a
     # lease was attached to the replay item. Serialized as `db_snapshot_usage`
     # on the raw trace so the server can stamp the trace's metadata at ingest:
-    # { neon_branch_id:, snapshot_timestamp: (optional), source_trace_id:
-    # (optional), accessed: } with :accessed true if customer code obtained
-    # the branch URL and false if it ignored it. nil outside replay or when no
-    # lease was attached, in which case the key is omitted entirely.
+    # { neon_branch_id:, snapshot_timestamp: (optional), original_trace_id:
+    # (optional, with its deprecated source_trace_id alias), accessed: } with
+    # :accessed true if customer code obtained the branch URL and false if it
+    # ignored it. nil outside replay or when no lease was attached, in which
+    # case the key is omitted entirely.
     def send_trace_completion(trace_function_key:, trace_id:, started_at:, ended_at:, db_snapshot_usage: nil)
       trace_state = TraceState.get(trace_id)
       trace_started_at = trace_state&.dig(:started_at) || started_at
@@ -573,8 +578,11 @@ module Bitfab
         if db_snapshot_usage[:snapshot_timestamp]
           usage["snapshot_timestamp"] = db_snapshot_usage[:snapshot_timestamp]
         end
-        if db_snapshot_usage[:source_trace_id]
-          usage["source_trace_id"] = db_snapshot_usage[:source_trace_id]
+        if db_snapshot_usage[:original_trace_id]
+          usage["original_trace_id"] = db_snapshot_usage[:original_trace_id]
+          # Deprecated wire alias, kept so this SDK still reports usage
+          # against servers that predate the rename.
+          usage["source_trace_id"] = db_snapshot_usage[:original_trace_id]
         end
         usage["accessed"] = db_snapshot_usage[:accessed]
         raw_trace["db_snapshot_usage"] = usage

data/lib/bitfab/replay.rb

@@ -110,14 +110,19 @@ module Bitfab
     # @param adapt_inputs [#call, nil] optional hook to reshape recorded inputs
     #   onto the method's current signature when its shape changed after the
     #   traces were captured. Receives (args, kwargs, ctx) where ctx is
-    #   { trace_id:, source_span_id: }, and returns [new_args, new_kwargs]. Runs
-    #   per item inside the same rescue as the method, so a raising adapter sets
-    #   that item's :error rather than crashing the run.
+    #   { original_trace_id:, original_span_id: } (with deprecated
+    #   source_trace_id/source_span_id aliases), and returns [new_args, new_kwargs].
+    #   Runs per item inside the same rescue as the method, so a raising adapter
+    #   sets that item's :error rather than crashing the run.
     # @param on_progress [#call, nil] optional callback invoked once per item as
     #   it finishes, with a running-totals hash { completed:, total:, succeeded:,
-    #   errored:, item: } where item is { trace_id:, error:, duration_ms: } for
-    #   the single item that just settled. trace_id is the SOURCE (historical)
-    #   trace that was replayed, error is that item's replay error or nil, and
+    #   errored:, item: } where item is { trace_id:, original_trace_id:,
+    #   original_span_id:, error:, duration_ms: } for the single item that just
+    #   settled (source_trace_id/source_span_id remain as deprecated aliases).
+    #   trace_id is the new server replay trace id, written in after the run
+    #   completes (nil during progress callbacks); original_trace_id is the
+    #   ORIGINAL (historical) trace that was replayed, error is that item's replay
+    #   error or nil, and
     #   duration_ms is how long that one trace took to replay. Use it to
     #   render replay progress (e.g. a per-trace log). A raising callback never
     #   crashes the run.
@@ -194,10 +199,9 @@ module Bitfab
 
       # 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.
+      # by now: no flush needed. complete_replay finalizes the run and returns
+      # the token/diagnostic mapping; its failures propagate loudly because a
+      # run that never completed can't be finalized.
       complete_response = http_client.complete_replay(test_run_id)
       trace_id_map = complete_response&.dig("traceIds")
       # Per-replay-trace token usage keyed by server trace id: the REPLAYED
@@ -205,66 +209,85 @@ module Bitfab
       # item's :tokens.
       replay_tokens = complete_response&.dig("tokens") || {}
 
-      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.
+      # trace_id_map maps each item's client-side correlation id (:_sdk_trace_id,
+      # which tagged that item's spans during the run) to the server's trace row
+      # id. We use it to write the real server replay trace id into item[:trace_id]
+      # now that the row exists, attach each item's server-aggregated token usage,
+      # and detect a systemic upload failure early. Verdict persistence does NOT
+      # use this map: it is keyed by the original-trace lineage (:original_trace_id +
+      # test_run_id), which needs no client-held server id. Older servers that omit
+      # the map yield no replay tokens and leave item[:trace_id] nil.
+      unless trace_id_map.nil?
         missing = []
         completed_count = 0
         result_items.each do |item|
-          next unless item[:trace_id]
-
-          mapped = trace_id_map[item[:trace_id]]
+          local_id = item[:_sdk_trace_id]
+          mapped = local_id && trace_id_map[local_id]
+          # Write the real server replay trace id in as it comes back; the item
+          # held nil until now (the client correlation id is never surfaced).
+          item[:trace_id] = mapped
           if item[:error].nil?
             completed_count += 1
-            missing << item[:trace_id] if mapped.nil?
+            missing << local_id if mapped.nil?
           end
-          # Pull this item's replayed-run tokens by its server trace id, before
-          # :trace_id is overwritten with that id below.
           item[:tokens] = normalize_tokens(replay_tokens[mapped]) if mapped
-          item[:trace_id] = mapped
         end
-        if missing.any?
+        # ALL completed items missing: systemic (the replayed method is not
+        # traced, or uploads are wholesale broken). Raise; the run's traces
+        # never persisted, so nothing can be labeled.
+        if completed_count.positive? && missing.length == completed_count
           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
+          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
+        # SOME completed items missing: per-item upload failure. Warn, but
+        # return the run; the items that landed can still be labeled.
+        if missing.any?
           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(", ")}"
+            "(test_run_id #{test_run_id}). Their replay token usage is " \
+            "unavailable and they cannot be labeled."
         end
       end
 
-      replay_result = {
+      # Strip the internal correlation handle so returned items expose only the
+      # public shape (runs against older servers that omit the map too).
+      result_items.each { |item| item.delete(:_sdk_trace_id) }
+
+      result = {
         items: result_items,
         test_run_id:,
         test_run_url: "#{client.service_url}#{test_run_url}"
       }
-      write_replay_result_file(replay_result)
-      replay_result
+      # Persist the enriched result two ways so the Bitfab plugin never has to
+      # parse the replay's stdout (which a dependency's logging can corrupt):
+      # write it to BITFAB_REPLAY_RESULT_PATH when the plugin set that env var,
+      # and stream a terminal "complete" progress event. The plugin prefers the
+      # streamed event and falls back to the file. The event routes through
+      # on_progress so only progress-reporting runs emit it.
+      write_replay_result_file(result)
+      if on_progress
+        errored = result_items.count { |item| !item[:error].nil? }
+        total = result_items.length
+        begin
+          on_progress.call({
+            type: "complete",
+            test_run_id:,
+            completed: total,
+            total:,
+            succeeded: total - errored,
+            errored:,
+            result:
+          })
+        rescue => e
+          warn "Bitfab: replay on_progress callback raised: #{e.message}"
+        end
+      end
+      result
     end
 
     def write_replay_result_file(result)
@@ -296,11 +319,13 @@ module Bitfab
       succeeded = 0
       errored = 0
       # Each event carries the single item that just settled so a progress UI
-      # can render per-trace pass/fail as the run streams. trace_id is the
-      # SOURCE (historical) trace that was replayed, taken from the server
-      # item: the result's own :trace_id at this stage is the new replay
-      # trace id (assigned in run() after complete_replay), not the source.
-      report = lambda do |result, source_trace_id, test_run_id|
+      # can render per-trace pass/fail as the run streams. The item's :trace_id
+      # is nil at this stage: the server replay trace id isn't known until run()
+      # writes it in after complete_replay, and the client correlation id is
+      # never surfaced. original_trace_id (the historical trace being replayed,
+      # taken from the server item) is what a UI keys on to identify what just
+      # settled. source_trace_id/source_span_id are kept as deprecated aliases.
+      report = lambda do |result, original_trace_id, original_span_id, test_run_id|
         return unless on_progress
 
         progress_mutex.synchronize do
@@ -311,8 +336,12 @@ module Bitfab
             on_progress.call({
               test_run_id:, completed:, total:, succeeded:, errored:,
               item: {
-                trace_id: source_trace_id,
-                replay_trace_id: result[:trace_id],
+                trace_id: result[:trace_id],
+                original_trace_id:,
+                original_span_id:,
+                # Deprecated aliases for original_trace_id/original_span_id.
+                source_trace_id: original_trace_id,
+                source_span_id: original_span_id,
                 input: result[:input],
                 result: result[:result],
                 original_output: result[:original_output],
@@ -333,7 +362,7 @@ module Bitfab
         server_items.map do |item|
           result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
             adapt_inputs, include_db_branch_lease, mock_overrides:)
-          report.call(result, item["traceId"], test_run_id)
+          report.call(result, original_trace_id_of(item), original_span_id_of(item), test_run_id)
           result
         end
       else
@@ -351,7 +380,7 @@ module Bitfab
               result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
                 adapt_inputs, include_db_branch_lease, mock_overrides:)
               results_mutex.synchronize { results[idx] = result }
-              report.call(result, item["traceId"], test_run_id)
+              report.call(result, original_trace_id_of(item), original_span_id_of(item), test_run_id)
             end
           end
         end
@@ -370,6 +399,11 @@ module Bitfab
     def process_single_item(http_client, server_item, receiver, method_name, test_run_id, mock_strategy,
       adapt_inputs = nil, include_db_branch_lease = false, mock_overrides: [])
       metrics = extract_server_item_metrics(server_item)
+      # The ORIGINAL (historical) trace/span this item replays. Canonical
+      # keys are originalTraceId/originalSpanId; older servers send them under
+      # the deprecated sourceTraceId/sourceSpanId aliases (see *_of helpers).
+      original_trace_id = original_trace_id_of(server_item)
+      original_span_id = original_span_id_of(server_item)
       # The server resolves a Neon preview branch per item during /replay/start
       # (only when include_db_branch_lease was sent). Release it in the +ensure+
       # below so any raise (span fetch, mock-tree build, or the replayed
@@ -378,7 +412,7 @@ module Bitfab
       # lease (env.active? is false for those).
       lease = include_db_branch_lease ? server_item["dbBranchLease"] : nil
 
-      span = http_client.get_external_span(server_item["externalSpanId"])
+      span = http_client.get_external_span(original_span_id)
       item_data = extract_span_data(span)
 
       # Fetch the span tree when the base strategy needs recorded outputs
@@ -396,7 +430,7 @@ module Bitfab
       mock_tree = nil
       if mock_strategy == "all" || mock_strategy == "marked" || overrides_present
         begin
-          tree = http_client.get_span_tree(server_item["externalSpanId"], include_outputs:)
+          tree = http_client.get_span_tree(original_span_id, include_outputs:)
           mock_tree = build_mock_tree(tree["root"] || {})
         rescue Exception => e # rubocop:disable Lint/RescueException
           raise if e.is_a?(SystemExit) || e.is_a?(SignalException)
@@ -418,7 +452,13 @@ module Bitfab
       # override's get_original_output).
       fetch_span_output = (mock_tree && !include_outputs) ? build_span_output_fetcher(http_client) : nil
 
-      adapt_ctx = {trace_id: server_item["traceId"], source_span_id: server_item["externalSpanId"]}
+      adapt_ctx = {
+        original_trace_id:,
+        original_span_id:,
+        # Deprecated aliases for original_trace_id/original_span_id.
+        source_trace_id: original_trace_id,
+        source_span_id: original_span_id
+      }
 
       execute_item(
         item_data,
@@ -435,11 +475,11 @@ module Bitfab
         adapt_inputs:,
         adapt_ctx:,
         db_branch_lease: lease,
-        source_bitfab_trace_id: server_item["traceId"],
+        source_bitfab_trace_id: original_trace_id,
         db_snapshot_ref: server_item["dbSnapshotRef"]
       )
     rescue => e
-      warn "Bitfab: replay item for span #{server_item["externalSpanId"]} failed before execution: #{e.message}"
+      warn "Bitfab: replay item for span #{original_span_id} failed before execution: #{e.message}"
       {
         input: [],
         result: nil,
@@ -449,12 +489,28 @@ module Bitfab
         tokens: metrics&.dig(:tokens),
         model: metrics&.dig(:model),
         trace_id: nil,
+        original_trace_id:,
+        original_span_id:,
+        # Deprecated aliases for original_trace_id/original_span_id.
+        source_trace_id: original_trace_id,
+        source_span_id: original_span_id,
         db_snapshot_ref: server_item["dbSnapshotRef"]
       }
     ensure
       release_db_branch_lease(http_client, lease) if lease
     end
 
+    # The ORIGINAL (historical) trace/span an item replays. Canonical server
+    # keys are originalTraceId/originalSpanId; older servers send them under
+    # the deprecated sourceTraceId/sourceSpanId aliases.
+    def original_trace_id_of(server_item)
+      server_item["originalTraceId"] || server_item["sourceTraceId"]
+    end
+
+    def original_span_id_of(server_item)
+      server_item["originalSpanId"] || server_item["sourceSpanId"]
+    end
+
     # Delete the per-item Neon preview branch. Best-effort: a failure is warned
     # but never raised: the server-side TTL janitor reaps orphans.
     def release_db_branch_lease(http_client, lease)
@@ -583,6 +639,10 @@ module Bitfab
 
       fn_result = nil
       fn_error = nil
+      # Client-side correlation id that tags this item's replay spans so the
+      # server can echo back the row id it minted (resolved in run()'s
+      # complete-replay loop). Carried on the item under :_sdk_trace_id, never
+      # surfaced as the public :trace_id.
       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
@@ -607,7 +667,13 @@ module Bitfab
         # supplied. Inside the rescue so a raising adapter surfaces on this
         # item's :error instead of crashing the run; args is reported on :input.
         if adapt_inputs
-          ctx = adapt_ctx || {trace_id: nil, source_span_id: input_source_span_id}
+          ctx = adapt_ctx || {
+            original_trace_id: nil,
+            original_span_id: input_source_span_id,
+            # Deprecated aliases for original_trace_id/original_span_id.
+            source_trace_id: nil,
+            source_span_id: input_source_span_id
+          }
           args, kwargs = adapt_inputs.call(args, kwargs, ctx)
         end
         fn_result = if kwargs.empty?
@@ -633,7 +699,16 @@ module Bitfab
         duration_ms: metrics[:duration_ms],
         tokens: metrics[:tokens],
         model: metrics[:model],
-        trace_id: sdk_trace_id,
+        # Written in by run() from the complete-replay response once the server
+        # has minted this replay trace's row. Nil until then: the client-side
+        # correlation id (below) is never surfaced as the public :trace_id.
+        trace_id: nil,
+        _sdk_trace_id: sdk_trace_id,
+        original_trace_id: source_bitfab_trace_id,
+        original_span_id: input_source_span_id,
+        # Deprecated aliases for original_trace_id/original_span_id.
+        source_trace_id: source_bitfab_trace_id,
+        source_span_id: input_source_span_id,
         db_snapshot_ref:
       }
     end

data/lib/bitfab/version.rb

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

metadata

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