# `Tinkex.Telemetry.Otel`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/telemetry/otel.ex#L1)

OpenTelemetry trace context propagation for Tinkex.

This module provides opt-in support for propagating W3C Trace Context
headers (traceparent, tracestate) through HTTP requests. When enabled,
Tinkex requests will carry trace context from the caller, enabling
distributed tracing across services.

## Configuration

Enable OpenTelemetry propagation via config:

    config = Tinkex.Config.new(
      api_key: "tml-...",
      otel_propagate: true
    )

Or via environment variable:

    export TINKEX_OTEL_PROPAGATE=true

## Requirements

This feature requires the `opentelemetry` and `opentelemetry_api` packages
to be installed. If they are not available, the propagation functions
become no-ops.

Add to your mix.exs (optional):

    {:opentelemetry_api, "~> 1.0"},
    {:opentelemetry, "~> 1.0"}

## W3C Trace Context

The module follows the W3C Trace Context specification:
- `traceparent`: Contains trace-id, parent-id, and trace-flags
- `tracestate`: Vendor-specific trace data

See: https://www.w3.org/TR/trace-context/

# `enabled?`

```elixir
@spec enabled?(map() | struct()) :: boolean()
```

Check if OpenTelemetry propagation is enabled.

# `extract_context`

```elixir
@spec extract_context([{String.t(), String.t()}], map() | struct()) :: :ok
```

Extract trace context from incoming headers.

Sets the current trace context from the provided headers.
This is useful when processing responses that may contain
updated trace context.

Returns :ok. No-op if propagation is disabled or OpenTelemetry is unavailable.

# `inject_headers`

```elixir
@spec inject_headers([{String.t(), String.t()}], map() | struct()) :: [
  {String.t(), String.t()}
]
```

Inject trace context headers into an outgoing request.

If OpenTelemetry is available and propagation is enabled,
this will add traceparent and optionally tracestate headers
to the request headers list.

Returns the headers unchanged if:
- Propagation is disabled
- OpenTelemetry is not loaded
- No active trace context exists

# `otel_available?`

```elixir
@spec otel_available?() :: boolean()
```

Check if OpenTelemetry modules are available.

# `traceparent_header`

```elixir
@spec traceparent_header() :: String.t()
```

Returns the W3C traceparent header name.

# `tracestate_header`

```elixir
@spec tracestate_header() :: String.t()
```

Returns the W3C tracestate header name.

---

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