Jido.Telemetry (Jido v2.0.0-rc.4)

View Source

Production-ready telemetry for Jido Agent operations.

Provides structured, scannable logging with intelligent filtering to reduce noise while preserving actionable debugging information.

Log Levels

The telemetry system uses three effective log levels:

  • INFO - Developer narrative for user-facing interactions (request start/stop)
  • DEBUG - Interesting events only (slow operations, signals with directives, errors)
  • TRACE - Fine-grained internal churn (every signal/directive) - opt-in via config

Configuration

Configure via application environment:

config :jido, :telemetry,
  log_level: :debug,                    # :trace | :debug | :info
  slow_signal_threshold_ms: 10,         # Log signals slower than this
  slow_directive_threshold_ms: 5,       # Log directives slower than this
  interesting_signal_types: [           # Always log these signal types
    "jido.agent.user_request",
    "jido.tool.result",
    "jido.llm.done"
  ],
  log_prompts: false,                   # Privacy: don't log LLM prompts
  log_tool_args: :keys_only             # :keys_only | :full | :none

"Interestingness" Filtering

At DEBUG level, signals are only logged if they are "interesting":

  • Duration exceeds slow_signal_threshold_ms
  • Produced one or more directives
  • Signal type is in interesting_signal_types
  • An error occurred

This reduces log spam from high-frequency internal signals while preserving visibility into operations that matter.

Structured Output

All log entries include structured metadata for filtering and correlation:

  • trace_id, span_id - For distributed tracing
  • agent_id, agent_module - Agent identification
  • signal_type, directive_count, directive_types - What happened
  • duration - Formatted timing (e.g., "12.3ms")

Events

Agent Events

  • [:jido, :agent, :cmd, :start] - Agent command execution started
  • [:jido, :agent, :cmd, :stop] - Agent command execution completed
  • [:jido, :agent, :cmd, :exception] - Agent command execution failed

AgentServer Events

  • [:jido, :agent_server, :signal, :start] - Signal processing started
  • [:jido, :agent_server, :signal, :stop] - Signal processing completed
  • [:jido, :agent_server, :signal, :exception] - Signal processing failed
  • [:jido, :agent_server, :directive, :start] - Directive execution started
  • [:jido, :agent_server, :directive, :stop] - Directive execution completed
  • [:jido, :agent_server, :directive, :exception] - Directive execution failed
  • [:jido, :agent_server, :queue, :overflow] - Directive queue overflow

Strategy Events

  • [:jido, :agent, :strategy, :init, :start] - Strategy initialization started
  • [:jido, :agent, :strategy, :init, :stop] - Strategy initialization completed
  • [:jido, :agent, :strategy, :init, :exception] - Strategy initialization failed
  • [:jido, :agent, :strategy, :cmd, :start] - Strategy command execution started
  • [:jido, :agent, :strategy, :cmd, :stop] - Strategy command execution completed
  • [:jido, :agent, :strategy, :cmd, :exception] - Strategy command execution failed
  • [:jido, :agent, :strategy, :tick, :start] - Strategy tick started
  • [:jido, :agent, :strategy, :tick, :stop] - Strategy tick completed
  • [:jido, :agent, :strategy, :tick, :exception] - Strategy tick failed

Summary

Types

event_name()

Supported telemetry event names.

measurements()

Telemetry measurements map.

metadata()

Telemetry metadata map.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

handle_event(list, measurements, metadata, config)

Handles telemetry events for agent and strategy operations.

span_agent_cmd(agent, action, func)

Executes an agent command while emitting telemetry events.

span_strategy(agent, operation, strategy_module, func)

Executes a strategy operation while emitting telemetry events.

start_link(opts)

Starts the telemetry handler.

Types

event_name()

@type event_name() :: [atom(), ...]

Supported telemetry event names.

measurements()

@type measurements() :: %{
  optional(:system_time) => integer(),
  optional(:duration) => integer(),
  required(atom()) => term()
}

Telemetry measurements map.

metadata()

@type metadata() :: %{
  optional(:agent_id) => String.t(),
  optional(:agent_module) => module(),
  optional(:strategy) => module(),
  optional(:action) => term(),
  optional(:directive_count) => non_neg_integer(),
  optional(:error) => term(),
  required(atom()) => term()
}

Telemetry metadata map.

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

handle_event(list, measurements, metadata, config)

@spec handle_event(event_name(), measurements(), metadata(), config :: term()) :: :ok

Handles telemetry events for agent and strategy operations.

Uses intelligent filtering to reduce noise while preserving actionable information. Events are logged based on "interestingness" criteria configured via Jido.Telemetry.Config.

span_agent_cmd(agent, action, func)

@spec span_agent_cmd(Jido.Agent.t(), term(), (-> result)) :: result
when result: term()

Executes an agent command while emitting telemetry events.

Examples

Jido.Telemetry.span_agent_cmd(agent, action, fn ->
  # Execute command logic
  {updated_agent, directives}
end)

span_strategy(agent, operation, strategy_module, func)

@spec span_strategy(Jido.Agent.t(), :init | :cmd | :tick, module(), (-> result)) ::
  result
when result: term()

Executes a strategy operation while emitting telemetry events.

Examples

Jido.Telemetry.span_strategy(agent, :init, strategy_module, fn ->
  # Execute strategy logic
  {updated_agent, directives}
end)

start_link(opts)

@spec start_link(keyword()) :: GenServer.on_start()

Starts the telemetry handler.