bitfab 0.33.3 → 0.33.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44ebaac53c01dd84f179de5559eb3f00836c6c1a51f15520b8f10085bcfd6021
-  data.tar.gz: b7255113aef3706aefd3a1017520f24e6127503418965a0db23e70573fdd3d0e
+  metadata.gz: 40eaaf83e783c54b0a0b373b681d82e1d96b01f4e99a424f68af1fffcd82a79e
+  data.tar.gz: ed01d854b7ed2ee101a6bab9d659bd977c7f5ee6f0cbd0b481675d76dba449ec
 SHA512:
-  metadata.gz: de1b1c86dc8660477b87632d766e6f8fdf858d682248c9bd53d024fb3b423acc18d02d877ff567344e5a80aa686d0ad3e72bb02e8cc7dd099612e28ccdc02ad2
-  data.tar.gz: bb0ea7013f448acffa4644a359c0c38198ce9c74caf2b77c3d4d4c80a3f5b6f6f0bd73591ffd653b97c99af6518bc0c12460d69ac65314faf5d047541d731d1c
+  metadata.gz: 8965c0c940f603355b3ddb75c9a93fc33e56d839a730bcbe750f2eee6db558cb4fcc2de79e9551ce5431737c8907284a7593abaa63935c84d49268b2a7eb1ed2
+  data.tar.gz: 6c8883368d7b7bc68c823cd73860722a6460543484c2a5b687b4beec7b26f8737f46d935a33fdaf9b5760fc413ba04f6313426e67b4cc624429840ec0d9d12f7

data/lib/bitfab/client.rb

@@ -243,12 +243,23 @@ module Bitfab
     # Execute a block inside a span context, sending trace data on completion.
     # Called by Traceable, not intended for direct use.
     def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
-      mock_on_replay: false)
+      capture_when: "always", mock_on_replay: 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.
       return yield unless tracing_enabled?
 
+      resolved_capture_when = capture_when.to_s
+      unless %w[always nested].include?(resolved_capture_when)
+        Bitfab.warn_once(
+          "invalid-capture-when:#{trace_function_key}",
+          "unknown capture_when value #{capture_when.inspect}; defaulting to \"always\". " \
+          "Valid values: \"always\", \"nested\"."
+        )
+        resolved_capture_when = "always"
+      end
+      return yield if resolved_capture_when == "nested" && SpanContext.current.nil?
+
       # Span setup runs before the user's block. Tracing is a side-channel, so
       # if anything here raises (id generation, trace-state bookkeeping, a
       # malformed replay mock tree) the user's method must still run. On failure
@@ -892,12 +903,15 @@ module Bitfab
     # @param method_name [Symbol] the method to wrap
     # @param name [String, nil] explicit span name (defaults to method name)
     # @param type [String] span type
+    # @param capture_when [String, Symbol] "always" to allow a root trace, or
+    #   "nested" to capture only when another Bitfab span is active. Unknown
+    #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy
-    def wrap(klass, method_name, name: nil, type: "custom", mock_on_replay: false)
+    def wrap(klass, method_name, name: nil, type: "custom", capture_when: "always", mock_on_replay: false)
       Bitfab::Traceable.wrap(
         klass, method_name,
         trace_function_key: @trace_function_key,
-        name:, type:, mock_on_replay:,
+        name:, type:, capture_when:, mock_on_replay:,
         client: @client
       )
     end

data/lib/bitfab/replay.rb

@@ -127,10 +127,10 @@ module Bitfab
     #   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 db_branch [Hash, nil] passing it at all turns database branching
-    #   on, so +{}+ enables it with the mirror project's own sizing. Keys
-    #   +:min_cu+/+:max_cu+ are the branch compute's autoscaling floor and
-    #   ceiling in Neon Compute Units, and +:warmup_sql+ warms the branch's
+    # @param db_branch [Boolean, Hash, nil] +true+ branches with the mirror
+    #   project's own sizing; a Hash tunes it and +false+/+nil+ leave branching
+    #   off. Keys +:min_cu+/+:max_cu+ are the branch compute's autoscaling floor
+    #   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
@@ -192,7 +192,7 @@ module Bitfab
       # the count), so it's omitted from the request entirely.
       effective_limit = trace_ids ? nil : (limit || 5)
 
-      include_db_branch_lease = !db_branch.nil?
+      include_db_branch_lease = db_branch_enabled?(db_branch)
 
       # code_change_files controls capture: omitted auto-captures, an array
       # wins, and explicit nil opts out. Preserve a caller-supplied description
@@ -335,16 +335,26 @@ module Bitfab
     CC_MAX_FILE_BYTES = 500_000
     CC_MAX_TOTAL_BYTES = 2_000_000
 
