Class: Bitfab::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/bitfab/client.rb

Constant Summary collapse

SPAN_TYPES = 
%w[llm agent function guardrail handoff custom].freeze
MOCK_REPLAY_MISS =

Sentinel returned by check_mock_replay when this span should run real code (no mock active, wrong strategy, or no matching historical entry). Using a sentinel rather than nil/false avoids confusing legitimate mocked outputs (which may themselves be nil or false).

Object.new.freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api_key:, service_url: nil, enabled: true) ⇒ Client

Returns a new instance of Client.



24
25
26
27
28
29
30
31
32
33
34
35
 
# File 'lib/bitfab/client.rb', line 24

def initialize(api_key:, service_url: nil, enabled: true)
  @api_key = api_key
  @service_url = service_url || DEFAULT_SERVICE_URL
  @enabled = enabled
  if @enabled && (@api_key.nil? || @api_key.to_s.strip.empty?)
    warn "Bitfab: api_key is empty — tracing is disabled. Provide a valid API key to enable tracing."
    @enabled = false
  end
  @http_client = HttpClient.new(api_key:, service_url: @service_url)
  @pending_span_threads = {}
  @pending_span_mutex = Mutex.new
end

Instance Attribute Details

#api_key ⇒ Object (readonly)

Returns the value of attribute api_key.



22
23
24
 
# File 'lib/bitfab/client.rb', line 22

def api_key
  @api_key
end

#enabled ⇒ Object (readonly)

Returns the value of attribute enabled.



22
23
24
 
# File 'lib/bitfab/client.rb', line 22

def enabled
  @enabled
end

#service_url ⇒ Object (readonly)

Returns the value of attribute service_url.



22
23
24
 
# File 'lib/bitfab/client.rb', line 22

def service_url
  @service_url
end

Instance Method Details

#execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:, mock_on_replay: false) ⇒ Object

Execute a block inside a span context, sending trace data on completion. Called by Traceable — not intended for direct use.



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/bitfab/client.rb', line 82

def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:,
  mock_on_replay: false)
  return yield unless @enabled

  parent = SpanContext.current
  trace_id = parent ? parent[:trace_id] : SecureRandom.uuid
  span_id = SecureRandom.uuid
  parent_span_id = parent&.dig(:span_id)
  is_root_span = parent_span_id.nil?
  started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")

  replay_ctx = ReplayContext.current
  resolved_test_run_id = replay_ctx&.dig(:test_run_id)
  resolved_input_source_span_id = replay_ctx&.dig(:input_source_span_id)
  resolved_input_source_trace_id = replay_ctx&.dig(:input_source_trace_id)

  # Register trace state for root spans
  if is_root_span && !TraceState.get(trace_id)
    TraceState.create(
      trace_id,
      test_run_id: resolved_test_run_id,
      input_source_trace_id: resolved_input_source_trace_id
    )
  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
  # line up with `build_mock_tree`'s sequential numbering for the same
  # (key, name) pair. Different (key, name) pairs have independent
  # counters — they cannot shift each other.
  call_index = advance_mock_counter(replay_ctx, trace_function_key, span_name, is_root_span:)
  if call_index
    mocked_output = check_mock_replay(
      replay_ctx, trace_function_key, span_name, call_index, mock_on_replay:
    )
    if mocked_output != MOCK_REPLAY_MISS
      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: resolved_test_run_id,
        input_source_span_id: resolved_input_source_span_id
      )
      return mocked_output
    end
  end

  result = nil
  error = nil
  span_contexts = nil
  span_prompt = nil
  finalized = false

  finalize = lambda do |final_result, final_error|
    # Never crash the host app due to span building/sending. Idempotent —
    # only the first call sends the span. Subsequent calls (e.g. from the
    # enumerator wrapper after iteration completes) are no-ops.
    next if finalized
    finalized = true

    begin
      ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")

      span_thread = send_span(
        trace_function_key:,
        trace_id:,
        span_id:,
        parent_span_id:,
        span_name:,
        span_type:,
        function_name:,
        contexts: span_contexts,
        prompt: span_prompt,
        args:,
        kwargs:,
        result: final_result,
        error: final_error,
        started_at:,
        ended_at:,
        test_run_id: resolved_test_run_id,
        input_source_span_id: resolved_input_source_span_id
      )

      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) }

        send_trace_completion(
          trace_function_key:,
          trace_id:,
          started_at:,
          ended_at:
        )
      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
      # Catches Exception (not just StandardError) to handle SystemStackError
      # from deeply nested serialization
    end
  end

  begin
    SpanContext.with_span(trace_id:, span_id:) do
      result = yield
    ensure
      # Capture contexts before the span context is popped
      span_contexts = SpanContext.current&.dig(:contexts)
      span_prompt = SpanContext.current&.dig(:prompt)
    end
  rescue => e
    error = e.message
    finalize.call(result, error)
    raise
  end

  # If the wrapped block returned an Enumerator (lazy iteration via
  # `enum_for`, `to_enum`, `Enumerator.new`, `[...].lazy.map(...)`, etc.),
  # the work hasn't actually run yet — the values are produced as the
  # caller iterates. Without special handling we'd close the span here
  # with `result == <the Enumerator object>`, and any nested `bitfab_span`
  # calls inside the enumerator body would see an empty span stack and
  # post their own root traces, fragmenting one logical workflow.
  #
  # Instead, hand the caller a wrapping Enumerator whose body restores
  # the parent span stack on the iterating fiber, drives the source,
  # collects yielded values as the span output, and finalizes the span
  # once iteration completes (or errors).
  #
  # Limitation: when the source enumerator itself runs its body in a
  # separate fiber (e.g. `Enumerator.new { |y| ... }` or `enum_for(...)`
  # without a block), nested `bitfab_span` calls inside that body fiber
  # still see an empty stack because `Thread.current[STACK_KEY]` is
  # fiber-local. Lazy chains over collections (`.lazy.map`) and ordinary
  # `each` callbacks DO run in the iterating fiber and nest correctly.
  if result.is_a?(Enumerator)
    return wrap_enumerator(result, trace_id:, span_id:, finalize:)
  end

  finalize.call(result, error)
  result
