Telemetry integration for Nous AI.

Nous executes the following Telemetry events:

Agent Events

• [:nous, :agent, :run, :start] - Dispatched before agent execution starts

  • Measurement: %{system_time: native_time, monotonic_time: monotonic_time}
  • Metadata: %{agent_name: string, model_provider: atom, model_name: string, tool_count: integer, has_tools: boolean}

• [:nous, :agent, :run, :stop] - Dispatched after agent execution completes

  • Measurement: %{duration: native_time, total_tokens: integer, input_tokens: integer, output_tokens: integer, tool_calls: integer, requests: integer, iterations: integer}
  • Metadata: %{agent_name: string, model_provider: atom, model_name: string}

• [:nous, :agent, :run, :exception] - Dispatched when agent execution fails

  • Measurement: %{duration: native_time}
  • Metadata: %{agent_name: string, model_provider: atom, kind: atom, reason: term, stacktrace: list}

• [:nous, :agent, :iteration, :start] - Dispatched before each agent iteration

  • Measurement: %{system_time: native_time}
  • Metadata: %{agent_name: string, iteration: integer, max_iterations: integer}

• [:nous, :agent, :iteration, :stop] - Dispatched after each agent iteration

  • Measurement: %{duration: native_time}
  • Metadata: %{agent_name: string, iteration: integer, tool_calls: integer, needs_response: boolean}

Provider Events

• [:nous, :provider, :request, :start] - Dispatched before calling provider API

  • Measurement: %{system_time: native_time, monotonic_time: monotonic_time}
  • Metadata: %{provider: atom, model_name: string, message_count: integer}

• [:nous, :provider, :request, :stop] - Dispatched after provider responds

  • Measurement: %{duration: native_time, input_tokens: integer, output_tokens: integer, total_tokens: integer}
  • Metadata: %{provider: atom, model_name: string, has_tool_calls: boolean}

• [:nous, :provider, :request, :exception] - Dispatched when provider request fails

  • Measurement: %{duration: native_time}
  • Metadata: %{provider: atom, model_name: string, kind: atom, reason: term}

Provider Streaming Events

• [:nous, :provider, :stream, :start] - Dispatched before starting a streaming request

  • Measurement: %{system_time: native_time, monotonic_time: monotonic_time}
  • Metadata: %{provider: atom, model_name: string, message_count: integer}

• [:nous, :provider, :stream, :connected] - Dispatched when stream connection is established

  • Measurement: %{duration: native_time}
  • Metadata: %{provider: atom, model_name: string}

• [:nous, :provider, :stream, :exception] - Dispatched when streaming request fails

  • Measurement: %{duration: native_time}
  • Metadata: %{provider: atom, model_name: string, kind: atom, reason: term}

Tool Events

• [:nous, :tool, :execute, :start] - Dispatched before tool execution

  • Measurement: %{system_time: native_time, monotonic_time: monotonic_time}

  • Metadata: %{tool_name: string, tool_module: module | nil, attempt: integer, max_retries: integer, has_timeout: boolean}

• [:nous, :tool, :execute, :stop] - Dispatched after tool completes

  • Measurement: %{duration: native_time}
  • Metadata: %{tool_name: string, attempt: integer, success: boolean}

• [:nous, :tool, :execute, :exception] - Dispatched when tool fails

  • Measurement: %{duration: native_time}
  • Metadata: %{tool_name: string, attempt: integer, will_retry: boolean, kind: atom, reason: term, stacktrace: list}

• [:nous, :tool, :timeout] - Dispatched when tool times out

  • Measurement: %{timeout: integer}
  • Metadata: %{tool_name: string}

Context Events

• [:nous, :context, :update] - Dispatched when context deps are updated by a tool
  • Measurement: %{keys_updated: integer}
  • Metadata: %{agent_name: string, keys: list(atom)}

Callback Events

• [:nous, :callback, :execute] - Dispatched when a callback is executed
  • Measurement: %{duration: native_time}
  • Metadata: %{callback_type: atom, agent_name: string}

Fallback Events

