bitfab 0.36.3 → 0.36.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: deea3052760a7b677216225f0cd030f4931995b1d10e6b7396c97a57a27ab9c1
-  data.tar.gz: 5f64a512db5c8c79f092e5bbf92e16adfc2e20a4a07c869eafab48fb42db5665
+  metadata.gz: 49b714ee6d468fc34c0c6009802c5736d33f03275f06d7d7148635b5d70b7caa
+  data.tar.gz: 3816843ddea8722c0222cfc0bed5c65ea05f5abb5ff764233e5ab302d609f2d2
 SHA512:
-  metadata.gz: f9024ab4975b3963e4d2c91aa903b3e4bc7880791aa1f0a4132a9ee847e54e2132339246cbc1067beba8a2130e813738474fcc40a38a1d3b9a0e19ba92633834
-  data.tar.gz: b3c4b7c252a566192362e6d1a3e4d31bcad55f752a70527fce5de87ebc9ab75c4839a02fd5d67589823ee36003f3fcb49d5bdade0a315dc8a22971b9769ea9c3
+  metadata.gz: 1f5504e7d7622ccf55145b9124ee0d8ca42f774bdaea720a92382af42148bbf16afb72708d673fb359b37a9840364a770e4a1a87003f016aff2ebd1a59a52b38
+  data.tar.gz: db5fbc39adf358e640ae315348eb15ceb5798c67747d092eaaf37651cf9a89542ae9c4d8899a44ebfd4425ba623598e9e5af382dec11f119a917d52cf9ccb0dd

data/lib/bitfab/client.rb

@@ -132,21 +132,27 @@ module Bitfab
     #   +:min_cu+/+:max_cu+ size the branch compute in Neon Compute Units and
     #   +:warmup_sql+ warms its cache. Read the resolved branch inside the
     #   replayed method with +Bitfab.current_replay_branch+.
-    # @param on_progress [#call, nil] optional callback invoked once per item as
-    #   it finishes, with a running-totals hash { completed:, total:, succeeded:,
-    #   errored: }. Use it to render replay progress (e.g. a terminal progress
-    #   bar). Replay does not know pass/fail yet, so the totals only distinguish
-    #   items whose method ran (:succeeded) from items that raised (:errored).
-    #   A raising callback never crashes the run.
+    # @param on_item_finish [#call, nil] optional callback invoked exactly once
+    #   per item as it finishes, always with a running-totals hash containing
+    #   { completed:, total:, succeeded:, errored:, item: }. It never receives a
+    #   whole-run completion event. Replay does not know pass/fail yet, so the
+    #   totals only distinguish items whose method ran (:succeeded) from items
+    #   that raised (:errored). A raising callback never crashes the run.
+    # @param on_progress [#call, nil] deprecated compatibility callback. It
+    #   receives the same per-item events plus the legacy item-less +"complete"+
+    #   event. Ignored when +on_item_finish+ is also provided.
+    # @param on_item_start [#call, nil] optional callback invoked when a worker
+    #   begins processing each item. Pair it with on_item_finish to distinguish
+    #   queued work from in-flight work. A raising callback never crashes the run.
     # @return [Hash] with :items, :test_run_id, :test_run_url
     def replay(receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, max_concurrency: 10,
       name: nil, code_change_description: Replay::CODE_CHANGE_UNSET, code_change_files: Replay::CODE_CHANGE_UNSET, experiment_group_id: nil, dataset_id: nil, grader_ids: nil, mock: "marked",
-      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil)
       Replay.run(
         self, receiver, method_name,
         trace_function_key:, limit:, trace_ids:, name:, max_concurrency:,
         code_change_description:, code_change_files:, experiment_group_id:, dataset_id:, grader_ids:, mock:, adapt_inputs:,
-        mock_override:, db_branch:,
+        mock_override:, db_branch:, on_item_start:, on_item_finish:,
         on_progress:
       )
     end

data/lib/bitfab/compress.rb

@@ -12,18 +12,29 @@ module Bitfab
     # batches) ride uncompressed.
     MIN_COMPRESSED_BYTES = 8_192
 
+    PreparedRequest = Struct.new(:body, :content_encoding, :raw_bytes, :wire_bytes)
+
     module_function
 
     # Returns the body to send and the Content-Encoding it carries, or nil when
     # the body is sent as-is. Compression is best-effort: any failure sends the
     # original body rather than dropping the span.
     def encode_request_body(body)
