AgentSessionManager.Telemetry (AgentSessionManager v0.1.1)

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, ...]:

[: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

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
)

Summary

Functions

emit_adapter_event(run, session, event_data)

Emits an adapter event with the proper telemetry namespace.

emit_error(run, session, error)

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

emit_run_end(run, session, result)

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

emit_run_start(run, session)

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

emit_usage_metrics(session, metrics)

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

enabled?()

Returns whether telemetry is enabled.

set_enabled(enabled)

Enables or disables telemetry for the current process.

span(run, session, func)

Wraps a function execution with telemetry events.

Functions

emit_adapter_event(run, session, event_data)

@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(run, session, error)

@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(run, session, result)

@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(run, session)

@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(session, metrics)

@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?()

@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(enabled)

@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(run, session, func)

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