• [:nous, :agent, :fallback, :used] - Dispatched when an iteration switches to a fallback model (sticky-fallback). Use this to alert on provider degradation.

  • Measurement: %{system_time: native_time}
  • Metadata: %{agent_name, original_provider, original_model, active_provider, active_model}

• [:nous, :fallback, :activated] - Dispatched when the fallback chain promotes to the next model after the primary returns an error.

  • Measurement: depends on the call site
  • Metadata: includes the active model and the reason for activation

Hook Events

• [:nous, :hook, :execute, :start] / [:nous, :hook, :execute, :stop]

  • Measurement: %{system_time | duration}

  • Metadata: %{event, hook_name, hook_type, result?}
• [:nous, :hook, :denied] - emitted when a blocking hook returns :deny or when a fail_closed hook errors.
  • Metadata: %{event, hook_name, hook_type, reason?}

Skill Events

• [:nous, :skill, :activate] / [:nous, :skill, :deactivate]
  • Metadata: %{skill_name, agent_name}

Workflow Events

• [:nous, :workflow, :run, :start] / [:nous, :workflow, :run, :stop] / [:nous, :workflow, :run, :exception]
• [:nous, :workflow, :node, :start] / [:nous, :workflow, :node, :stop] / [:nous, :workflow, :node, :exception]
  • See Nous.Workflow.Telemetry for full measurement/metadata payloads.

All times are in :native time unit. Use System.convert_time_unit/3 to convert to desired unit.

Default Handler

Nous provides a default handler that logs events at appropriate levels:

Nous.Telemetry.attach_default_handler()

This is useful for development and debugging.

Custom Handlers

:telemetry.attach(
  "my-nous-handler",
  [:nous, :agent, :run, :stop],
  fn _event, measurements, metadata, _config ->
    MyApp.Metrics.track_agent_run(
      metadata.agent_name,
      measurements.duration,
      measurements.total_tokens
    )
  end,
  nil
)

Metrics Integration

For production metrics, consider integrating with:

• telemetry_metrics for Prometheus/StatsD

• telemetry_poller for periodic metrics

• Phoenix LiveDashboard for visualization

  defmodule MyApp.Telemetry do

  use Supervisor
  import Telemetry.Metrics
  
  def metrics do
    [
      counter("nous.agent.run.start.count"),
      distribution("nous.agent.run.stop.duration",
        unit: {:native, :millisecond}
      ),
      sum("nous.agent.run.stop.total_tokens"),
      counter("nous.tool.execute.stop.count",
        tags: [:tool_name]
      ),
      counter("nous.tool.timeout.count",
        tags: [:tool_name]
      )
    ]
  end

  end

Examples

Every event above is a plain :telemetry event, so attaching to one is just :telemetry.attach/4. This handler forwards tool timeouts to the calling process — the same shape you would use in a test to assert an event fired:

iex> :telemetry.attach(
...>   "nous-doc-example",
...>   [:nous, :tool, :timeout],
...>   fn _event, measurements, metadata, pid ->
...>     send(pid, {:tool_timeout, metadata.tool_name, measurements.timeout})
...>   end,
...>   self()
...> )
:ok
iex> :telemetry.execute([:nous, :tool, :timeout], %{timeout: 5000}, %{tool_name: "bash"})
:ok
iex> receive do
...>   {:tool_timeout, tool_name, timeout} -> {tool_name, timeout}
...> after
...>   0 -> :no_event
...> end
{"bash", 5000}
iex> :telemetry.detach("nous-doc-example")
:ok

Durations are in :native units, so convert before reporting them:

iex> System.convert_time_unit(System.convert_time_unit(120, :millisecond, :native), :native, :millisecond)
120

For local development, skip the wiring entirely and let Nous log everything it emits:

Nous.Telemetry.attach_default_handler()
{:ok, result} = Nous.run(agent, "Summarise this file")
# [Nous] Agent assistant completed in 1832ms (947 tokens, 1 tool calls, 2 iterations)
Nous.Telemetry.detach_default_handler()