Central system for capturing and querying tracer events.
The TracerSystem coordinates event recording through an EventStore and provides convenience methods for recording different types of events (LLM calls, tool calls, agent interactions) and querying them.
Usage
# Start a tracer system
{:ok, tracer} = TracerSystem.start_link()
# Record an LLM call
TracerSystem.record_llm_call(tracer,
model: "gpt-4",
messages: [%{role: "user", content: "Hello"}],
temperature: 0.7,
correlation_id: "abc-123"
)
# Record an LLM response
TracerSystem.record_llm_response(tracer,
model: "gpt-4",
content: "Hello! How can I help?",
call_duration_ms: 123.45,
correlation_id: "abc-123"
)
# Query events
events = TracerSystem.get_events(tracer)
llm_calls = TracerSystem.get_events(tracer, event_type: LLMCallTracerEvent)
# Enable/disable tracing
TracerSystem.disable(tracer)
TracerSystem.enable(tracer)
# Clear events
TracerSystem.clear(tracer)Integration
To integrate with LLM components, pass the tracer as an option:
broker = Broker.new("gpt-4", gateway, tracer: tracer)
{:ok, response} = Broker.generate(broker, messages, tools: [tool])The broker will automatically record LLM calls and responses.
Summary
Functions
Returns a specification to start this module under a supervisor.
Clears all events from the tracer.
Disables the tracer system.
Enables the tracer system.
Checks if the tracer is enabled.
Retrieves events from the tracer with optional filtering.
Gets the last N tracer events, optionally filtered by type.
Records an agent interaction event.
Records a generic tracer event.
Records an LLM call event.
Records an LLM response event.
Records a tool call event.
Starts the TracerSystem GenServer.
Functions
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec clear(GenServer.server()) :: :ok
Clears all events from the tracer.
Examples
:ok = TracerSystem.clear(tracer)@spec disable(GenServer.server()) :: :ok
Disables the tracer system.
When disabled, events will not be recorded.
Examples
:ok = TracerSystem.disable(tracer)@spec enable(GenServer.server()) :: :ok
Enables the tracer system.
When enabled, events will be recorded.
Examples
:ok = TracerSystem.enable(tracer)@spec enabled?(GenServer.server()) :: boolean()
Checks if the tracer is enabled.
Examples
true = TracerSystem.enabled?(tracer)@spec get_events( GenServer.server(), keyword() ) :: [Mojentic.Tracer.TracerEvents.TracerEvent.t()]
Retrieves events from the tracer with optional filtering.
See EventStore.get_events/2 for filter options.
Examples
# Get all events
events = TracerSystem.get_events(tracer)
# Filter by type
llm_calls = TracerSystem.get_events(tracer, event_type: LLMCallTracerEvent)
# Filter by time and type
events = TracerSystem.get_events(tracer,
event_type: ToolCallTracerEvent,
start_time: start_timestamp,
end_time: end_timestamp
)
# Custom filter
events = TracerSystem.get_events(tracer,
filter_func: fn event -> event.correlation_id == "abc-123" end
)@spec get_last_n_tracer_events(GenServer.server(), non_neg_integer(), keyword()) :: [ Mojentic.Tracer.TracerEvents.TracerEvent.t() ]
Gets the last N tracer events, optionally filtered by type.
Examples
# Get last 10 events
recent = TracerSystem.get_last_n_tracer_events(tracer, 10)
# Get last 5 LLM responses
recent = TracerSystem.get_last_n_tracer_events(tracer, 5,
event_type: LLMResponseTracerEvent
)@spec record_agent_interaction( GenServer.server(), keyword() ) :: :ok
Records an agent interaction event.
Options
:from_agent- Name of sending agent (required):to_agent- Name of receiving agent (required):event_type- Type of event (required):event_id- Event identifier (default: nil):source- Source module (default: TracerSystem):correlation_id- Correlation ID for tracing (required)
Examples
TracerSystem.record_agent_interaction(tracer,
from_agent: "AgentA",
to_agent: "AgentB",
event_type: "request",
event_id: "event-123",
correlation_id: "abc-123"
)@spec record_event(GenServer.server(), Mojentic.Tracer.TracerEvents.TracerEvent.t()) :: :ok
Records a generic tracer event.
Examples
event = %TracerEvent{
timestamp: System.os_time(:millisecond) / 1000,
correlation_id: "abc-123",
source: MyModule
}
TracerSystem.record_event(tracer, event)@spec record_llm_call( GenServer.server(), keyword() ) :: :ok
Records an LLM call event.
Options
:model- The LLM model being called (required):messages- Messages sent to the LLM (required):temperature- Temperature setting (default: 1.0):tools- Available tools (default: nil):source- Source module (default: TracerSystem):correlation_id- Correlation ID for tracing (required)
Examples
TracerSystem.record_llm_call(tracer,
model: "gpt-4",
messages: [%{role: "user", content: "Hello"}],
temperature: 0.7,
correlation_id: "abc-123"
)@spec record_llm_response( GenServer.server(), keyword() ) :: :ok
Records an LLM response event.
Options
:model- The LLM model that responded (required):content- Response content (required):tool_calls- Tool calls made by the LLM (default: nil):call_duration_ms- Call duration in milliseconds (default: nil):source- Source module (default: TracerSystem):correlation_id- Correlation ID for tracing (required)
Examples
TracerSystem.record_llm_response(tracer,
model: "gpt-4",
content: "Hello! How can I help?",
call_duration_ms: 123.45,
correlation_id: "abc-123"
)@spec record_tool_call( GenServer.server(), keyword() ) :: :ok
Records a tool call event.
Options
:tool_name- Name of the tool (required):arguments- Tool arguments (required):result- Tool result (required):caller- Name of the caller (default: nil):call_duration_ms- Call duration in milliseconds (default: nil):source- Source module (default: TracerSystem):correlation_id- Correlation ID for tracing (required)
Examples
TracerSystem.record_tool_call(tracer,
tool_name: "date_resolver",
arguments: %{"days_offset" => 3},
result: "2024-11-18",
caller: "ChatSession",
call_duration_ms: 5.67,
correlation_id: "abc-123"
)Starts the TracerSystem GenServer.
Options
:event_store- Existing EventStore pid (will create new one if not provided):enabled- Whether tracing is enabled (default: true):on_store_callback- Callback function for when events are stored:name- Name to register the GenServer under
Examples
{:ok, tracer} = TracerSystem.start_link()
{:ok, tracer} = TracerSystem.start_link(enabled: false)
{:ok, tracer} = TracerSystem.start_link(name: :my_tracer)