bitfab 0.33.5 → 0.33.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40eaaf83e783c54b0a0b373b681d82e1d96b01f4e99a424f68af1fffcd82a79e
-  data.tar.gz: ed01d854b7ed2ee101a6bab9d659bd977c7f5ee6f0cbd0b481675d76dba449ec
+  metadata.gz: 1d72d477d9b3533bbba990387aeaf342774ec7e3271e11e51fc297a7de9534bb
+  data.tar.gz: 624832fc2f8b1e526370a6c07b75fcb36dc5ffe62871ed888392e3f3d9eeb5ca
 SHA512:
-  metadata.gz: 8965c0c940f603355b3ddb75c9a93fc33e56d839a730bcbe750f2eee6db558cb4fcc2de79e9551ce5431737c8907284a7593abaa63935c84d49268b2a7eb1ed2
-  data.tar.gz: 6c8883368d7b7bc68c823cd73860722a6460543484c2a5b687b4beec7b26f8737f46d935a33fdaf9b5760fc413ba04f6313426e67b4cc624429840ec0d9d12f7
+  metadata.gz: d8e17a56b93c6ab2ab59e5ba5f5bb264f68329f19f7c1801c10e750609be96b3ae2be5dca4117aeae6e41f2d62ae5be757188c6a85bc98548290f1afe6b0aef1
+  data.tar.gz: 7de5823eb5e244c4576723234d7ad6812fded976cd8f22837585a563ded544906d0f2c91114eb748d971056563fe2301a17ce937473538d8c3e507870a5e9929

data/README.md

@@ -19,7 +19,8 @@ gem install bitfab
 ## Requirements
 
 - Ruby >= 3.4
-- No external runtime dependencies (uses stdlib only)
+- Runtime dependencies: `base64`, `opentelemetry-sdk` (`>= 1.2, < 2`, verified against 1.2 through 1.13, so an application already pinning its own OpenTelemetry version does not have to move)
+- Optional: `opentelemetry-exporter-otlp`, only to deliver through an OpenTelemetry Collector. Use a version compatible with your `opentelemetry-sdk`; if the gem cannot load, the SDK warns once and keeps delivering directly to Bitfab
 
 ## Quick Start
 
@@ -355,17 +356,80 @@ end
 
 ### Automatic Flush
 
-Spans are sent in background threads and automatically flushed on exit via `at_exit` hook.
+Spans are queued on a batch worker and delivered on exit via an `at_exit` hook that flushes and shuts the worker down. Every other API call is blocking.
 
 ### Manual Flush
 
 Wait for all pending spans to be sent:
 
 ```ruby
-Bitfab.flush_traces
-# Blocks until all background threads complete
+raise "Bitfab traces were not delivered" unless Bitfab.flush_traces(timeout: 30)
+```
+
+The return value is `false` when an export fails or the deadline expires.
+
+### Closing a Client
+
+A long-running process that builds transient clients should release each one when it is done:
+
+```ruby
+client = Bitfab::Client.new(api_key: ENV.fetch("BITFAB_API_KEY"))
+begin
+  # ... traced work ...
+ensure
+  client.close(timeout: 30)
+end
 ```
 
