Baggage

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.
在 OpenTelemetry 中，Baggage 是在Span之间传递的上下文信息。它是一个键值对存储结构，与Trace中的Span Context并存，可供该Trace中创建的任何Span使用。

For example, imagine you want to have a CustomerId attribute on every span in your trace, which involves multiple services; however, CustomerId is only available in one specific service. To accomplish your goal, you can use OpenTelemetry Baggage to propagate this value across your system.
例如，假设您希望涉及多个服务的Trace中的每个Span都有一个CustomerId属性，而CustomerId仅在一项特定服务中可用。为了实现您的目标，您可以使用OpenTelemetry Baggage在整个系统中传播此值。

OpenTelemetry uses 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.
OpenTelemetry使用Context Propagation来传递 Baggage，每个不同的库实现都有传播器（propagators）来解析并使 Baggage 可用，而无需您显式实现它。

Why does OTel Baggage exist?

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.
Baggage提供了一种统一的存储和传播的信息的方案。这些信号可以跨越Trace以及其他信号。例如，您可能希望将应用程序中的信息附加到一个Span，并在稍后检索该信息，然后在另一个Span中使用它。但是，OpenTelemetry中的Span一旦创建就不可变，并且可以在您稍后需要有关它们的信息之前导出。 Baggage提供存储和检索信息的位置来帮助您解决此问题。

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.
常见用例包括：只能在堆栈的更上层访问的信息。例如，这可以包括帐户标识、用户 ID、产品 ID 和源 IP 等内容。将这些传递到堆栈中后，您可以将它们添加到下游服务中的 Spans 中，以便在可观测性后端搜索时更轻松地进行过滤。

Baggage security considerations

Sensitive Baggage items could 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 inspecting your network traffic. If traffic is restricted within your network, then this risk may not apply, but keep in mind that downstream services could propagate Baggage outside your network.
便捷的Baggage可能会与第三方API等非预期资源共享信息。这是因为在大多数服务的网络请求的自动测量装置中都包含 Baggage。具体来说，Baggage 和Trace Context的其他部分在 HTTP 标头中发送，使其对检查您的网络流量的任何人都可见。如果您的网络内的流量受到限制，则此风险可能不适用，但请记住，下游服务可能会将Baggage传播到您的网络之外。

Also, there are no built-in integrity checks to ensure that Baggage items are yours, so exercise caution when retrieving them.
此外，没有内置的完整性检查来确保Baggage中项目属于您，因此从中取值时请务必小心。

Baggage is not the same as Span attributes

One important thing to note about Baggage is that it is not a subset of the Span 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.
关于 Baggage 需要注意的一件重要事情是它不是 Span Attributes的子集。当您将某些内容添加到Baggage中时，它不会自动出现在子系统Span的属性上。您必须明确地从 Baggage 中取出某些内容并将其附加为 Span Attributes。

For example, in .NET you might do this:
例如，在 .NET 中您可以这样做：

var accountId = Baggage.GetBaggage("AccountId");
Activity.Current?.SetTag("AccountId", accountId);

For more information, see the baggage specification.

如需了解更多信息，请参阅baggage specification.。