-      return [body, nil] if ENV[DISABLE_COMPRESSION_ENV]
-      return [body, nil] if body.bytesize < MIN_COMPRESSED_BYTES
+      prepared = prepare_request_body(body)
+      [prepared.body, prepared.content_encoding]
+    end
+
+    def prepare_request_body(body)
+      size = body.bytesize
+      return PreparedRequest.new(body, nil, size, size) if ENV[DISABLE_COMPRESSION_ENV]
+      return PreparedRequest.new(body, nil, size, size) if size < MIN_COMPRESSED_BYTES
+
+      compressed = Zlib.gzip(body)
+      return PreparedRequest.new(body, nil, size, size) if compressed.bytesize >= size
 
-      [Zlib.gzip(body), "gzip"]
+      PreparedRequest.new(compressed, "gzip", size, compressed.bytesize)
     rescue
-      [body, nil]
+      PreparedRequest.new(body, nil, body.bytesize, body.bytesize)
     end
   end
 end

data/lib/bitfab/http_client.rb

@@ -58,6 +58,16 @@ module Bitfab
     # POST an already-encoded body. The span transport encodes its own batches,
     # so routing them back through #request would encode the same data twice.
     def send_encoded(endpoint, body, timeout: nil, max_retries: 1, retry_delay: 0.1)
+      send_prepared(
+        endpoint,
+        Compress.prepare_request_body(body),
+        timeout:,
+        max_retries:,
+        retry_delay:
+      )
+    end
+
+    def send_prepared(endpoint, prepared, timeout: nil, max_retries: 1, retry_delay: 0.1)
       uri = URI("#{@service_url}#{endpoint}")
       request_timeout = timeout || @timeout
 
@@ -70,9 +80,8 @@ module Bitfab
         http.read_timeout = request_timeout
 
         req = Net::HTTP::Post.new(uri.path, headers)
-        encoded_body, content_encoding = Compress.encode_request_body(body)
-        req["Content-Encoding"] = content_encoding if content_encoding
-        req.body = encoded_body
+        req["Content-Encoding"] = prepared.content_encoding if prepared.content_encoding
+        req.body = prepared.body
 
         response = http.request(req)
 
@@ -279,8 +288,8 @@ module Bitfab
       end
     end
 
-    def send_transport_request(endpoint, body, timeout)
-      send_encoded(endpoint, body, timeout:, max_retries: 1)
+    def send_transport_request(endpoint, request, timeout)
+      send_prepared(endpoint, request, timeout:, max_retries: 1)
     end
 
     # Normalize each entry to a hash with stable string keys, accepting either

data/lib/bitfab/otel.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "time"
 require "opentelemetry/sdk"
 
+require_relative "compress"
 require_relative "serialize"
 require_relative "version"
 require_relative "warn_once"
@@ -22,6 +23,7 @@ module Bitfab
     MAX_REQUEST_BYTES_ENV = "BITFAB_OTEL_MAX_REQUEST_BYTES"
     EXPORT_CONCURRENCY_ENV = "BITFAB_OTEL_EXPORT_CONCURRENCY"
     MAX_EXPORT_REQUEST_BYTES = 3_000_000
+    MAX_DECOMPRESSED_REQUEST_BYTES = 8_000_000
     MAX_QUEUE_SIZE = 8_192
     DIRECT_MAX_EXPORT_BATCH_SIZE = 512
     DIRECT_MAX_REQUEST_BATCH_SIZE = 8
@@ -314,13 +316,35 @@ module Bitfab
       end
 
       def send_batch(envelope, batch)
-        if batch.size > @max_request_bytes
-          warn_oversized(batch.spans.size)
-          return false
-        end
+        request_spans = batch.spans
+        request_raw_bytes = batch.size
+        already_trimmed = false
+        loop do
+          if request_raw_bytes <= MAX_DECOMPRESSED_REQUEST_BYTES
+            prepared = Compress.prepare_request_body(Encoder.encode_request(envelope, request_spans))
+            if prepared.wire_bytes <= @max_request_bytes
+              send_with_retries(prepared)
+              return true
+            end
+          end
 
