Copyright	(c) Ian Duncan 2021-2026
License	BSD-3
Stability	experimental
Safe Haskell	None
Language	Haskell2010

OpenTelemetry.Propagator

Contents

Propagator
TextMap carrier
TextMapPropagator
Global TextMapPropagator

Description

Overview

Propagators serialize and deserialize Context (trace state and baggage) into carrier formats like HTTP headers. This is how distributed tracing works across service boundaries.

Built-in propagators

The SDK registers these propagators automatically:

W3C TraceContext (traceparent header) -- default
W3C Baggage (baggage header) -- default
B3 (Zipkin single and multi-header)
Jaeger (uber-trace-id header)
Datadog (x-datadog-trace-id headers)
AWS X-Ray (X-Amzn-Trace-Id header)

Configure via OTEL_PROPAGATORS:

export OTEL_PROPAGATORS=tracecontext,baggage,b3

Usage in instrumentation

If you are writing instrumentation for a transport (HTTP, gRPC, messaging), use the global propagator to inject/extract context:

import OpenTelemetry.Propagator
import OpenTelemetry.Context.ThreadLocal

-- Injecting (outbound request):
propagator <- getGlobalTextMapPropagator
ctx <- getContext
headers <- inject propagator ctx request

-- Extracting (inbound request):
propagator <- getGlobalTextMapPropagator
ctx <- extract propagator request =<< getContext
tok <- attachContext ctx
-- ... later, restore previous context:
detachContext tok

Custom propagators

Implement the Propagator record with propagatorFields, extractor, and injector fields. Propagators are composable via their Monoid instance (extracts and injects run in sequence).

Spec reference

https://opentelemetry.io/docs/specs/otel/context/api-propagators/

Synopsis

data Propagator context inboundCarrier outboundCarrier = Propagator {
- propagatorFields :: [Text]
- extractor :: inboundCarrier -> context -> IO context
- injector :: context -> outboundCarrier -> IO outboundCarrier
}
propagatorNames :: Propagator context i o -> [Text]
extract :: MonadIO m => Propagator context i o -> i -> context -> m context
inject :: MonadIO m => Propagator context i o -> context -> o -> m o
data TextMap
emptyTextMap :: TextMap
textMapInsert :: Text -> Text -> TextMap -> TextMap
textMapLookup :: Text -> TextMap -> Maybe Text
textMapDelete :: Text -> TextMap -> TextMap
textMapKeys :: TextMap -> [Text]
textMapToList :: TextMap -> [(Text, Text)]
textMapFromList :: [(Text, Text)] -> TextMap
type TextMapPropagator = Propagator Context TextMap TextMap
getGlobalTextMapPropagator :: IO TextMapPropagator
setGlobalTextMapPropagator :: TextMapPropagator -> IO ()

Propagator

data Propagator context inboundCarrier outboundCarrier Source #

A carrier is the medium used by Propagators to read values from and write values to. Each specific Propagator type defines its expected carrier type, such as a string map or a byte array.

Since: 0.0.1.0

Constructors

Propagator
Fields propagatorFields :: [Text] The predefined propagation fields. For a TextMapPropagator these are the header names the propagator reads and writes (e.g. `["traceparent", "tracestate"]`). If your carrier is reused, you should delete these fields before calling `inject`. extractor :: inboundCarrier -> context -> IO context injector :: context -> outboundCarrier -> IO outboundCarrier

Instances

Instances details

Monoid (Propagator c i o) Source #
Instance details Defined in OpenTelemetry.Propagator Methods mempty :: Propagator c i o # mappend :: Propagator c i o -> Propagator c i o -> Propagator c i o # mconcat :: [Propagator c i o] -> Propagator c i o #
Semigroup (Propagator c i o) Source #
Instance details Defined in OpenTelemetry.Propagator Methods (<>) :: Propagator c i o -> Propagator c i o -> Propagator c i o # sconcat :: NonEmpty (Propagator c i o) -> Propagator c i o # stimes :: Integral b => b -> Propagator c i o -> Propagator c i o #

propagatorNames :: Propagator context i o -> [Text] Source #

Deprecated: Use propagatorFields instead. propagatorNames will be removed in a future release.

Deprecated alias for propagatorFields.

Since: 0.0.1.0

extract Source #

Arguments

:: MonadIO m
=> Propagator context i o
-> i	The carrier that holds the propagation fields. For example, an incoming message or HTTP request.
-> context
-> m context	a new Context derived from the Context passed as argument, containing the extracted value, which can be a SpanContext, Baggage or another cross-cutting concern context.

Extracts the value from an incoming request. For example, from the headers of an HTTP request.

If a value can not be parsed from the carrier, for a cross-cutting concern, the implementation MUST NOT throw an exception and MUST NOT store a new value in the Context, in order to preserve any previously existing valid value.

Since: 0.0.1.0

inject Source #

Arguments

:: MonadIO m
=> Propagator context i o
-> context
-> o	The carrier that holds the propagation fields. For example, an outgoing message or HTTP request.
-> m o

Injects the value into a carrier. For example, into the headers of an HTTP request.

Since: 0.0.1.0

TextMap carrier

data TextMap Source #

A case-insensitive text map used as the carrier for context propagation. Keys are compared case-insensitively but their original casing is preserved, matching the behavior required by HTTP header semantics.

Instrumentation code converts between transport-specific representations (e.g. HTTP headers) and TextMap at the boundary.

Since: 0.4.0.0

Instances

Instances details

Show TextMap Source #
Instance details Defined in OpenTelemetry.Propagator Methods showsPrec :: Int -> TextMap -> ShowS # show :: TextMap -> String # showList :: [TextMap] -> ShowS #
Eq TextMap Source #
Instance details Defined in OpenTelemetry.Propagator Methods (==) :: TextMap -> TextMap -> Bool # (/=) :: TextMap -> TextMap -> Bool #

emptyTextMap :: TextMap Source #

Since: 0.4.0.0

textMapInsert :: Text -> Text -> TextMap -> TextMap Source #

Since: 0.4.0.0

textMapLookup :: Text -> TextMap -> Maybe Text Source #

Since: 0.4.0.0

textMapDelete :: Text -> TextMap -> TextMap Source #

Since: 0.4.0.0

textMapKeys :: TextMap -> [Text] Source #

Since: 0.4.0.0

textMapToList :: TextMap -> [(Text, Text)] Source #

Since: 0.4.0.0

textMapFromList :: [(Text, Text)] -> TextMap Source #

Since: 0.4.0.0

TextMapPropagator

type TextMapPropagator = Propagator Context TextMap TextMap Source #

A TextMapPropagator is a Propagator specialized for text-based carriers. This is the only propagator type defined by the OpenTelemetry specification.

Instrumentation libraries convert between transport-specific formats (e.g. HTTP headers, gRPC metadata, environment variables) and TextMap at the boundary, then pass the TextMap to the propagator.

Since: 0.4.0.0

Global TextMapPropagator

getGlobalTextMapPropagator :: IO TextMapPropagator Source #

Get the globally configured TextMapPropagator.

Returns a no-op propagator until the SDK sets one via setGlobalTextMapPropagator (typically driven by OTEL_PROPAGATORS).

Since: 0.4.0.0

setGlobalTextMapPropagator :: TextMapPropagator -> IO () Source #

Set the global TextMapPropagator.

Called by the SDK during initialization. Instrumentation libraries should use getGlobalTextMapPropagator rather than accessing the TracerProvider propagator directly.

Since: 0.4.0.0