+A shared client needs no explicit close; `at_exit` shuts remaining transports down.
+
+## OpenTelemetry Transport
+
+Bitfab keeps its public API (`Bitfab::Traceable`, `bitfab_span`, `Bitfab.span`), while one private
+OpenTelemetry `TracerProvider` and `BatchSpanProcessor` per client manage the bounded queue, batch
+worker, export scheduling, flush, and shutdown lifecycle. Pipelines are created lazily on the first
+trace send and are never installed globally, so an unused or disabled client starts no OTel worker
+and the SDK does not replace an application's own OpenTelemetry setup.
+
+By default, batches are sent directly to Bitfab as OTLP/JSON. To send through a local OTel Collector
+instead, add the `opentelemetry-exporter-otlp` gem and set `BITFAB_OTEL_EXPORTER_ENDPOINT` to the
+Collector's OTLP/HTTP base URL (for example, `http://localhost:4318`). The SDK appends `/v1/traces`
+and sends protobuf through OTel's official exporter. Production and replay traffic share the same
+pipeline. Before finalizing a replay, the SDK flushes OTel and polls Bitfab's replay-status API
+until every expected trace completion and span count is persisted, so Collector acceptance is never
+mistaken for Bitfab persistence.
+
+Direct requests carry at most eight carriers each and up to 32 run concurrently; set
+`BITFAB_OTEL_EXPORT_CONCURRENCY` to an integer from `1` through `64` to tune that. Direct JSON and
+Collector protobuf requests are partitioned at roughly 3 MB; set `BITFAB_OTEL_MAX_REQUEST_BYTES` to
+a positive integer no greater than `3000000` for a Collector or proxy with a stricter limit.
+Invalid values warn once and fall back to the defaults. If Bitfab accepts only part of a batch, it
+returns the standard OTLP `partialSuccess` response and the SDK warns with the rejected-span count
+and reason.
+
+```yaml
+receivers:
+  otlp:
+    protocols:
+      http:
+
+exporters:
+  otlphttp/bitfab:
+    endpoint: https://bitfab.ai/api/sdk/otel
+    encoding: json
+    headers:
+      Authorization: Bearer ${env:BITFAB_API_KEY}
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      exporters: [otlphttp/bitfab]
+```
+
+See the [OpenTelemetry Transport Architecture](https://docs.bitfab.ai/otel-architecture) for the
+full component ownership, carrier format, replay barrier, batching, and lifecycle design.
+
 ### Reset Client
 
 Clear the global client (useful for testing):

data/lib/bitfab/client.rb

@@ -42,8 +42,6 @@ module Bitfab
       # The key is NOT read here. HttpClient gets a proc so the key is resolved
       # at send time, after any env loading has run.
       @http_client = HttpClient.new(api_key: -> { resolve_api_key }, service_url: @service_url)
-      @pending_span_threads = {}
-      @pending_span_mutex = Mutex.new
       # Mock overrides registered via register_mock_override, applied to every
       # replay on this client (after any per-call mock_override). Instance
       # state, no global; clear_mock_overrides resets it.
@@ -57,6 +55,25 @@ module Bitfab
       @api_key_config.respond_to?(:call) ? @api_key_config.call : @api_key_config
     end
 
+    # Flush and permanently close this client's tracing transport, releasing its
+    # batch worker. Long-running processes that build transient clients should
+    # call this; a shared client is closed at process exit.
+    #
+    # @param timeout [Numeric] maximum total seconds to wait
+    # @return [Boolean] true when everything queued was delivered in time
+    def close(timeout: 30)
+      @http_client.close(timeout:)
+    end
+
+    # Wait for the spans and traces this client queued to be delivered, without
+    # closing it.
+    #
+    # @param timeout [Numeric] maximum total seconds to wait
+    # @return [Boolean] true when everything queued was delivered in time
+    def flush(timeout: 30)
+      @http_client.flush(timeout:)
+    end
+
     # Effective tracing state, evaluated lazily: enabled only when not
     # explicitly disabled AND a key resolves. Reading this resolves the key
     # (and may emit the one-time empty-key warning), exactly as the first traced
@@ -294,10 +311,6 @@ module Bitfab
           )
         end
 
-        if is_root_span
-          @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
-        end
-
         # Advance the per-(key, name) call counter for any non-root span under
         # an active mock tree, even when this span won't itself be mocked.
         # Unmarked spans must consume an index so subsequent marked siblings
@@ -332,10 +345,7 @@ module Bitfab
       rescue
         # Clean up any trace state this partial setup registered so it does not
         # leak.
-        if trace_id
-          TraceState.delete(trace_id)
-          @pending_span_mutex.synchronize { @pending_span_threads.delete(trace_id) }
-        end
+        TraceState.delete(trace_id) if trace_id
         # During replay (a controlled eval) a setup failure must surface, not
         # silently run the block untraced: swallowing it would execute real code
         # with real side effects and skew the mock call counter, defeating the
@@ -366,7 +376,7 @@ module Bitfab
         begin
           ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
 
-          span_thread = send_span(
+          send_span(
             trace_function_key:,
             trace_id:,
             span_id:,
@@ -387,10 +397,6 @@ module Bitfab
           )
 
           if is_root_span
-            pending = @pending_span_mutex.synchronize { @pending_span_threads.delete(trace_id) || [] }
-            pending << span_thread if span_thread
-            pending.each { |t| t.join(5) }
-
             # Built AFTER the wrapped method finished (finalize runs at root
             # span end), so :accessed reflects whether customer code obtained
             # the branch URL during this item. nil (key omitted) when no
@@ -409,29 +415,13 @@ module Bitfab
               }
             end
 
