From d7f668615d3538b8174a0f21374d9752be8cb834 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Sat, 15 Jun 2024 10:32:29 -0700 Subject: [PATCH 01/10] 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 From a138eeb476de75560a27a9faeaba09c922b35f1b Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Sat, 15 Jun 2024 17:38:23 +0000 Subject: [PATCH 02/10] Results from /fix:format --- content/en/docs/concepts/signals/baggage.md | 55 +++++++++++---------- 1 file changed, 29 insertions(+), 26 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 299fd065b12c..13b04882f89c 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -4,40 +4,43 @@ weight: 4 description: Contextual information that is passed between signals. --- -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. +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. -Baggage means you can pass data across services and processes, making it available to -add to trace, metrics, or logs in those services. +Baggage means you can pass data across services and processes, making it +available to add to trace, metrics, or logs in those services. ## Example 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. +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. -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. +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. ![OTel Baggage](/img/otel-baggage.svg) ## What should OTel Baggage be used for? -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. +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. +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) @@ -59,18 +62,18 @@ yours, so exercise caution when reading them. 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. -To add Baggage entries to attributes, you need to explicitly read that data -and add it. 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. +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][]. From 0aa0f7390ff763a0285b9b39b2924af3f194200f Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Sat, 15 Jun 2024 15:28:43 -0700 Subject: [PATCH 03/10] Update baggage.md --- content/en/docs/concepts/signals/baggage.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 13b04882f89c..e63c29916ce6 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -75,6 +75,15 @@ Because one of the most common use cases for Baggage is to add data to trace, several languages have Baggage Span Processors that automatically read Baggage values and add them as attributes for you. +## Baggage is only for observability data + +Although Baggage does support propagating arbitrary key:value pairs across +services, it is not a replacement for programmatic data flow. Because Baggage +is stored in HTTP headers, not only does this mean the data is available for +anyone who can read those headers to consume, but it would be a poor choice +to propagate general program data given the practical limits HTTP servers +place on header lengths. + > For more information, see the [baggage specification][]. [baggage specification]: /docs/specs/otel/overview/#baggage-signal From 407c7b252bb075cc84d0fa2d95334f295f472e71 Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Sat, 15 Jun 2024 22:32:38 +0000 Subject: [PATCH 04/10] Results from /fix:format --- content/en/docs/concepts/signals/baggage.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index e63c29916ce6..7ccfe8fefe76 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -78,11 +78,11 @@ Baggage values and add them as attributes for you. ## Baggage is only for observability data Although Baggage does support propagating arbitrary key:value pairs across -services, it is not a replacement for programmatic data flow. Because Baggage -is stored in HTTP headers, not only does this mean the data is available for -anyone who can read those headers to consume, but it would be a poor choice -to propagate general program data given the practical limits HTTP servers -place on header lengths. +services, it is not a replacement for programmatic data flow. Because Baggage is +stored in HTTP headers, not only does this mean the data is available for anyone +who can read those headers to consume, but it would be a poor choice to +propagate general program data given the practical limits HTTP servers place on +header lengths. > For more information, see the [baggage specification][]. From 08dc4510741cc3f81ba39459bfb3ef94fc9b92bc Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 17 Jun 2024 06:53:14 -0700 Subject: [PATCH 05/10] Apply suggestions from code review Co-authored-by: Severin Neumann Co-authored-by: Fabrizio Ferri-Benedetti --- content/en/docs/concepts/signals/baggage.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 7ccfe8fefe76..ba6cb2f7b17a 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -5,11 +5,11 @@ description: Contextual information that is passed between signals. --- 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. +context. Baggage is a key-value store, which means it lets you [propagate](/docs/concepts/context-propagation/#propagation) any +data you like alongside [context](/docs/concepts/context-propagation/#context). Baggage means you can pass data across services and processes, making it -available to add to trace, metrics, or logs in those services. +available to add to [trace](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/), or [logs](/docs/concepts/signals/logs/) in those services. ## Example @@ -23,7 +23,7 @@ multiple services, you need some way to propagate that data without copying the By using [Context Propagation](/docs/concepts/signals/traces/#context-propagation) to -pass Baggage across these services, the `clientId` is available to add to any +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. @@ -35,7 +35,7 @@ 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 +Propagating this information using 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 @@ -59,7 +59,7 @@ yours, so exercise caution when reading them. ## Baggage is not the same as attributes -An important thing to note about Baggage is that it is a separate key:value +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. To add Baggage entries to attributes, you need to explicitly read that data and @@ -77,8 +77,8 @@ Baggage values and add them as attributes for you. ## Baggage is only for observability data -Although Baggage does support propagating arbitrary key:value pairs across -services, it is not a replacement for programmatic data flow. Because Baggage is +Although Baggage does support propagating arbitrary key-value pairs across +services, it is not a replacement for programmatic data flow. Because baggage is stored in HTTP headers, not only does this mean the data is available for anyone who can read those headers to consume, but it would be a poor choice to propagate general program data given the practical limits HTTP servers place on From 9c2c6c3f56371d528bbf50db3ef91063d35f48f3 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 17 Jun 2024 07:23:14 -0700 Subject: [PATCH 06/10] Update baggage.md --- content/en/docs/concepts/signals/baggage.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index ba6cb2f7b17a..9fedcf3f33e7 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -82,7 +82,9 @@ services, it is not a replacement for programmatic data flow. Because baggage is stored in HTTP headers, not only does this mean the data is available for anyone who can read those headers to consume, but it would be a poor choice to propagate general program data given the practical limits HTTP servers place on -header lengths. +header lengths. Furthermore, clients reserve the right to drop HTTP headers, +which would result in unexpected data loss. To reiterate: don't use baggage +as a replacement for programmatic data flow. > For more information, see the [baggage specification][]. From 06623a0de7cd72ebbd58193259949059b74f4dab Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Mon, 17 Jun 2024 11:49:53 -0700 Subject: [PATCH 07/10] Apply suggestions from code review Co-authored-by: Cijo Thomas --- content/en/docs/concepts/signals/baggage.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 9fedcf3f33e7..de66aff55220 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -9,7 +9,7 @@ context. Baggage is a key-value store, which means it lets you [propagate](/docs data you like alongside [context](/docs/concepts/context-propagation/#context). Baggage means you can pass data across services and processes, making it -available to add to [trace](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/), or [logs](/docs/concepts/signals/logs/) in those services. +available to add to [traces](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/), or [logs](/docs/concepts/signals/logs/) in those services. ## Example @@ -60,7 +60,7 @@ yours, so exercise caution when reading them. ## Baggage is not the same 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. +store and is unassociated with attributes on spans, metrics, or logs without explicitly adding them. To add Baggage entries to attributes, you need to explicitly read that data and add it. For example, in .NET you might do this: From 35d3d9ca4a33216024ddaf18b6483dbc3980a6d1 Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 18 Jun 2024 06:13:17 -0700 Subject: [PATCH 08/10] updates as per review --- content/en/docs/concepts/signals/baggage.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index de66aff55220..24f3f6771eda 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -62,18 +62,13 @@ yours, so exercise caution when reading them. 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 without explicitly adding them. -To add Baggage entries to attributes, you need to explicitly read that data and -add it. For example, in .NET you might do this: +To add baggage entries to attributes, you need to explicitly read the data +from baggage and add it as attributes to your spans, metrics, or logs. -```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 +Because a 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. +trace, several languages have Baggage Span Processors that add data from +baggage as attributes on span creation. ## Baggage is only for observability data From 105c0c836779a042dc56dd5955951659754b6b8f Mon Sep 17 00:00:00 2001 From: Phillip Carter Date: Tue, 25 Jun 2024 09:28:32 -0700 Subject: [PATCH 09/10] Update baggage.md --- content/en/docs/concepts/signals/baggage.md | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 24f3f6771eda..60121f443d11 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -70,17 +70,6 @@ Because a common use cases for Baggage is to add data to trace, several languages have Baggage Span Processors that add data from baggage as attributes on span creation. -## Baggage is only for observability data - -Although Baggage does support propagating arbitrary key-value pairs across -services, it is not a replacement for programmatic data flow. Because baggage is -stored in HTTP headers, not only does this mean the data is available for anyone -who can read those headers to consume, but it would be a poor choice to -propagate general program data given the practical limits HTTP servers place on -header lengths. Furthermore, clients reserve the right to drop HTTP headers, -which would result in unexpected data loss. To reiterate: don't use baggage -as a replacement for programmatic data flow. - > For more information, see the [baggage specification][]. [baggage specification]: /docs/specs/otel/overview/#baggage-signal From 79f4bc496cb71d02b24023ef6d91b8ef4f5ca664 Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Wed, 26 Jun 2024 16:01:31 +0000 Subject: [PATCH 10/10] Results from /fix:format --- content/en/docs/concepts/signals/baggage.md | 28 ++++++++++++--------- 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/content/en/docs/concepts/signals/baggage.md b/content/en/docs/concepts/signals/baggage.md index 60121f443d11..7cf6d1379fce 100644 --- a/content/en/docs/concepts/signals/baggage.md +++ b/content/en/docs/concepts/signals/baggage.md @@ -5,11 +5,14 @@ description: Contextual information that is passed between signals. --- In OpenTelemetry, Baggage is contextual information that resides next to -context. Baggage is a key-value store, which means it lets you [propagate](/docs/concepts/context-propagation/#propagation) any -data you like alongside [context](/docs/concepts/context-propagation/#context). +context. Baggage is a key-value store, which means it lets you +[propagate](/docs/concepts/context-propagation/#propagation) any data you like +alongside [context](/docs/concepts/context-propagation/#context). Baggage means you can pass data across services and processes, making it -available to add to [traces](/docs/concepts/signals/traces/), [metrics](/docs/concepts/signals/metrics/), or [logs](/docs/concepts/signals/logs/) in those services. +available to add to [traces](/docs/concepts/signals/traces/), +[metrics](/docs/concepts/signals/metrics/), or +[logs](/docs/concepts/signals/logs/) in those services. ## Example @@ -35,10 +38,10 @@ 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 using 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 +Propagating this information using 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. @@ -60,15 +63,16 @@ yours, so exercise caution when reading them. ## Baggage is not the same 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 without explicitly adding them. +store and is unassociated with attributes on spans, metrics, or logs without +explicitly adding them. -To add baggage entries to attributes, you need to explicitly read the data -from baggage and add it as attributes to your spans, metrics, or logs. +To add baggage entries to attributes, you need to explicitly read the data from +baggage and add it as attributes to your spans, metrics, or logs. Because a 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 add data from -baggage as attributes on span creation. +trace, several languages have Baggage Span Processors that add data from baggage +as attributes on span creation. > For more information, see the [baggage specification][].