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

Public API for the Mojentic Tracer System.

The tracer system provides observability and debugging capabilities by recording
LLM calls, tool executions, and agent interactions. All events include correlation
IDs for tracing related operations across the system.

## Quick Start

    # Start a tracer
    {:ok, tracer} = Tracer.start_link()

    # Pass to components
    broker = Broker.new("gpt-4", gateway, tracer: tracer)
    {:ok, response} = Broker.generate(broker, messages, tools: [tool])

    # Query events
    events = Tracer.get_events(tracer)
    llm_calls = Tracer.get_events(tracer, event_type: LLMCallTracerEvent)

## Null Tracer

When tracing is not needed, use the null tracer to avoid overhead:

    broker = Broker.new("gpt-4", gateway, tracer: Tracer.null_tracer())

## Event Types

- `TracerEvent` - Base event type
- `LLMCallTracerEvent` - Records LLM calls
- `LLMResponseTracerEvent` - Records LLM responses
- `ToolCallTracerEvent` - Records tool executions
- `AgentInteractionTracerEvent` - Records agent-to-agent interactions

## Filtering Events

    # By type
    llm_calls = Tracer.get_events(tracer, event_type: LLMCallTracerEvent)

    # By time range
    recent = Tracer.get_events(tracer,
      start_time: start_timestamp,
      end_time: end_timestamp
    )

    # By correlation ID
    related = Tracer.get_events(tracer,
      filter_func: fn event -> event.correlation_id == "abc-123" end
    )

    # Last N events
    recent = Tracer.get_last_n_tracer_events(tracer, 10)

## Correlation IDs

Correlation IDs allow tracing related events across system boundaries:

    alias UUID

    correlation_id = UUID.uuid4()

    # Pass the same correlation_id to all related operations
    Tracer.record_llm_call(tracer,
      model: "gpt-4",
      messages: messages,
      correlation_id: correlation_id
    )

    Tracer.record_tool_call(tracer,
      tool_name: "date_resolver",
      arguments: args,
      result: result,
      correlation_id: correlation_id
    )

    # Query all related events
    related_events = Tracer.get_events(tracer,
      filter_func: fn e -> e.correlation_id == correlation_id end
    )

# `clear`

Clears all events from the tracer.

# `disable`

Disables the tracer system.

# `enable`

Enables the tracer system.

# `enabled?`

Checks if the tracer is enabled.

# `get_events`

Retrieves events from the tracer.

# `get_last_n_tracer_events`

Gets the last N tracer events.

# `null_tracer`

```elixir
@spec null_tracer() :: :null_tracer
```

Returns the singleton null tracer instance.

The null tracer implements the same API as TracerSystem but performs no operations,
following the Null Object Pattern. This eliminates conditional checks in code.

## Examples

    # Use null tracer when tracing is not needed
    broker = Broker.new("gpt-4", gateway, tracer: Tracer.null_tracer())

    # All operations are no-ops
    Tracer.record_llm_call(Tracer.null_tracer(), ...)  # Does nothing
    Tracer.get_events(Tracer.null_tracer())            # Returns []

# `record_agent_interaction`

Records an agent interaction event.

# `record_event`

Records a generic tracer event.

# `record_llm_call`

Records an LLM call event.

# `record_llm_response`

Records an LLM response event.

# `record_tool_call`

Records a tool call event.

# `start_link`

---

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