Rework baggage page to be less trace-specific

content/en/docs/concepts/signals/baggage.md

@@ -4,46 +4,49 @@ 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.
 
-## Why does OTel Baggage exist?
+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.
 
-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.
+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?
 
-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 +55,35 @@ 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.
+
+## 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