-            completion_thread = send_trace_completion(
+            send_trace_completion(
               trace_function_key:,
               trace_id:,
               started_at:,
               ended_at:,
               db_snapshot_usage:
             )
-
-            # 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)
-            end
           end
         rescue Exception # rubocop:disable Lint/RescueException
           # Silently ignore: user's result/exception takes priority
@@ -633,14 +623,10 @@ module Bitfab
         payload["testRunId"] = trace_state[:test_run_id]
       end
 
-      completion_thread = @http_client.send_external_trace(payload)
+      @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:,
@@ -649,8 +635,7 @@ module Bitfab
       # If drop() was called on this trace, suppress the span PAYLOAD upload for
       # every span that completes after the flag was set. The trace completion
       # still rides out with dropped: true, so the server scrubs any sibling
-      # spans that already raced out before the flag was set. Returning nil
-      # signals "no span thread" to the caller, which already handles nil.
+      # spans that already raced out before the flag was set.
       trace_dropped = TraceState.get(trace_id)&.dig(:dropped) == true
       return nil if trace_dropped
 
@@ -835,16 +820,12 @@ module Bitfab
 
     # Record a span entry for a mocked invocation so the test run reflects the
     # mocked execution. Mirrors send_span's payload shape but with the mocked
-    # output as the result and no error. The returned background thread is
-    # registered with @pending_span_threads so the root span's finalize joins
-    # it before sending trace completion; without this the trace completion
-    # can race ahead of the mocked span's HTTP send and the trace lands
-    # temporarily incomplete on the server.
+    # output as the result and no error.
     def send_mocked_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
       span_name:, span_type:, function_name:, args:, kwargs:, mocked_output:,
       started_at:, test_run_id:, input_source_span_id:)
       ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
-      span_thread = send_span(
+      send_span(
         trace_function_key:,
         trace_id:,
         span_id:,
@@ -864,12 +845,6 @@ module Bitfab
         input_source_span_id:,
         mocked: true
       )
-      # Mocked spans are always non-root (advance_mock_counter returns nil for
-      # root spans, so check_mock_replay never short-circuits them), so the
-      # thread always belongs in the parent's pending list, never standalone.
-      @pending_span_mutex.synchronize do
-        @pending_span_threads[trace_id] << span_thread if span_thread && @pending_span_threads.key?(trace_id)
-      end
     rescue Exception # rubocop:disable Lint/RescueException
       # Never crash the host app: mocked span recording is best-effort
     end

data/lib/bitfab/http_client.rb

@@ -6,6 +6,7 @@ require "uri"
 
 require_relative "constants"
 require_relative "serialize"
+require_relative "transport"
 require_relative "version"
 require_relative "warn_once"
 
@@ -20,6 +21,31 @@ module Bitfab
       @api_key = api_key
       @service_url = (service_url || DEFAULT_SERVICE_URL).chomp("/")
       @timeout = timeout
+      @transport_mutex = Mutex.new
+      @transport = nil
+      @closed = false
+    end
+
+    # Flush and permanently close this client's tracing transport.
+    # Returns true when everything it queued was delivered within the deadline.
+    def close(timeout: 30)
+      transport = @transport_mutex.synchronize do
+        current = @transport
+        @transport = nil
+        @closed = true
+        current
+      end
+      return true if transport.nil?
+
+      transport.shutdown(timeout)
+    end
+
+    # Wait for the spans and traces this client queued to be delivered.
+    def flush(timeout: 30)
+      transport = @transport_mutex.synchronize { @transport }
+      return true if transport.nil?
+
+      transport.flush(timeout)
     end
 
     # Make a POST request to the Bitfab API.
@@ -37,7 +63,7 @@ module Bitfab
         http.read_timeout = request_timeout
 
         req = Net::HTTP::Post.new(uri.path, headers)
-        req.body = safe_generate(payload, endpoint)
+        req.body = Serialize.safe_generate(payload)
 
         response = http.request(req)
 
@@ -62,14 +88,9 @@ module Bitfab
       raise last_error
     end
 
-    # Send an external span in a background thread.
-    # Returns the thread for callers that need to await completion.
+    # Queue an external span on this client's trace transport (fire-and-forget).
     def send_external_span(payload)
-      merged = payload.merge("sdkVersion" => VERSION)
-
-      Bitfab._run_in_background do
-        request("/api/sdk/externalSpans", merged, timeout: 30)
-      end
+      trace_transport&.submit("external_span", payload.merge("sdkVersion" => VERSION))
     end
 
     # Make a GET request to the Bitfab API.
@@ -208,54 +229,45 @@ module Bitfab
       )
     end
 