-        send_with_retries(Encoder.encode_request(envelope, batch.spans))
-        true
+          if batch.spans.size != 1
+            warn_oversized(batch.spans.size)
+            return false
+          end
+          if already_trimmed
+            warn_oversized(1)
+            return false
+          end
+          trimmed = Encoder.trim_span(batch.spans.first)
+          if trimmed.nil?
+            warn_oversized(1)
+            return false
+          end
+          request_spans = [trimmed]
+          request_raw_bytes = envelope.size + trimmed.size
+          already_trimmed = true
+        end
       rescue PayloadTooLargeError
         warn_oversized(batch.spans.size)
         false
@@ -343,11 +367,11 @@ module Bitfab
         )
       end
 
-      def send_with_retries(body)
+      def send_with_retries(request)
         attempt = 0
         begin
           attempt += 1
-          response = @direct_sender.call(OTLP_TRACES_ENDPOINT, body, EXPORT_TIMEOUT_MILLIS / 1000.0)
+          response = @direct_sender.call(OTLP_TRACES_ENDPOINT, request, EXPORT_TIMEOUT_MILLIS / 1000.0)
           check_partial_success(response)
         rescue PartialSuccessError
           raise
@@ -456,7 +480,10 @@ module Bitfab
         # Encoding is the expensive part of a submit and needs no mutual
         # exclusion, so it stays outside the lock.
         name = Encoder.span_name(operation, payload)
-        encoded_payload = Serialize.safe_generate(payload)
+        encoded_payload = Serialize.safe_generate(
+          payload,
+          max_carrier_bytes: PayloadBudget::MAX_COMPRESSIBLE_SPAN_CARRIER_BYTES
+        )
         started_at = Encoder.timestamp(payload, "started_at")
         ended_at = Encoder.timestamp(payload, "ended_at")
         errored = Encoder.error?(payload)
@@ -616,6 +643,20 @@ module Bitfab
           EncodedSpan.new(encoded, encoded.bytesize)
         end
 
+        def trim_span(span)
+          carrier = JSON.parse(span.encoded)
+          attribute = carrier.fetch("attributes").find { |entry| entry["key"] == PAYLOAD_ATTRIBUTE }
+          return nil if attribute.nil?
+
+          value = attribute.fetch("value")
+          payload = JSON.parse(value.fetch("stringValue"))
+          value["stringValue"] = Serialize.safe_generate(payload)
+          encoded = JSON.generate(carrier)
+          EncodedSpan.new(encoded, encoded.bytesize)
+        rescue KeyError, JSON::ParserError, TypeError
+          nil
+        end
+
         def request_envelope(first)
           scope = first.instrumentation_scope
           resource = JSON.generate({"attributes" => attributes(first.resource.attribute_enumerator.to_h)})

data/lib/bitfab/payload_budget.rb

@@ -19,10 +19,12 @@ module Bitfab
   # on a body sized exactly to a 2.4 MB cap, prose produced a 2.4 MB carrier but
   # backslash-dense content produced 4.8 MB, which the exporter dropped.
   #
-  # 2.8 MB leaves room beneath the 3 MB request ceiling for the span and request
-  # envelopes wrapped around the attribute.
+  # The normal 2.8 MB fallback leaves room beneath the 3 MB wire target. Trace
+  # transport may first preserve a carrier up to 7.8 MB when its single-span
+  # request compresses below that target and stays under the 8 MB raw ceiling.
   module PayloadBudget
     MAX_SPAN_CARRIER_BYTES = 2_800_000
+    MAX_COMPRESSIBLE_SPAN_CARRIER_BYTES = 7_800_000
 
     # Span fields that identify the span rather than carry user data. Trimming
     # one would leave a span that no longer says what it is, so they stay
@@ -47,23 +49,23 @@ module Bitfab
     # can at most double it, so anything under half the budget always fits and
     # anything past the budget never does. Ordinary spans settle on the first
     # comparison and never pay for the scan.
-    def fits_carrier_budget?(body)
+    def fits_carrier_budget?(body, max_bytes = MAX_SPAN_CARRIER_BYTES)
       size = body.bytesize
-      return true if size * 2 + 2 <= MAX_SPAN_CARRIER_BYTES
-      return false if size + 2 > MAX_SPAN_CARRIER_BYTES
+      return true if size * 2 + 2 <= max_bytes
+      return false if size + 2 > max_bytes
 
