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

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.



18
19
20
21
22
23
24
25
26
27
28
29
 
# File 'lib/bitfab/client.rb', line 18

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.



16
17
18
 
# File 'lib/bitfab/client.rb', line 16

def api_key
  @api_key
end

#enabled ⇒ Object (readonly)

Returns the value of attribute enabled.



16
17
18
 
# File 'lib/bitfab/client.rb', line 16

def enabled
  @enabled
end

#service_url ⇒ Object (readonly)

Returns the value of attribute service_url.



16
17
18
 
# File 'lib/bitfab/client.rb', line 16

def service_url
  @service_url
end

Instance Method Details

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

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



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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
 
# File 'lib/bitfab/client.rb', line 46

def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:)
  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)

  # 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)
  end

  if is_root_span
    @pending_span_mutex.synchronize { @pending_span_threads[trace_id] = [] }
  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

#replay(receiver, method_name, trace_function_key:, limit: 5, trace_ids: nil, max_concurrency: 10) ⇒ 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)

Returns:

  • (Hash) —

    with :items, :test_run_id, :test_run_url



40
41
42
 
# File 'lib/bitfab/client.rb', line 40

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