Configuration

Copy Markdown View Source

Jido.Otel uses two configuration surfaces:

  • :jido for selecting the tracer implementation.
  • :jido_otel for tracer runtime behavior.
  • :opentelemetry for SDK/exporter behavior.

Jido Observability Config

config :jido, :observability,
  tracer: Jido.Otel.Tracer

Jido.Observe will call:

OpenTelemetry SDK Config

Development baseline:

config :opentelemetry,
  traces_exporter: :none

Example OTLP export (requires corresponding exporter dependency/config in host app):

config :opentelemetry,
  span_processor: :batch,
  traces_exporter: :otlp

Jido.Otel Runtime Config

Use :jido_otel to configure current-span activation behavior:

config :jido_otel,
  current_span_mode: :safe

Valid values:

  • :safe (default): does not set current process span in span_start/2. Recommended for production and async workloads.
  • :activate_unsafe: preserves same-process activation/restore behavior. Use only when you explicitly need legacy current-span activation semantics.

If :activate_unsafe is enabled and span_stop/2 or span_exception/4 runs in another process, restore is skipped and a warning is logged.

Synchronous Jido.Observe.with_span/3 does not depend on :activate_unsafe. Jido.Otel.Tracer.with_span_scope/3 activates the OTel span only while the callback runs in the caller process, which lets nested OTel instrumentation use the Jido span as its parent without leaking current-span context into async finish paths.

Attribute Mapping Rules

Jido.Otel.Tracer sanitizes metadata and measurements into OpenTelemetry attributes:

  • Atom keys become string keys (for example :agent_id -> "agent_id").
  • Atom values become strings.
  • Sensitive keys such as :api_key, :authorization, :password, :secret, and :token are redacted.
  • Raw :stacktrace metadata is omitted from span attributes.
  • Long strings are truncated.
  • Homogeneous primitive lists remain bounded OTel-compatible lists.
  • Complex values are sanitized, bounded, made inspect-safe, and serialized via inspect/2.

Exception spans additionally include:

  • Span status :error
  • Exception event named :exception
  • Attributes error.kind and error.reason

jido_otel is an adapter over Jido's canonical observe/telemetry surfaces. It does not define Jido runtime semantics privately; future metrics or event bridges should consume package telemetry rather than create a second instrumentation path.

Jido.Otel.Tracer terminal callbacks are idempotent (first_terminal_call_wins): if span_stop/2 and span_exception/4 race for the same span context, only the first terminal call applies status/events and ends the span.