-      carrier_byte_length(body) <= MAX_SPAN_CARRIER_BYTES
+      carrier_byte_length(body) <= max_bytes
     end
 
     # Return a body within the budget, plus the fields that had to be stubbed.
-    def enforce(payload, body, &encode)
-      return [body, []] if fits_carrier_budget?(body)
+    def enforce(payload, body, max_bytes = MAX_SPAN_CARRIER_BYTES, &encode)
+      return [body, []] if fits_carrier_budget?(body, max_bytes)
       return [body, []] unless payload.is_a?(Hash)
 
-      trimmed_payload, trimmed = trim(payload, &encode)
+      trimmed_payload, trimmed = trim(payload, max_bytes, &encode)
       return [body, []] if trimmed_payload.nil?
 
-      mark_trimmed(trimmed_payload, trimmed)
+      mark_trimmed(trimmed_payload, trimmed, max_bytes)
       [encode.call(trimmed_payload), trimmed]
     rescue
       [body, []]
@@ -73,7 +75,7 @@ module Bitfab
     # Returns [trimmed_payload, trimmed_keys], or nil when nothing could be
     # trimmed: the caller then ships the oversized body and lets the exporter
     # report the drop, which still beats silently emptying a span.
-    def trim(payload, &encode)
+    def trim(payload, max_bytes = MAX_SPAN_CARRIER_BYTES, &encode)
       copy, containers = clone_trimmable(payload)
       candidates = collect_candidates(containers)
       return nil if candidates.empty?
@@ -83,7 +85,7 @@ module Bitfab
         container[key] = "<unserializable: too_large_#{size}_bytes>"
         trimmed << key
         body = encode.call(copy)
-        return [copy, trimmed] if fits_carrier_budget?(body)
+        return [copy, trimmed] if fits_carrier_budget?(body, max_bytes)
       end
       nil
     end
@@ -135,7 +137,7 @@ module Bitfab
 
     # Record the trim in the payload's own errors, which is what the server
     # reads to flag a trace as incomplete.
-    def mark_trimmed(payload, trimmed)
+    def mark_trimmed(payload, trimmed, max_bytes)
       key = payload.key?(:errors) ? :errors : "errors"
       existing = payload[key]
       errors = existing.is_a?(Array) ? existing.dup : []
@@ -143,7 +145,7 @@ module Bitfab
         "source" => "sdk",
         "step" => "payload_budget",
         "error" => "trimmed oversized field(s) to fit the " \
-          "#{MAX_SPAN_CARRIER_BYTES}-byte span carrier budget: " \
+          "#{max_bytes}-byte span carrier budget: " \
           "#{trimmed.uniq.join(", ")}"
       }
       payload[key] = errors

data/lib/bitfab/replay.rb

@@ -201,11 +201,11 @@ module Bitfab
     #   and ceiling in Neon Compute Units, and +:warmup_sql+ warms the branch's
     #   cache before the replayed method sees it. Read the resolved branch
     #   inside the method with +Bitfab.current_replay_branch+.
-    # @param on_progress [#call, nil] optional callback invoked once per item as
+    # @param on_item_finish [#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:, 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).
+    #   finished (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
@@ -213,14 +213,22 @@ module Bitfab
     #   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.
+    # @param on_progress [#call, nil] deprecated compatibility callback. It
+    #   receives the same per-item finish events plus the legacy whole-run
+    #   +"complete"+ event. Ignored when +on_item_finish+ is also provided.
+    # @param on_item_start [#call, nil] optional callback invoked when a worker
+    #   begins processing each item, before replay setup and customer code run.
+    #   Pair it with on_item_finish to distinguish queued work from in-flight work.
+    #   A raising callback never crashes the run.
     # @return [Hash] with :items, :test_run_id, :test_run_url
     def run(client, receiver, method_name, trace_function_key:, limit: nil, trace_ids: nil, name: nil,
       max_concurrency: 10, code_change_description: CODE_CHANGE_UNSET, code_change_files: CODE_CHANGE_UNSET, experiment_group_id: nil,
       dataset_id: nil, grader_ids: nil, mock: "marked",
-      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_progress: nil)
+      adapt_inputs: nil, mock_override: nil, db_branch: nil, on_item_start: nil, on_item_finish: nil, on_progress: nil)
       unless MOCK_STRATEGIES.include?(mock.to_s)
         raise ArgumentError, "Invalid mock strategy '#{mock}'. Must be one of: #{MOCK_STRATEGIES.join(", ")}"
       end
