Module: Bitfab::Traceable::ClassMethods

Defined in:
lib/bitfab/traceable.rb

Instance Method Summary collapse

Instance Method Details

#bitfab_function(key) ⇒ Object

Set the trace function key for this class. All spans declared in this class will be grouped under this key.

Parameters:

  • key (String) —

    the trace function key



114
115
116
 
# File 'lib/bitfab/traceable.rb', line 114

def bitfab_function(key)
  @bitfab_function_key = key
end

#bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", mock_on_replay: false) ⇒ Object

Declare that a method should be wrapped with span tracing.

Supports three styles:

bitfab_span :foo, type: "function"   # before def foo (uses method_added hook)
def foo; end

bitfab_span def foo                   # inline (def returns :foo, method already exists)
  ...
end, type: "function"

def foo; end                            # after def foo (method already exists)
bitfab_span :foo, type: "function"

Parameters:

  • method_name (Symbol) —

    the method to wrap

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

    trace function key (overrides class-level bitfab_function)

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

    explicit span name (defaults to method name)

  • type (String) (defaults to: "custom") —

    span type: llm, agent, function, guardrail, handoff, custom

  • mock_on_replay (Boolean) (defaults to: false) —

    mark this span for the “marked” mock strategy. When true, ‘client.replay(… mock: “marked”)` returns this span’s historical output instead of executing the wrapped method.



138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/bitfab/traceable.rb', line 138

def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom", 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` " \
          "or call `bitfab_function 'my-key'` before using `bitfab_span`."
  end

  # 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:)
  else
    # Method doesn't exist yet (before-method style) — register for method_added hook
    @_bitfab_pending_spans ||= {}
    @_bitfab_pending_spans[method_name] = {
      trace_function_key:,
      name:,
      type:,
      mock_on_replay:
    }
  end
end