Jido.AI.Observe (Jido AI v2.3.0)

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

Summary

Types

event_name()

feature_gate()

measurements()

metadata()

obs_cfg()

sanitize_profile()

span_ctx()

Functions

emit(obs_cfg, event, measurements \\ %{}, metadata \\ %{}, opts \\ [])

Emits an AI telemetry event when enabled in obs_cfg.

ensure_required_measurements(measurements)

Ensures required AI measurement keys are present with 0 defaults.

ensure_required_metadata(metadata)

Ensures required AI metadata keys are present with nil defaults.

finish_span(span_ctx, extra_measurements)

Finishes a span started by start_span/3.

finish_span_error(span_ctx, kind, reason, stacktrace)

Finishes a span with error details.

llm(event)

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

output(event)

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

request(event)

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

sanitize(payload, profile, opts \\ [])

Sanitizes arbitrary payloads for a specific boundary profile.

sanitize_sensitive(payload)

Redacts sensitive keys recursively for telemetry-safe payloads.

sanitize_telemetry_metadata(metadata, opts \\ [])

Sanitizes event metadata before it crosses the telemetry boundary.

sanitize_transport_payload(payload, opts \\ [])

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

start_span(obs_cfg, event_prefix, metadata \\ %{})

Starts a telemetry span when AI telemetry is enabled.

strategy(strategy, event)

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

tool(event)

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

tool_execute(event)

Builds a tool execution telemetry event path for executor internals.

Types

event_name()

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

feature_gate()

@type feature_gate() :: :llm_deltas

measurements()

@type measurements() :: map()

metadata()

@type metadata() :: map()

obs_cfg()

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

sanitize_profile()

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

span_ctx()

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

Functions

emit(obs_cfg, event, measurements \\ %{}, metadata \\ %{}, opts \\ [])

@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(measurements)

@spec ensure_required_measurements(map()) :: map()

Ensures required AI measurement keys are present with 0 defaults.

ensure_required_metadata(metadata)

@spec ensure_required_metadata(map()) :: map()

Ensures required AI metadata keys are present with nil defaults.

finish_span(span_ctx, extra_measurements)

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

Finishes a span started by start_span/3.

finish_span_error(span_ctx, kind, reason, stacktrace)

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

Finishes a span with error details.

llm(event)

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

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

output(event)

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

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

request(event)

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

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

sanitize(payload, profile, opts \\ [])

@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(payload)

@spec sanitize_sensitive(term()) :: term()

Redacts sensitive keys recursively for telemetry-safe payloads.

sanitize_telemetry_metadata(metadata, opts \\ [])

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

Sanitizes event metadata before it crosses the telemetry boundary.

sanitize_transport_payload(payload, opts \\ [])

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

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

start_span(obs_cfg, event_prefix, metadata \\ %{})

@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(strategy, event)

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

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

tool(event)

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

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

tool_execute(event)

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

Builds a tool execution telemetry event path for executor internals.