# `Jido.Telemetry`
[🔗](https://github.com/agentjido/jido/blob/v2.3.3/lib/jido/telemetry.ex#L1)

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
- `[:jido, :agent_server, :cron, :register]` - Dynamic cron registered
- `[:jido, :agent_server, :cron, :cancel]` - Dynamic cron cancelled
- `[:jido, :agent_server, :cron, :restart_scheduled]` - Dynamic cron restart scheduled
- `[:jido, :agent_server, :cron, :restart_succeeded]` - Dynamic cron restart completed
- `[:jido, :agent_server, :cron, :persist_failure]` - Cron persistence failed

### 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

# `event_name`

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

Supported telemetry event names.

# `measurements`

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

Telemetry measurements map.

# `metadata`

```elixir
@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.

# `handle_event`

```elixir
@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`.

# `metrics`

```elixir
@spec metrics() :: [Telemetry.Metrics.t()]
```

Returns telemetry metric definitions with automatic per-instance scoping.

Wire these into your reporter in your application:

    TelemetryMetricsPrometheus.init(Jido.Telemetry.metrics())

# `setup`

```elixir
@spec setup() :: :ok
```

Attaches telemetry handlers. Idempotent — safe to call multiple times.
Called from application startup.

# `span_agent_cmd`

> This function is deprecated. Use Jido.Observe.with_span/3 instead.

```elixir
@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`

> This function is deprecated. Use Jido.Observe.with_span/3 instead.

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