# `Mojentic.Tracer.TracerSystem`
[🔗](https://github.com/svetzal/mojentic-ex/blob/v1.2.0/lib/mojentic/tracer/tracer_system.ex#L1)

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.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `clear`

```elixir
@spec clear(GenServer.server()) :: :ok
```

Clears all events from the tracer.

## Examples

    :ok = TracerSystem.clear(tracer)

# `disable`

```elixir
@spec disable(GenServer.server()) :: :ok
```

Disables the tracer system.

When disabled, events will not be recorded.

## Examples

    :ok = TracerSystem.disable(tracer)

# `enable`

```elixir
@spec enable(GenServer.server()) :: :ok
```

Enables the tracer system.

When enabled, events will be recorded.

## Examples

    :ok = TracerSystem.enable(tracer)

# `enabled?`

```elixir
@spec enabled?(GenServer.server()) :: boolean()
```

Checks if the tracer is enabled.

## Examples

    true = TracerSystem.enabled?(tracer)

# `get_events`

```elixir
@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
    )

# `get_last_n_tracer_events`

```elixir
@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
    )

# `record_agent_interaction`

```elixir
@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"
    )

# `record_event`

```elixir
@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)

# `record_llm_call`

```elixir
@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"
    )

# `record_llm_response`

```elixir
@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"
    )

# `record_tool_call`

```elixir
@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"
    )

# `start_link`

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)

---

*Consult [api-reference.md](api-reference.md) for complete listing*