From d7f668615d3538b8174a0f21374d9752be8cb834 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Sat, 15 Jun 2024 10:32:29 -0700 Subject: [PATCH] Rework baggage page to be less trace-specific Should fix https://github.com/open-telemetry/opentelemetry.io/issues/3674 and https://github.com/open-telemetry/opentelemetry.io/issues/1878#issuecomment-2158675491 --- content/en/docs/concepts/signals/baggage.md | 73 +++++++++++---------- 1 file changed, 38 insertions(+), 35 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 1e7c7cc4d84d..299fd065b12c 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -4,46 +4,46 @@ weight: 4 description: Contextual information that is passed between signals. --- -In OpenTelemetry, Baggage is contextual information that’s passed between spans. -It's a key-value store that resides alongside span context in a trace, making -values available to any span created within that trace. +In OpenTelemetry, Baggage is contextual information that resides next to context. +Baggage is a key:value store, which means it lets you propagate any data you +like alongside context. -For example, imagine you want to have a `ClientId` attribute on every span in -your trace, which involves multiple services; however, `ClientId` is only -available in one specific service. To accomplish your goal, you can use -OpenTelemetry Baggage to propagate this value across your system. +Baggage means you can pass data across services and processes, making it available to +add to trace, metrics, or logs in those services. -OpenTelemetry uses -[Context Propagation](/docs/concepts/signals/traces/#context-propagation) to -pass Baggage around, and each of the different library implementations has -propagators that parse and make that Baggage available without you needing to -explicitly implement it. +## Example -![OTel Baggage](/img/otel-baggage.svg) +Baggage is often used in tracing to propagate additional data across services. + +For example, imagine you have a `clientId` at the start of a request, but you'd +like for that ID to be available on all spans in a trace, some metrics in another +service, and some logs along the way. Because the trace may span multiple services, +you need some way to propagate that data without copying the `clientId` across many +places in your codebase. -## Why does OTel Baggage exist? +By using [Context Propagation](/docs/concepts/signals/traces/#context-propagation) to +pass Baggage across these services, the `clientId` is available to add to any additional +spans, metrics, or logs. Additionally, instrumentations automatically propagate baggage +for you. -Baggage provides a uniform way to store and propagate information across a trace -and other signals. For example, you may want to attach information from your -application to a span and retrieve that information much later and use it later -on with another span. However, spans in OpenTelemetry are immutable once -created, and can be exported before you need information on them later on. -Baggage allows you to work around this problem by providing a place to store and -retrieve information. +![OTel Baggage](/img/otel-baggage.svg) ## What should OTel Baggage be used for? -Common use cases include information that’s only accessible further up a stack. -This can include things like Account Identification, User IDs, Product IDs, and -origin IPs, for example. Passing these down your stack allows you to then add -them to your Spans in downstream services to make it easier to filter when -you’re searching in your Observability backend. +Baggage is best used to include information typically available only at the start of a request +further downstream. This can include things like Account Identification, User IDs, +Product IDs, and origin IPs, for example. + +Propagating this information via Baggage allows for deeper analysis of telemetry in a backend. +For example, if you include information like a User ID on a span that tracks a database call, +you can much more easily answer questions like "which users are experiencing the slowest database calls?" +You can also log information about a downstream operation and include that same User ID in the log data. ![OTel Baggage](/img/otel-baggage-2.svg) ## Baggage security considerations -Sensitive Baggage items could be shared with unintended resources, like +Sensitive Baggage items can be shared with unintended resources, like third-party APIs. This is because automatic instrumentation includes Baggage in most of your service’s network requests. Specifically, Baggage and other parts of trace context are sent in HTTP headers, making it visible to anyone @@ -52,23 +52,26 @@ then this risk may not apply, but keep in mind that downstream services could propagate Baggage outside your network. Also, there are no built-in integrity checks to ensure that Baggage items are -yours, so exercise caution when retrieving them. +yours, so exercise caution when reading them. -## Baggage is not the same as Span attributes +## Baggage is not the same as attributes -One important thing to note about Baggage is that it is not a subset of the -[Span Attributes](/docs/concepts/signals/traces/#attributes). When you add -something as Baggage, it does not automatically end up on the Attributes of the -child system’s spans. You must explicitly take something out of Baggage and -append it as Attributes. +An important thing to note about Baggage is that it is a separate key:value +store and is unassociated with attributes on spans, metrics, or logs. -For example, in .NET you might do this: +To add Baggage entries to attributes, you need to explicitly read that data +and add it. For example, in .NET you might do this: ```csharp var accountId = Baggage.GetBaggage("AccountId"); Activity.Current?.SetTag("AccountId", accountId); ``` +Because one of the most common use cases for Baggage +is to add data to [Span Attributes](/docs/concepts/signals/traces/#attributes) +across a whole trace, several languages have Baggage Span Processors that +automatically read Baggage values and add them as attributes for you. + > For more information, see the [baggage specification][]. [baggage specification]: /docs/specs/otel/overview/#baggage-signal