+      item_finish_callback = on_item_finish || on_progress
       if trace_ids
         raise ArgumentError, "trace_ids must contain at least one trace ID." if trace_ids.empty?
         if trace_ids.length > 100
@@ -296,7 +304,8 @@ module Bitfab
 
       result_items = if server_items.any?
         process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock.to_s,
-          adapt_inputs, include_db_branch_lease, resolved_db_branch_settings, on_progress:,
+          adapt_inputs, include_db_branch_lease, resolved_db_branch_settings, on_item_start:,
+          on_item_finish: item_finish_callback,
           mock_overrides: resolved_overrides)
       else
         []
@@ -383,14 +392,12 @@ module Bitfab
         test_run_id:,
         test_run_url: full_test_run_url
       }
-      # 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.
+      # Persist the enriched result so the Bitfab plugin never has to parse the
+      # replay's stdout, which a dependency's logging can corrupt.
       write_replay_result_file(result)
-      if on_progress
+      # Preserve the legacy terminal event only for on_progress. on_item_finish
+      # is strictly item-scoped, so every invocation always includes an item.
+      if on_item_finish.nil? && on_progress
         errored = result_items.count { |item| !item[:error].nil? }
         total = result_items.length
         begin
@@ -631,36 +638,56 @@ module Bitfab
 
     # Process all replay items, optionally in parallel using threads.
     def process_items(http_client, server_items, receiver, method_name, test_run_id, max_concurrency, mock_strategy,
-      adapt_inputs = nil, include_db_branch_lease = false, db_branch_settings = nil, on_progress: nil,
+      adapt_inputs = nil, include_db_branch_lease = false, db_branch_settings = nil, on_item_start: nil, on_item_finish: nil,
       mock_overrides: [])
       concurrency = max_concurrency || server_items.length
 
-      # Reports running totals once per item as it settles. In the parallel
-      # path it runs from worker threads, so the mutex both makes the counter
-      # updates safe and serializes the user's callback (never called
-      # concurrently). A raising callback is swallowed: progress UI must never
-      # crash the run.
+      # Lifecycle callbacks run from worker threads in the parallel path, so the
+      # mutex makes counter updates safe and serializes each callback. A raising
+      # callback is swallowed because progress UI must never crash the run.
       total = server_items.length
       progress_mutex = Mutex.new
+      started = 0
       completed = 0
       succeeded = 0
       errored = 0
-      # Each event carries the single item that just settled so a progress UI
+      # Each event carries the single item that just finished so a progress UI
       # 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
+      # finished. source_trace_id/source_span_id are kept as deprecated aliases.
+      report_start = lambda do |original_trace_id, original_span_id|
+        progress_mutex.synchronize do
+          started += 1
+          next unless on_item_start
+
+          begin
+            on_item_start.call({
+              type: "started", test_run_id:, started:, completed:, total:, succeeded:, errored:,
+              item: {
+                original_trace_id:,
+                original_span_id:,
+                source_trace_id: original_trace_id,
+                source_span_id: original_span_id
+              }
+            })
+          rescue => e
+            warn "Bitfab: replay on_item_start callback raised: #{e.message}"
+          end
+        end
+      end
 
+      report = lambda do |result, original_trace_id, original_span_id, test_run_id|
         progress_mutex.synchronize do
           completed += 1
           error = result[:error]
           error.nil? ? (succeeded += 1) : (errored += 1)
+          next unless on_item_finish
+
           begin
