Tinkex.Telemetry.Otel (Tinkex v0.4.0)

Copy Markdown View Source

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/

Summary

Functions

enabled?(arg1)

Check if OpenTelemetry propagation is enabled.

extract_context(headers, config)

Extract trace context from incoming headers.

inject_headers(headers, config)

Inject trace context headers into an outgoing request.

otel_available?()

Check if OpenTelemetry modules are available.

traceparent_header()

Returns the W3C traceparent header name.

tracestate_header()

Returns the W3C tracestate header name.

Functions

enabled?(arg1)

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

Check if OpenTelemetry propagation is enabled.

extract_context(headers, config)

@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(headers, config)

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

@spec otel_available?() :: boolean()

Check if OpenTelemetry modules are available.

traceparent_header()

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

Returns the W3C traceparent header name.

tracestate_header()

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

Returns the W3C tracestate header name.