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

OpenTelemetry.Baggage

Contents

Constructing Baggage structures
Limits (W3C Baggage specification)
Modifying Baggage
Querying Baggage
Encoding and decoding Baggage

Description

Overview

Baggage is a set of key-value pairs that propagate alongside trace context across service boundaries (typically via the baggage HTTP header). Use it to pass metadata like tenant IDs, feature flags, or routing hints through your distributed system.

Baggage is not for span-specific annotations. Use addAttribute for that.

Quick example

import OpenTelemetry.Baggage

-- Create baggage:
let bag = insert [token|tenant-id|] (element "abc123")
        $ insert [token|region|] (element "us-east-1")
        $ empty

-- Encode for HTTP propagation:
let headerValue = encodeBaggageHeader bag
-- "tenant-id=abc123,region=us-east-1"

-- Decode from an incoming header:
case decodeBaggageHeader headerBytes of
  Right bag -> -- use the baggage
  Left err  -> -- malformed header

Thread-local baggage

Use the functions in OpenTelemetry.Context.ThreadLocal to get/set baggage on the current thread:

import OpenTelemetry.Context.ThreadLocal (getContext, adjustContext)
import OpenTelemetry.Context (insertBaggage, lookupBaggage)

-- Read:
mbag <- lookupBaggage <$> getContext
-- Write:
adjustContext (insertBaggage myBaggage)

Limits

W3C Baggage specification enforces:

Max 8192 bytes total serialized size
Max 4096 bytes per member
Max 180 members

insertChecked validates these limits and returns Left InvalidBaggage on violation.

Spec reference

https://opentelemetry.io/docs/specs/otel/baggage/api/

Synopsis

data Baggage
empty :: Baggage
fromHashMap :: HashMap Token Element -> Baggage
values :: Baggage -> HashMap Token Element
data Token
token :: QuasiQuoter
mkToken :: Text -> Maybe Token
tokenValue :: Token -> ByteString
data Element = Element {
- value :: Text
- properties :: [Property]
}
element :: Text -> Element
property :: Token -> Maybe Text -> Property
data InvalidBaggage
- = BaggageTooLong
- | MemberTooLong
- | TooManyListMembers
- | Empty
maxBaggageBytes :: Int
maxMemberBytes :: Int
maxMembers :: Int
insert :: Token -> Element -> Baggage -> Baggage
insertChecked :: Token -> Element -> Baggage -> Either InvalidBaggage Baggage
delete :: Token -> Baggage -> Baggage
getValue :: Token -> Baggage -> Maybe Text
encodeBaggageHeader :: Baggage -> ByteString
encodeBaggageHeaderB :: Baggage -> Builder
decodeBaggageHeader :: ByteString -> Either String Baggage

Constructing `Baggage` structures

data Baggage Source #

Baggage is used to annotate telemetry, adding context and information to metrics, traces, and logs. It is a set of name/value pairs describing user-defined properties. Each name in Baggage is associated with exactly one value.

Since: 0.0.1.0

Instances

Instances details

Semigroup Baggage Source #
Instance details Defined in OpenTelemetry.Baggage Methods (<>) :: Baggage -> Baggage -> Baggage # sconcat :: NonEmpty Baggage -> Baggage # stimes :: Integral b => b -> Baggage -> Baggage #
Show Baggage Source #
Instance details Defined in OpenTelemetry.Baggage Methods showsPrec :: Int -> Baggage -> ShowS # show :: Baggage -> String # showList :: [Baggage] -> ShowS #
Eq Baggage Source #
Instance details Defined in OpenTelemetry.Baggage Methods (==) :: Baggage -> Baggage -> Bool # (/=) :: Baggage -> Baggage -> Bool #

empty :: Baggage Source #

An empty initial baggage value

Since: 0.0.1.0

fromHashMap :: HashMap Token Element -> Baggage Source #

Convert a HashMap into Baggage

Since: 0.0.1.0

values :: Baggage -> HashMap Token Element Source #

Returns the namevalue pairs in the Baggage. The order of namevalue pairs is not significant.

Since: 0.0.1.0

data Token Source #

A key for a baggage entry, restricted to the set of valid characters specified in the token definition of RFC 2616:

https://www.rfc-editor.org/rfc/rfc2616#section-2.2

Since: 0.0.1.0

Instances

Instances details

Show Token Source #
Instance details Defined in OpenTelemetry.Baggage Methods showsPrec :: Int -> Token -> ShowS # show :: Token -> String # showList :: [Token] -> ShowS #
Eq Token Source #
Instance details Defined in OpenTelemetry.Baggage Methods (==) :: Token -> Token -> Bool # (/=) :: Token -> Token -> Bool #
Ord Token Source #
Instance details Defined in OpenTelemetry.Baggage Methods compare :: Token -> Token -> Ordering # (<) :: Token -> Token -> Bool # (<=) :: Token -> Token -> Bool # (>) :: Token -> Token -> Bool # (>=) :: Token -> Token -> Bool # max :: Token -> Token -> Token # min :: Token -> Token -> Token #
Hashable Token Source #
Instance details Defined in OpenTelemetry.Baggage Methods hashWithSalt :: Int -> Token -> Int # hash :: Token -> Int #
Lift Token Source #
Instance details Defined in OpenTelemetry.Baggage Methods lift :: Quote m => Token -> m Exp # liftTyped :: forall (m :: Type -> Type). Quote m => Token -> Code m Token #

token :: QuasiQuoter Source #

Since: 0.0.1.0

mkToken :: Text -> Maybe Token Source #

Since: 0.0.1.0

tokenValue :: Token -> ByteString Source #

Convert a Token into a ByteString

Since: 0.0.1.0

data Element Source #

An entry into the baggage

Since: 0.0.1.0

Constructors

Element
Fields value :: Text properties :: [Property]

Instances

Instances details

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

element :: Text -> Element Source #

Since: 0.0.1.0

property :: Token -> Maybe Text -> Property Source #

Since: 0.0.1.0

data InvalidBaggage Source #

Since: 0.0.1.0

Constructors

BaggageTooLong
MemberTooLong
TooManyListMembers
Empty

Instances

Instances details

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