# `Jido.AI.Observe`
[🔗](https://github.com/agentjido/jido_ai/blob/v2.4.0/lib/jido_ai/observe.ex#L1)

AI observability boundary for telemetry events and spans.

This module centralizes:

- Canonical AI telemetry event names
- Required AI metadata/measurement normalization
- Feature-gated event emission
- Span lifecycle wrappers that honor AI observability config
- Sensitive value redaction helpers for telemetry payloads
- Bounded telemetry and transport-safe payload shaping

# `event_name`

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

# `feature_gate`

```elixir
@type feature_gate() :: :llm_deltas
```

# `measurements`

```elixir
@type measurements() :: map()
```

# `metadata`

```elixir
@type metadata() :: map()
```

# `obs_cfg`

```elixir
@type obs_cfg() :: map() | nil
```

# `sanitize_profile`

```elixir
@type sanitize_profile() :: Jido.AI.Observe.Sanitize.profile()
```

# `span_ctx`

```elixir
@type span_ctx() :: Jido.Observe.span_ctx() | :noop
```

# `emit`

```elixir
@spec emit(obs_cfg(), event_name(), measurements(), metadata(), keyword()) :: :ok
```

Emits an AI telemetry event when enabled in `obs_cfg`.

Supports optional feature gates via `opts`:

- `feature_gate: :llm_deltas`

# `ensure_required_measurements`

```elixir
@spec ensure_required_measurements(map()) :: map()
```

Ensures required AI measurement keys are present with `0` defaults.

# `ensure_required_metadata`

```elixir
@spec ensure_required_metadata(map()) :: map()
```

Ensures required AI metadata keys are present with `nil` defaults.

# `finish_span`

```elixir
@spec finish_span(span_ctx(), measurements()) :: :ok
```

Finishes a span started by `start_span/3`.

# `finish_span_error`

```elixir
@spec finish_span_error(span_ctx(), atom(), term(), list()) :: :ok
```

Finishes a span with error details.

# `llm`

```elixir
@spec llm(atom()) :: event_name()
```

Builds an LLM telemetry event path under `[:jido, :ai, :llm, ...]`.

# `output`

```elixir
@spec output(atom()) :: event_name()
```

Builds a structured output telemetry event path under `[:jido, :ai, :output, ...]`.

# `request`

```elixir
@spec request(atom()) :: event_name()
```

Builds a request telemetry event path under `[:jido, :ai, :request, ...]`.

# `sanitize`

```elixir
@spec sanitize(term(), sanitize_profile(), keyword()) :: term()
```

Sanitizes arbitrary payloads for a specific boundary profile.

The `:telemetry` profile keeps metadata low-cardinality by redacting
sensitive keys, truncating large values, and summarizing payload-shaped
fields such as results and provider responses.

The `:transport` profile preserves more payload detail while converting
arbitrary terms into bounded JSON-safe data.

# `sanitize_sensitive`

```elixir
@spec sanitize_sensitive(term()) :: term()
```

Redacts sensitive keys recursively for telemetry-safe payloads.

# `sanitize_telemetry_metadata`

```elixir
@spec sanitize_telemetry_metadata(term(), keyword()) :: term()
```

Sanitizes event metadata before it crosses the telemetry boundary.

# `sanitize_transport_payload`

```elixir
@spec sanitize_transport_payload(term(), keyword()) :: term()
```

Sanitizes a public/tool payload into bounded JSON-safe data.

# `start_span`

```elixir
@spec start_span(obs_cfg(), event_name(), metadata()) :: span_ctx()
```

Starts a telemetry span when AI telemetry is enabled.

Returns `:noop` when telemetry is disabled or event prefix is invalid.

# `strategy`

```elixir
@spec strategy(atom(), atom()) :: event_name()
```

Builds a strategy telemetry event path under `[:jido, :ai, :strategy, strategy, ...]`.

# `tool`

```elixir
@spec tool(atom()) :: event_name()
```

Builds a tool telemetry event path under `[:jido, :ai, :tool, ...]`.

# `tool_execute`

```elixir
@spec tool_execute(atom()) :: event_name()
```

Builds a tool execution telemetry event path for executor internals.

---

*Consult [api-reference.md](api-reference.md) for complete listing*