Telemetry integration for Legion agents.

Legion emits the following telemetry events:

Agent Lifecycle Events

• [:legion, :agent, :started] — agent process finished init/1

  • Measurements: %{system_time: integer}
  • Metadata: %{agent: module, run_id: reference, parent_run_id: reference}
  • parent_run_id is only present when the agent was started inside another agent's run. Not emitted if init/1 itself crashes (e.g. while building the system prompt) — in that case :stopped is not emitted either, since GenServer does not call terminate/2 on init failure.

• [:legion, :agent, :stopped] — agent process terminated via terminate/2

  • Measurements: %{system_time: integer}
  • Metadata: %{agent: module, run_id: reference} (plus parent_run_id when the parent's run is still on the process Vault)

Agent Message Events (spans)

• [:legion, :agent, :message, :start | :stop | :exception] — agent handling a message

  • Metadata includes: agent, run_id, message
  • Stop adds: iterations (count of assistant turns in this message), status (:ok or :cancel), result (the value returned, or the cancellation reason such as :reached_max_iterations), and bindings (the variable bindings carried out of the turn)

Iteration Events (spans)

• [:legion, :iteration, :start | :stop | :exception]

  • Metadata includes: agent, run_id, iteration
  • Stop adds: action

LLM Request Events (spans)

• [:legion, :llm, :request, :start | :stop | :exception]

  • Metadata includes: agent, run_id, model, message_count, iteration

Sandbox Eval Events (spans)

• [:legion, :sandbox, :eval, :start | :stop | :exception]

  • Metadata includes: agent, run_id, code
  • Stop adds: success, result or error

Default Logger

A default logger is provided that outputs human-readable telemetry to Logger. Attach it with Legion.Telemetry.attach_default_logger/1.