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



80
81
82
 
# File 'lib/bitfab/traceable.rb', line 80

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.



104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
 
# File 'lib/bitfab/traceable.rb', line 104

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