+    # Whether the caller asked for database branching. +true+ and a Hash both
+    # turn it on; +false+ and +nil+ leave it off. Kept separate from
+    # +db_branch_settings+ because +db_branch: true+ enables branching while
+    # contributing no settings, so the presence of settings can't stand in for
+    # the switch.
+    def db_branch_enabled?(db_branch)
+      !db_branch.nil? && db_branch != false
+    end
+
     # Convert the caller's +db_branch+ options to the wire shape, or nil when
     # nothing was set. Dropping the key entirely keeps the request identical to
-    # what older SDKs send.
+    # what older SDKs send. Booleans carry no settings: they only move the
+    # switch.
     #
     # Keys: :min_cu and :max_cu are the branch compute's autoscaling floor and
     # ceiling in Neon Compute Units (equal values pin the size, keeping items
     # comparable); :warmup_sql is appended to the branch's readiness check so it
     # warms the cache before the replayed function sees the lease.
     def db_branch_settings(db_branch)
-      return nil if db_branch.nil? || db_branch.empty?
+      return nil if db_branch.nil? || db_branch == true || db_branch == false || db_branch.empty?
 
       # Symbol or string keys, matching normalize_code_change_files: a hash
       # assembled from JSON or YAML would otherwise be read as empty, leaving

data/lib/bitfab/traceable.rb

@@ -38,6 +38,9 @@ module Bitfab
     # @param trace_function_key [String] the trace function key
     # @param name [String, nil] explicit span name (defaults to method name)
     # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+    # @param capture_when [String, Symbol] "always" to allow a root trace, or
+    #   "nested" to capture only when another Bitfab span is active. Unknown
+    #   values warn once and default to "always"
     # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy.
     #   When true, `client.replay(...)` returns this span's
     #   historical output instead of executing the wrapped method.
@@ -48,7 +51,7 @@ module Bitfab
     #   preserve the bound client through the fluent wrapper, matching Python's
     #   `BitfabFunction.span()` and TypeScript's `BitfabFunction.withSpan()`.
     def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom",
-      mock_on_replay: false, client: nil)
+      capture_when: "always", mock_on_replay: false, client: nil)
       span_name = name || method_name.to_s
       method_name_str = method_name.to_s
       bound_client = client
@@ -63,6 +66,7 @@ module Bitfab
             function_name: method_name_str,
             args:,
             kwargs:,
+            capture_when:,
             mock_on_replay:) do
             super(*args, **kwargs, &block)
           end
@@ -132,10 +136,14 @@ module Bitfab
       # @param trace_function_key [String, nil] trace function key (overrides class-level bitfab_function)
       # @param name [String, nil] explicit span name (defaults to method name)
       # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+      # @param capture_when [String, Symbol] "always" to allow a root trace, or
+      #   "nested" to capture only when another Bitfab span is active. Unknown
+      #   values warn once and default to "always"
       # @param mock_on_replay [Boolean] mark this span for the default "marked" mock strategy.
       #   When true, `client.replay(...)` returns this span's
       #   historical output instead of executing the wrapped method.
-      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", mock_on_replay: false)
+      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom",
+        capture_when: "always", mock_on_replay: false)
         trace_function_key ||= @bitfab_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_span` " \
@@ -144,7 +152,9 @@ module Bitfab
 
         # If the method already exists (inline or after-method style), wrap it immediately
         if method_defined?(method_name) || private_method_defined?(method_name)
-          _bitfab_wrap_method(method_name, trace_function_key:, name:, type:, mock_on_replay:)
+          _bitfab_wrap_method(
+            method_name, trace_function_key:, name:, type:, capture_when:, mock_on_replay:
+          )
         else
           # Method doesn't exist yet (before-method style) - register for method_added hook
           @_bitfab_pending_spans ||= {}
@@ -152,6 +162,7 @@ module Bitfab
             trace_function_key:,
             name:,
             type:,
+            capture_when:,
             mock_on_replay:
           }
         end
@@ -167,7 +178,8 @@ module Bitfab
         _bitfab_wrap_method(method_name, **config)
       end
 
-      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom", mock_on_replay: false)
+      def _bitfab_wrap_method(method_name, trace_function_key:, name: nil, type: "custom",
+        capture_when: "always", mock_on_replay: false)
         span_name = name || method_name.to_s
         method_name_str = method_name.to_s
 
@@ -185,6 +197,7 @@ module Bitfab
               function_name: method_name_str,
               args:,
               kwargs:,
+              capture_when:,
               mock_on_replay:) do
               super(*args, **kwargs, &block)
             end

data/lib/bitfab/version.rb

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

metadata

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