-            on_progress.call({
+            on_item_finish.call({
               test_run_id:, completed:, total:, succeeded:, errored:,
               item: {
                 trace_id: result[:trace_id],
@@ -682,13 +709,14 @@ module Bitfab
               }
             })
           rescue => e
-            warn "Bitfab: replay on_progress callback raised: #{e.message}"
+            warn "Bitfab: replay on_item_finish callback raised: #{e.message}"
           end
         end
       end
 
       if concurrency <= 1
         server_items.map do |item|
+          report_start.call(original_trace_id_of(item), original_span_id_of(item))
           result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
             adapt_inputs, include_db_branch_lease, db_branch_settings, mock_overrides:)
           report.call(result, original_trace_id_of(item), original_span_id_of(item), test_run_id)
@@ -706,6 +734,7 @@ module Bitfab
               item, idx = work_mutex.synchronize { work_queue.shift }
               break unless item
 
+              report_start.call(original_trace_id_of(item), original_span_id_of(item))
               result = process_single_item(http_client, item, receiver, method_name, test_run_id, mock_strategy,
                 adapt_inputs, include_db_branch_lease, db_branch_settings, mock_overrides:)
               results_mutex.synchronize { results[idx] = result }

data/lib/bitfab/serialize.rb

@@ -14,7 +14,7 @@ module Bitfab
     # further. It is deliberately the same number as the whole-span budget: one
     # legitimately large value may use the entire budget, and PayloadBudget is
     # what enforces the total once every field is in.
-    MAX_SERIALIZED_BYTES = PayloadBudget::MAX_SPAN_CARRIER_BYTES
+    MAX_SERIALIZED_BYTES = PayloadBudget::MAX_COMPRESSIBLE_SPAN_CARRIER_BYTES
 
     # Recursion guard for cyclic graphs and pathologically nested structures.
     MAX_SERIALIZE_DEPTH = 16
@@ -260,18 +260,20 @@ module Bitfab
     # raises and stubs strays) instead of letting JSON.generate raise and drop
     # the whole span/trace silently. A degraded payload warns loudly so the
     # trace isn't quietly left incomplete or not replayable.
-    def safe_generate(payload)
+    def safe_generate(payload, max_carrier_bytes: PayloadBudget::MAX_SPAN_CARRIER_BYTES)
       # Budget the value that was actually encoded, not the caller's original: a
       # cyclic or otherwise non-encodable field cannot be sized (JSON.generate
       # raises on it), so on the original graph the biggest field is skipped as
       # a trim candidate and the oversized body ships anyway. The sanitized copy
       # has those values already replaced with stubs, so every field is sizeable.
       body, encoded = encode_unbounded(payload)
-      body, trimmed = PayloadBudget.enforce(encoded, body) { |value| encode_unbounded(value).first }
+      body, trimmed = PayloadBudget.enforce(encoded, body, max_carrier_bytes) do |value|
+        encode_unbounded(value).first
+      end
       if trimmed.any?
         Bitfab.warn_once(
           "payload-over-budget",
-          "a span payload exceeded the #{PayloadBudget::MAX_SPAN_CARRIER_BYTES}-byte carrier budget; its " \
+          "a span payload exceeded the #{max_carrier_bytes}-byte carrier budget; its " \
           "largest field(s) (#{trimmed.uniq.join(", ")}) were replaced with placeholders " \
           "so the span still ships. The span is incomplete and may not be replayable."
         )

data/lib/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -144,20 +144,18 @@ module Bitfab
       CurrentTrace.new(entry[:trace_id])
     end
 
-    # A ready-made on_progress callback for replay: writes one @@bitfab:progress
-    # line per trace to stderr, which the Bitfab plugin polls to report live
-    # progress while the replay runs in the background, so replay scripts never
-    # hand-format the protocol. stdout stays the ReplayResult JSON. Never raises
-    # (progress must not crash a run). The progress hash's item is forwarded
-    # verbatim through to_json, so the plugin sees the source trace id, local
-    # replay trace id, outputs, error, and duration of the item that just settled.
+    # A ready-made replay lifecycle reporter. Pass it as both on_item_start and
+    # on_item_finish so the Bitfab plugin sees in-flight and finished items. It writes
+    # @@bitfab:progress lines to stderr, leaving stdout for ReplayResult JSON, and
+    # never raises because progress reporting must not crash a run.
     #
     # @example
-    #   Bitfab.client.replay(..., on_progress: Bitfab.method(:report_replay_progress))
+    #   reporter = Bitfab.method(:report_replay_progress)
+    #   Bitfab.client.replay(..., on_item_start: reporter, on_item_finish: reporter)
     #
     # @param progress [Hash] running totals with keys completed, total,
     #   succeeded, errored, and item (the object replay already passes to
-    #   on_progress)
+    #   on_item_finish)
     def report_replay_progress(progress)
       warn "#{BITFAB_PROGRESS_PREFIX}#{Replay.json_safe(progress).to_json}"
     rescue

metadata

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