# `PtcRunner.TraceLog.Handler`
[🔗](https://github.com/andreasronge/ptc_runner/blob/main/lib/ptc_runner/trace_log/handler.ex#L1)

Telemetry handler that captures SubAgent events for trace logging.

This handler attaches to all SubAgent telemetry events, builds v2 flat
event envelopes, and forwards them to the Collector for writing to a
JSONL file. Events are filtered by process — only events from processes
that have an active collector in their `TraceContext` collector stack
are captured.

On `run.start` events, the handler extracts the full agent config from
telemetry metadata and includes it in the event data so the Collector
can emit a deduplicated `agent.config` event.

# `attach`

```elixir
@spec attach(String.t(), pid(), String.t(), map()) :: :ok | {:error, :already_exists}
```

Attaches the handler to telemetry events.

## Parameters

  * `handler_id` - Unique identifier for this handler attachment
  * `collector` - The Collector process to write events to
  * `trace_id` - The trace ID for this trace session
  * `meta` - Additional metadata to include with events (optional)

## Examples

    Handler.attach("my-trace", collector_pid, "trace-123")

# `detach`

```elixir
@spec detach(String.t()) :: :ok | {:error, :not_found}
```

Detaches the handler from telemetry events.

## Parameters

  * `handler_id` - The handler ID that was used during attachment

## Examples

    Handler.detach("my-trace")

# `events`

```elixir
@spec events() :: [[atom()]]
```

Returns the list of telemetry events this handler subscribes to.

# `handle_event`

```elixir
@spec handle_event([atom()], map(), map(), map()) :: :ok
```

Handles a telemetry event.

Events are only captured if the calling process has the config's collector
in its active `TraceContext` collector stack.

This function never raises — errors are logged at debug level to avoid
crashing the caller's execution.

---

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