> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Events & Observability

> Python API reference for Events & Observability.

Event emission and observability: subscribe to session and pipeline events, and
configure logging, metrics, and tracing for a running agent.

## EventEmitter

Lightweight event emitter supporting synchronous and asynchronous handlers.

Handlers are registered against events and invoked when the corresponding
event is emitted. Coroutine handlers are scheduled on the running event loop,
or run to completion if no loop is active. Exceptions raised by handlers are
logged and do not propagate to the caller.

The emitter is generic over the event key type `T`; event keys are coerced
to strings internally.

### Constructor

```python theme={null}
EventEmitter() -> 'None'
```

### emit

```python theme={null}
def emit(self, event: 'T', *args: 'Any') -> 'None'
```

Emit an event, invoking all registered handlers with the given arguments.

Handlers are called in registration order. Coroutine handlers are
scheduled on the running event loop. If the emitter is closed, the call
is a no-op.

<ParamField path="event" type="T" required>
  The event to emit.
</ParamField>

### off

```python theme={null}
def off(self, event: 'T', callback: 'Callable[..., Any]') -> 'None'
```

Remove a previously registered handler for an event.

If the handler is not registered for the event, the call is a no-op.

<ParamField path="event" type="T" required>
  The event the handler was registered for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any]" required>
  The handler to remove.
</ParamField>

### on

```python theme={null}
def on(self, event: 'T', callback: 'Callable[..., Any] | None' = None) -> 'Callable[..., Any]'
```

Register a handler for an event.

Can be used directly by passing a callback, or as a decorator when
`callback` is omitted.

<ParamField path="event" type="T" required>
  The event to listen for.
</ParamField>

<ParamField path="callback" type="Callable[..., Any] | None">
  The handler to invoke when the event is emitted. If `None`, a decorator is returned that registers the decorated function.
</ParamField>

<ResponseField name="returns" type="Callable[..., Any]">
  The registered callback when `callback` is provided, otherwise a decorator that registers and returns the function it wraps.
</ResponseField>

***

## MetricsOptions

### Fields

<ParamField path="enabled" type="bool" default="True" />

<ParamField path="export_url" type="Optional[str]" />

<ParamField path="export_headers" type="Optional[Dict[str, str]]" />

***

## TracesOptions

### Fields

<ParamField path="enabled" type="bool" default="True" />

<ParamField path="export_url" type="Optional[str]" />

<ParamField path="export_headers" type="Optional[Dict[str, str]]" />

***

## LoggingOptions

### Fields

<ParamField path="enabled" type="bool" default="False" />

<ParamField path="level" type="'str | list[str]'" default="INFO" />

<ParamField path="export_url" type="Optional[str]" />

<ParamField path="export_headers" type="Optional[Dict[str, str]]" />

***

## ObservabilityOptions

### Fields

<ParamField path="traces" type="Optional[TracesOptions]" />

<ParamField path="metrics" type="Optional[MetricsOptions]" />

<ParamField path="logs" type="Optional[LoggingOptions]" />

***

## setup\_logging

```python theme={null}
def setup_logging(level=20)
```

Configure the `zrt.agents` logger with a colorized console handler.

Replaces any existing handlers on the `zrt.agents` logger with a single
stream handler writing to standard output. Colorized output is enabled when
the output stream supports it. Propagation to ancestor loggers is disabled.

<ParamField path="level" default="20">
  Logging level to apply to the logger. Defaults to `logging.INFO`.
</ParamField>

<ResponseField name="returns">
  The configured `zrt.agents` `logging.Logger` instance.
</ResponseField>