# `Jido.Otel.Tracer`
[🔗](https://github.com/agentjido/jido_otel/blob/v1.0.0/lib/jido/otel/tracer.ex#L1)

OpenTelemetry tracer adapter for `Jido.Observe`.

This module implements `Jido.Observe.Tracer` and maps Jido span lifecycle
callbacks to OpenTelemetry spans.

# `current_span_mode`

```elixir
@type current_span_mode() :: :safe | :activate_unsafe
```

Controls whether `span_start/2` mutates process-local current span context.

`:safe` is OTP-safe across async boundaries and does not activate the started span
as the current process span.
`:activate_unsafe` preserves same-process activation/restore behavior.

# `tracer_ctx`

```elixir
@type tracer_ctx() :: Jido.Otel.Tracer.Context.t()
```

Context carried from `span_start/2` to stop/exception callbacks.

# `span_exception`

```elixir
@spec span_exception(Jido.Observe.Tracer.tracer_ctx(), atom(), term(), list()) :: :ok
```

Finalizes a failed span, records an exception event, and marks the span as error.

Terminal callbacks are idempotent: first terminal call wins.

# `span_start`

```elixir
@spec span_start(Jido.Observe.Tracer.event_prefix(), Jido.Observe.Tracer.metadata()) ::
  tracer_ctx()
```

Starts an OpenTelemetry span from a Jido event prefix and metadata map.

The event prefix is converted to a dot-joined span name and metadata is
normalized into OpenTelemetry-compatible span attributes.

See `t:current_span_mode/0` for current-span activation behavior.

# `span_stop`

```elixir
@spec span_stop(Jido.Observe.Tracer.tracer_ctx(), Jido.Observe.Tracer.measurements()) ::
  :ok
```

Finalizes a successful span and attaches measurements as span attributes.

Terminal callbacks are idempotent: first terminal call wins.

# `with_span_scope`

```elixir
@spec with_span_scope(
  Jido.Observe.Tracer.event_prefix(),
  Jido.Observe.Tracer.metadata(),
  (-> result)
) :: result
when result: term()
```

Runs synchronous work inside an active OpenTelemetry span.

This callback is used by `Jido.Observe.with_span/3` when available. Unlike
async `span_start/2`, scoped spans intentionally activate the OTel span only
for the duration of the provided function and restore the previous current
span before returning.

---

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