# `AgentSessionManager.Telemetry`
[🔗](https://github.com/nshkrdotcom/agent_session_manager/blob/v0.8.0/lib/agent_session_manager/telemetry.ex#L1)

Telemetry event emission for observability.

This module provides functions to emit telemetry events for run lifecycle
and usage metrics. Events follow the `:telemetry` library conventions and
can be consumed by any telemetry handler (e.g., for metrics, logging, tracing).

## Event Names

All events are prefixed with `[:agent_session_manager, ...]`:

### Run Lifecycle
- `[:agent_session_manager, :run, :start]` - Emitted when a run starts
- `[:agent_session_manager, :run, :stop]` - Emitted when a run completes successfully
- `[:agent_session_manager, :run, :exception]` - Emitted when a run fails with an error
- `[:agent_session_manager, :usage, :report]` - Emitted with usage metrics

### Persistence (emitted by `EventPipeline`)
- `[:agent_session_manager, :persistence, :event_persisted]` - Event was validated and persisted
- `[:agent_session_manager, :persistence, :event_validation_warning]` - Event had shape warnings
- `[:agent_session_manager, :persistence, :event_rejected]` - Event failed structural validation
- `[:agent_session_manager, :persistence, :event_redacted]` - Secrets were redacted from an event

## Configuration

Telemetry is enabled by default. Disable it via application config
(global baseline) or at runtime per-process:

    # Global baseline (config.exs)
    config :agent_session_manager, telemetry_enabled: false

    # Per-process override (safe in concurrent tests)
    AgentSessionManager.Telemetry.set_enabled(false)

## Usage

    alias AgentSessionManager.Telemetry

    # Manual event emission
    Telemetry.emit_run_start(run, session)
    Telemetry.emit_run_end(run, session, result)
    Telemetry.emit_error(run, session, error)

    # Or use the span helper for automatic start/stop/exception
    Telemetry.span(run, session, fn ->
      # Do work
      {:ok, result}
    end)

## Attaching Handlers

    :telemetry.attach_many(
      "my-handler",
      [
        [:agent_session_manager, :run, :start],
        [:agent_session_manager, :run, :stop],
        [:agent_session_manager, :run, :exception]
      ],
      &MyHandler.handle_event/4,
      nil
    )

# `emit_adapter_event`

```elixir
@spec emit_adapter_event(
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  map()
) ::
  :ok
```

Emits an adapter event with the proper telemetry namespace.

Events are emitted as `[:agent_session_manager, :adapter, event_type]`.

## Event Types

Common adapter event types include:
- `:run_started` - Execution begins
- `:message_streamed` - Content chunk received
- `:message_received` - Full message ready
- `:tool_call_started` - Tool invocation begins
- `:tool_call_completed` - Tool completes
- `:token_usage_updated` - Usage stats update
- `:run_completed` - Execution finishes
- `:error_occurred` - Error during execution
- `:run_failed` - Execution failed
- `:run_cancelled` - Execution was cancelled

## Measurements

Numeric values from the event data are included as measurements.

## Metadata

- `run_id` - The run identifier
- `session_id` - The session identifier
- `agent_id` - The agent identifier
- `provider` - The provider name (:claude, :codex, etc.)
- `tool_name` - Tool name for tool events (if present)
- `event_data` - The full event data map

# `emit_error`

```elixir
@spec emit_error(
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  map()
) :: :ok
```

Emits a `[:agent_session_manager, :run, :exception]` event.

## Measurements

- `duration` - Duration in native time units (nanoseconds)
- `system_time` - System time when the error occurred

## Metadata

- `run_id` - The run identifier
- `session_id` - The session identifier
- `agent_id` - The agent identifier
- `error_code` - The error code
- `error_message` - The error message
- `run` - The full Run struct
- `session` - The full Session struct

# `emit_run_end`

```elixir
@spec emit_run_end(
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  map()
) :: :ok
```

Emits a `[:agent_session_manager, :run, :stop]` event.

## Measurements

- `duration` - Duration in native time units (nanoseconds)
- `input_tokens` - Number of input tokens (if provided)
- `output_tokens` - Number of output tokens (if provided)
- `total_tokens` - Total tokens (if provided)

## Metadata

- `run_id` - The run identifier
- `session_id` - The session identifier
- `agent_id` - The agent identifier
- `status` - The final run status
- `run` - The full Run struct
- `session` - The full Session struct

# `emit_run_start`

```elixir
@spec emit_run_start(
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t()
) :: :ok
```

Emits a `[:agent_session_manager, :run, :start]` event.

## Measurements

- `system_time` - System time in native units when the run started

## Metadata

- `run_id` - The run identifier
- `session_id` - The session identifier
- `agent_id` - The agent identifier
- `run` - The full Run struct
- `session` - The full Session struct

# `emit_usage_metrics`

```elixir
@spec emit_usage_metrics(AgentSessionManager.Core.Session.t(), map()) :: :ok
```

Emits a `[:agent_session_manager, :usage, :report]` event.

## Measurements

All keys from the metrics map are included as measurements.
Common keys include:
- `input_tokens`
- `output_tokens`
- `total_tokens`
- `cost_usd`

## Metadata

- `session_id` - The session identifier
- `agent_id` - The agent identifier
- `session` - The full Session struct

# `enabled?`

```elixir
@spec enabled?() :: boolean()
```

Returns whether telemetry is enabled.

Checks the process-local override first, then Application environment,
then defaults to `true`. See `AgentSessionManager.Config` for details.

# `set_enabled`

```elixir
@spec set_enabled(boolean()) :: :ok
```

Enables or disables telemetry for the current process.

The override is process-local and automatically cleaned up when the
process exits. This is safe to call in concurrent tests.

# `span`

```elixir
@spec span(
  AgentSessionManager.Core.Run.t(),
  AgentSessionManager.Core.Session.t(),
  (-> {:ok, map()}
      | {:error, map()})
) ::
  {:ok, map()} | {:error, map()}
```

Wraps a function execution with telemetry events.

Automatically emits:
- `[:agent_session_manager, :run, :start]` before execution
- `[:agent_session_manager, :run, :stop]` on `{:ok, result}`
- `[:agent_session_manager, :run, :exception]` on `{:error, error}`

## Example

    Telemetry.span(run, session, fn ->
      # Perform the run
      {:ok, %{output: output, token_usage: usage}}
    end)

---

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