-    # Send an external trace (fire-and-forget in background thread).
+    # Queue an external trace on this client's trace transport (fire-and-forget).
     def send_external_trace(payload)
-      merged = payload.merge("sdkVersion" => VERSION)
+      trace_transport&.submit("external_trace", payload.merge("sdkVersion" => VERSION))
+    end
 
-      Bitfab._run_in_background do
-        request("/api/sdk/externalTraces", merged, timeout: 10)
-      end
+    # Read the replay traces the server has fully persisted so far.
+    def get_replay_status(test_run_id, expected_span_counts)
+      request(
+        "/api/sdk/replay/status",
+        {"testRunId" => test_run_id, "expectedSpanCounts" => expected_span_counts},
+        timeout: 30
+      )
     end
 
     private
 
-    # JSON-encode a request body without ever raising on a stray value.
-    #
-    # Upstream serialization (Serialize.serialize_value) should already have
-    # flattened user data. This is the boundary backstop: if anything
-    # non-serializable still slips through, it is run through serialize_value
-    # (which never 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, endpoint)
-      JSON.generate(payload)
-    rescue => e
-      Bitfab.warn_once(
-        "request-body-stubbed",
-        "a request body held a non-serializable value (#{e.message}); it was " \
-        "stubbed so the span still sends, but the trace may be incomplete or " \
-        "not replayable. Capture a JSON-safe projection of this input to make " \
-        "it replayable."
-      )
+    # Returns nil once the client is closed. A stray traced call after close
+    # must not crash the host app, and raising here would be swallowed by the
+    # span finalize path, dropping the span with no explanation.
+    def trace_transport
+      @transport_mutex.synchronize do
+        if @closed
+          Bitfab.warn_once(
+            "client-closed",
+            "client is closed; dropping spans. Close it after the traced work " \
+            "finishes, or keep one client for the life of the process."
+          )
+          next nil
+        end
 
-      begin
-        JSON.generate(sanitize_payload(payload))
-      rescue
-        # Truly pathological. Still never drop silently: send a marker body.
-        JSON.generate({"error" => "payload_serialize_failed"})
+        @transport ||= Transport.create_trace_transport(
+          api_key: @api_key,
+          direct_sender: method(:send_transport_request)
+        )
       end
     end
 
-    # Serialize each top-level value so a bad or oversize value is stubbed in
-    # place while the payload keeps its object shape. Running serialize_value on
-    # the whole payload could collapse the entire body to a single stub string
-    # (oversize/cyclic), sending a JSON string instead of a span object.
-    def sanitize_payload(payload)
-      return {"error" => "payload_serialize_failed"} unless payload.is_a?(Hash)
-
-      payload.each_with_object({}) do |(k, v), acc|
-        acc[k.to_s] = Serialize.serialize_value(v)
-      end
+    def send_transport_request(endpoint, payload, timeout)
+      request(endpoint, payload, timeout:, max_retries: 1)
     end
 
     # Normalize each entry to a hash with stable string keys, accepting either
@@ -281,39 +293,15 @@ module Bitfab
     end
   end
 
-  # --- Background thread management ---
-
-  @pending_threads_mutex = Mutex.new
-  @pending_threads = []
-
   class << self
-    # Run a block in a background thread with tracking.
-    # Returns the thread for callers that need to join on it.
-    def _run_in_background(&block)
-      thread = Thread.new do
-        block.call
-      rescue => e
-        Bitfab.warn_once(
-          "send-request-failed",
-          "failed to send a request to the backend (further occurrences " \
-          "suppressed): #{e.message}"
-        )
-      ensure
-        @pending_threads_mutex.synchronize { @pending_threads.delete(Thread.current) }
-      end
-
-      @pending_threads_mutex.synchronize { @pending_threads << thread }
-      thread
-    end
-
-    # Wait for all pending background threads to complete.
+    # Wait for queued spans and trace completions to reach the server, within
+    # one total deadline. Returns true when everything landed in time.
     def flush_traces(timeout: 30)
-      threads = @pending_threads_mutex.synchronize { @pending_threads.dup }
-      threads.each { |t| t.join(timeout) }
+      Transport.flush_trace_transports([timeout, 0].max)
     end
   end
 
   at_exit do
-    Bitfab.flush_traces(timeout: 2)
+    Transport.shutdown_trace_transports(4)
   end
 end