From c65621e324405ecb5132e11d1f9f605002303de8 Mon Sep 17 00:00:00 2001 From: Cassandra Coyle Date: Mon, 14 Apr 2025 09:10:50 -0500 Subject: [PATCH 1/2] copy contents from other PR Signed-off-by: Cassandra Coyle --- .../observability/tracing/tracing-overview.md | 37 +++++++++++++++++++ .../tracing/w3c-tracing-overview.md | 24 ++++++++++++ 2 files changed, 61 insertions(+) diff --git a/daprdocs/content/en/operations/observability/tracing/tracing-overview.md b/daprdocs/content/en/operations/observability/tracing/tracing-overview.md index a5194a73086..23eff28c4fc 100644 --- a/daprdocs/content/en/operations/observability/tracing/tracing-overview.md +++ b/daprdocs/content/en/operations/observability/tracing/tracing-overview.md @@ -110,6 +110,43 @@ If you decide to generate trace headers yourself, there are three ways this can Read [the trace context overview]({{< ref w3c-tracing-overview >}}) for more background and examples on W3C trace context and headers. +### Baggage Support + +Dapr supports propagating W3C Baggage alongside trace context. For details on the W3C Baggage specification, format, and how it works, see the [W3C Trace Context Overview]({{< ref "w3c-tracing-overview.md#w3c-baggage" >}}). + +#### Using Baggage with Dapr + +You can add baggage from your application by setting the appropriate HTTP header or gRPC metadata when calling Dapr. Dapr automatically propagates this baggage across subsequent service calls. + +**Setting Baggage** + +Set the `baggage` header (HTTP) or metadata (gRPC) in your requests to Dapr: +- For HTTP: Add the `baggage` header to your request. +- For gRPC: Add `baggage` key-value pairs to the outgoing context metadata. + +*HTTP Example:* +```http +POST /v1.0/invoke/serviceB/method/hello HTTP/1.1 +Content-Type: application/json +baggage: key1=value1,key2=value2 +{ + "message": "Hello service B" +} +``` + +*gRPC Example (Go):* +```go +ctx = grpcMetadata.AppendToOutgoingContext(ctx, + "baggage", "key1=value1,key2=value2", + ) +``` + +#### Common Use Cases + +Baggage is useful for: +- Propagating user IDs or correlation IDs across services +- Passing tenant or environment information + ## Related Links - [Observability concepts]({{< ref observability-concept.md >}}) diff --git a/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md b/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md index 52eccbef4d5..4f08b81c562 100644 --- a/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md +++ b/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md @@ -73,6 +73,18 @@ tracestate: congo=t61rcWkgMzE [Learn more about the tracestate fields details](https://www.w3.org/TR/trace-context/#tracestate-header). +**Baggage header** + +Dapr supports [W3C Baggage](https://www.w3.org/TR/baggage/) for propagating key-value pairs alongside trace context. The baggage header allows you to attach metadata to trace context that needs to be propagated throughout your distributed system, such as user IDs, tenant information, or environment details. + +The header value follows the W3C Baggage specification format: + +``` +baggage: userId=alice,serverNode=DF%2028,isVIP=true +``` + +Multiple baggage headers are supported and will be combined according to the W3C specification. Dapr automatically propagates baggage headers across service calls. + {{% /codetab %}} @@ -81,6 +93,18 @@ tracestate: congo=t61rcWkgMzE In the gRPC API calls, trace context is passed through `grpc-trace-bin` header. +**Baggage metadata** + +Dapr supports [W3C Baggage](https://www.w3.org/TR/baggage/) for propagating key-value pairs alongside trace context. The baggage metadata allows you to attach metadata to trace context that needs to be propagated throughout your distributed system, such as user IDs, tenant information, or environment details. + +The metadata value follows the W3C Baggage specification format: + +``` +baggage: userId=alice,serverNode=DF%2028,isVIP=true +``` + +Multiple baggage metadata entries are supported and will be combined according to the W3C specification. Dapr automatically propagates baggage metadata across service calls. + {{% /codetab %}} {{< /tabs >}} From 3cb21b7d44c27b2da148d9704f1cb137221d28f4 Mon Sep 17 00:00:00 2001 From: Cassandra Coyle Date: Sun, 20 Apr 2025 22:25:35 -0500 Subject: [PATCH 2/2] update docs Signed-off-by: Cassandra Coyle --- .../observability/tracing/tracing-overview.md | 118 +++++++++++++++--- .../tracing/w3c-tracing-overview.md | 67 +++++++--- 2 files changed, 151 insertions(+), 34 deletions(-) diff --git a/daprdocs/content/en/operations/observability/tracing/tracing-overview.md b/daprdocs/content/en/operations/observability/tracing/tracing-overview.md index 23eff28c4fc..46b503dff87 100644 --- a/daprdocs/content/en/operations/observability/tracing/tracing-overview.md +++ b/daprdocs/content/en/operations/observability/tracing/tracing-overview.md @@ -112,33 +112,106 @@ If you decide to generate trace headers yourself, there are three ways this can ### Baggage Support -Dapr supports propagating W3C Baggage alongside trace context. For details on the W3C Baggage specification, format, and how it works, see the [W3C Trace Context Overview]({{< ref "w3c-tracing-overview.md#w3c-baggage" >}}). +Dapr supports two distinct mechanisms for propagating W3C Baggage alongside trace context: + +1. **Context Baggage (OpenTelemetry)** + - Follows OpenTelemetry conventions with decoded values + - Used when working with OpenTelemetry context propagation + - Values are stored and transmitted in their original, unencoded form + - Recommended for OpenTelemetry integrations and when working with application context + +2. **Header/Metadata Baggage** + - You must URL encode special characters (for example, `%20` for spaces, `%2F` for slashes) when setting header/metadata baggage + - Values remain percent-encoded in transport as required by the W3C Baggage spec + - Values stay encoded when inspecting raw headers/metadata + - Only OpenTelemetry APIs will decode the values + - Example: Use `serverNode=DF%2028` (not `serverNode=DF 28`) when setting header baggage + +For security purposes, context baggage and header baggage are strictly separated and never merged between domains. This ensures that baggage values maintain their intended format and security properties. #### Using Baggage with Dapr -You can add baggage from your application by setting the appropriate HTTP header or gRPC metadata when calling Dapr. Dapr automatically propagates this baggage across subsequent service calls. +You can propagate baggage using either mechanism, depending on your use case. + +1. **In your application code**: Set the baggage in the context before making a Dapr API call +2. **When calling Dapr**: Pass the context to any Dapr API call +3. **Inside Dapr**: The Dapr runtime automatically picks up the baggage +4. **Propagation**: Dapr automatically propagates the baggage to downstream services, maintaining the appropriate encoding for each mechanism + +Here are examples of both mechanisms: + +**1. Using Context Baggage (OpenTelemetry)** + +When using OpenTelemetry SDK: +```go +import otelbaggage "go.opentelemetry.io/otel/baggage" + +// Set baggage in context (values remain unencoded) +baggage, err = otelbaggage.Parse("userId=cassie,serverNode=DF%2028") +... +ctx := otelbaggage.ContextWithBaggage(t.Context(), baggage) +) -**Setting Baggage** +// Pass this context to any Dapr API call +client.InvokeMethodWithContent(ctx, "serviceB", ...) +``` -Set the `baggage` header (HTTP) or metadata (gRPC) in your requests to Dapr: -- For HTTP: Add the `baggage` header to your request. -- For gRPC: Add `baggage` key-value pairs to the outgoing context metadata. +**2. Using Header/Metadata Baggage** -*HTTP Example:* -```http -POST /v1.0/invoke/serviceB/method/hello HTTP/1.1 -Content-Type: application/json -baggage: key1=value1,key2=value2 -{ - "message": "Hello service B" +When using gRPC metadata: +```go +import "google.golang.org/grpc/metadata" + +// Set URL-encoded baggage in context +ctx = metadata.AppendToOutgoingContext(ctx, + "baggage", "userId=cassie,serverNode=DF%2028", +) + +// Pass this context to any Dapr API call +client.InvokeMethodWithContent(ctx, "serviceB", ...) +``` + +**3. Receiving Baggage in Target Service** + +In your target service, you can access the propagated baggage: + +```go +// Using OpenTelemetry (values are automatically decoded) +import "go.opentelemetry.io/otel/baggage" + +bag := baggage.FromContext(ctx) +userID := bag.Member("userId").Value() // "cassie" +``` + +```go +// Using raw gRPC metadata (values remain percent-encoded) +import "google.golang.org/grpc/metadata" + +md, _ := metadata.FromIncomingContext(ctx) +if values := md.Get("baggage"); len(values) > 0 { + // values[0] contains the percent-encoded string you set: "userId=cassie,serverNode=DF%2028" + // Remember: You must URL encode special characters when setting baggage + + // To decode the values, use OpenTelemetry APIs: + bag, err := baggage.Parse(values[0]) + ... + userID := bag.Member("userId").Value() // "cassie" } ``` -*gRPC Example (Go):* +*HTTP Example (URL-encoded):* +```bash +curl -X POST http://localhost:3500/v1.0/invoke/serviceB/method/hello \ + -H "Content-Type: application/json" \ + -H "baggage: userID=cassie,serverNode=DF%2028" \ + -d '{"message": "Hello service B"}' +``` + +*gRPC Example (URL-encoded):* ```go ctx = grpcMetadata.AppendToOutgoingContext(ctx, - "baggage", "key1=value1,key2=value2", - ) + "baggage", "userID=cassie,serverNode=DF%2028", +) ``` #### Common Use Cases @@ -146,6 +219,19 @@ ctx = grpcMetadata.AppendToOutgoingContext(ctx, Baggage is useful for: - Propagating user IDs or correlation IDs across services - Passing tenant or environment information +- Maintaining consistent context across service boundaries +- Debugging and troubleshooting distributed transactions + +#### Best Practices + +1. **Choose the Right Mechanism** + - Use Context Baggage when working with OpenTelemetry + - Use Header Baggage when working directly with HTTP/gRPC + +2. **Security Considerations** + - Be mindful that baggage is propagated across service boundaries + - Don't include sensitive information in baggage + - Remember that context and header baggage remain separate ## Related Links diff --git a/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md b/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md index 4f08b81c562..760c027c726 100644 --- a/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md +++ b/daprdocs/content/en/operations/observability/tracing/w3c-tracing-overview.md @@ -73,17 +73,35 @@ tracestate: congo=t61rcWkgMzE [Learn more about the tracestate fields details](https://www.w3.org/TR/trace-context/#tracestate-header). -**Baggage header** - -Dapr supports [W3C Baggage](https://www.w3.org/TR/baggage/) for propagating key-value pairs alongside trace context. The baggage header allows you to attach metadata to trace context that needs to be propagated throughout your distributed system, such as user IDs, tenant information, or environment details. - -The header value follows the W3C Baggage specification format: - -``` -baggage: userId=alice,serverNode=DF%2028,isVIP=true -``` - -Multiple baggage headers are supported and will be combined according to the W3C specification. Dapr automatically propagates baggage headers across service calls. +**Baggage Support** + +Dapr supports [W3C Baggage](https://www.w3.org/TR/baggage/) for propagating key-value pairs alongside trace context through two distinct mechanisms: + +1. **Context Baggage (OpenTelemetry)** + - Follows OpenTelemetry conventions with decoded values + - Used when propagating baggage through application context + - Values are stored in their original, unencoded form + - Example of how it would be printed with OpenTelemetry APIs: + ``` + baggage: userId=cassie,serverNode=DF 28,isVIP=true + ``` + +2. **HTTP Header Baggage** + - You must URL encode special characters (for example, `%20` for spaces, `%2F` for slashes) when setting header baggage + - Values remain percent-encoded in HTTP headers as required by the W3C Baggage spec + - Values stay encoded when inspecting raw headers in Dapr + - Only OpenTelemetry APIs like `otelbaggage.Parse()` will decode the values + - Example (note the URL-encoded space `%20`): + ```bash + curl -X POST http://localhost:3500/v1.0/invoke/serviceB/method/hello \ + -H "Content-Type: application/json" \ + -H "baggage: userId=cassie,serverNode=DF%2028,isVIP=true" \ + -d '{"message": "Hello service B"}' + ``` + +For security purposes, context baggage and header baggage are strictly separated and never merged between domains. This ensures that baggage values maintain their intended format and security properties in each domain. + +Multiple baggage headers are supported and will be combined according to the W3C specification. Dapr automatically propagates baggage across service calls while maintaining the appropriate encoding for each domain. {{% /codetab %}} @@ -93,17 +111,30 @@ Multiple baggage headers are supported and will be combined according to the W3C In the gRPC API calls, trace context is passed through `grpc-trace-bin` header. -**Baggage metadata** +**Baggage Support** -Dapr supports [W3C Baggage](https://www.w3.org/TR/baggage/) for propagating key-value pairs alongside trace context. The baggage metadata allows you to attach metadata to trace context that needs to be propagated throughout your distributed system, such as user IDs, tenant information, or environment details. +Dapr supports [W3C Baggage](https://www.w3.org/TR/baggage/) for propagating key-value pairs alongside trace context through two distinct mechanisms: -The metadata value follows the W3C Baggage specification format: +1. **Context Baggage (OpenTelemetry)** + - Follows OpenTelemetry conventions with decoded values + - Used when propagating baggage through gRPC context + - Values are stored in their original, unencoded form + - Example of how it would be printed with OpenTelemetry APIs: + ``` + baggage: userId=cassie,serverNode=DF 28,isVIP=true + ``` -``` -baggage: userId=alice,serverNode=DF%2028,isVIP=true -``` +2. **gRPC Metadata Baggage** + - You must URL encode special characters (for example, `%20` for spaces, `%2F` for slashes) when setting metadata baggage + - Values remain percent-encoded in gRPC metadata + - Example (note the URL-encoded space `%20`): + ``` + baggage: userId=cassie,serverNode=DF%2028,isVIP=true + ``` + +For security purposes, context baggage and metadata baggage are strictly separated and never merged between domains. This ensures that baggage values maintain their intended format and security properties in each domain. -Multiple baggage metadata entries are supported and will be combined according to the W3C specification. Dapr automatically propagates baggage metadata across service calls. +Multiple baggage metadata entries are supported and will be combined according to the W3C specification. Dapr automatically propagates baggage across service calls while maintaining the appropriate encoding for each domain. {{% /codetab %}}