end

#get_function(trace_function_key) ⇒ BitfabFunction

Get a function wrapper bound to a specific trace function key.

This provides a fluent API for binding a trace_function_key once and then wrapping multiple methods or classes with that key. Mirrors ‘client.get_function(key)` in the Python SDK and `client.getFunction(key)` in the TypeScript SDK.

Examples:

fn = Bitfab.client.get_function("order-processing")
fn.wrap(OrderService, :process_order, type: "function")
fn.wrap(OrderService, :validate_order, type: "guardrail")

Parameters:

  • trace_function_key (String)

Returns:



76
77
78
 
# File 'lib/bitfab/client.rb', line 76

def get_function(trace_function_key)
  BitfabFunction.new(self, trace_function_key)
end

#replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10, code_change_description: nil, code_change_files: nil, mock: "none") ⇒ Hash

Replay historical traces through a method and create a test run.

Parameters:

  • receiver (Object, Class) —

    an instance for instance methods, or a Class for class methods

  • method_name (Symbol) —

    the method to replay

  • trace_function_key (String) —

    the trace function key for this method

  • limit (Integer) (defaults to: 5) —

    maximum number of traces to replay (default: 5)

  • trace_ids (Array<String>, nil) (defaults to: nil) —

    optional list of trace IDs to filter

  • max_concurrency (Integer, nil) (defaults to: 10) —

    max threads for parallel replay (default: 10)

  • code_change_description (String, nil) (defaults to: nil) —

    optional rationale for the code change being tested in this replay (stored on the experiment)

  • code_change_files (Array<Hash>, nil) (defaults to: nil) —

    optional list of edited files, each as { path:, before:, after: } (use “” for new/deleted files)

  • mock (String) (defaults to: "none") —

    mock strategy for child spans: “none” (default), “all”, or “marked”. “all” mocks every child span; “marked” only mocks spans declared with mock_on_replay: true.

Returns:

  • (Hash) —

    with :items, :test_run_id, :test_run_url



53
54
55
56
57
58
59
60
 
# File 'lib/bitfab/client.rb', line 53

def replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10,
  code_change_description: nil, code_change_files: nil, mock: "none")
  Replay.run(
    self, receiver, method_name,
    trace_function_key:, limit:, trace_ids:, max_concurrency:,
    code_change_description:, code_change_files:, mock:
  )
end