From 833d7cc9725028f0ef5a87264543dc53e91ecb20 Mon Sep 17 00:00:00 2001 From: Shalabh Mohan Shrivastava Date: Sun, 7 Jun 2020 16:10:41 -0700 Subject: [PATCH 1/9] Adding How to Use W3C Trace Context --- howto/use-w3c-tracecontext/README.md | 241 +++++++++++++++++++++++++++ 1 file changed, 241 insertions(+) create mode 100644 howto/use-w3c-tracecontext/README.md diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md new file mode 100644 index 000000000..bbb7f3368 --- /dev/null +++ b/howto/use-w3c-tracecontext/README.md @@ -0,0 +1,241 @@ +# W3C TraceContext - Background + +Distributed tracing is a methodology implemented by tracing tools to follow, analyze and debug a transaction across multiple software components. Typically, a distributed trace traverses more than one component which requires it to be uniquely identifiable across all participating systems. Trace context propagation passes along this unique identification. Today, trace context propagation is implemented individually by each tracing vendor. In multi-vendor environments, this causes interoperability problems, like: + +Traces that are collected by different tracing vendors cannot be correlated as there is no shared unique identifier. +Traces that cross boundaries between different tracing vendors can not be propagated as there is no uniformly agreed set of identification that is forwarded. +Vendor specific metadata might be dropped by intermediaries. +Cloud platform vendors, intermediaries and service providers, cannot guarantee to support trace context propagation as there is no standard to follow. +In the past, these problems did not have a significant impact as most applications were monitored by a single tracing vendor and stayed within the boundaries of a single platform provider. Today, an increasing number of applications are highly distributed and leverage multiple middleware services and cloud platforms. + +This transformation of modern applications calls for a distributed tracing context propagation standard. + +W3C trace context specification defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by + +* providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together. +* providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction. + * providing an industry standard that intermediaries, platforms, and hardware providers can support. + +A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis. The interoperability provided by trace context is a prerequisite to manage modern micro-service based applications. + +Please refer complete W3C context specifications [here](https://www.w3.org/TR/trace-context/). + +## W3C Trace Headers + +### Trace Context HTTP Headers Format + +#### Traceparent Header + +The traceparent header represents the incoming request in a tracing system in a common format, understood by all vendors. +Here’s an example of a traceparent header. + +`traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01` + +Please refer traceparent fields details [here](https://www.w3.org/TR/trace-context/#traceparent-header) + +#### Tracestate Header + +The tracestate header includes the parent in a potentially vendor-specific format: + +`tracestate: congo=t61rcWkgMzE` + +Please refer tracestate fields details [here](https://www.w3.org/TR/trace-context/#tracestate-header) + +### Trace Context gRPC Headers Format + +In the gRPC API calls, trace id is passed through `grpc-trace-bin` header. + + +## Using TraceContext in Dapr + +Dapr tracing is built on [OpenCensus](https://opencensus.io/introduction/) specifications that supports official W3C HTTP tracing header. +For the gRPC tracing , [here](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/gRPC.md) is more details with OpenCensus. + +Dapr provides in built support of OpenCensus instrmentation of services when tracing configuration is enabled through Dapr annotation. +Once the tracing configuration is applied, you will get full instrumentation of traces and you can retrieve the trace correlation id from the standard +W3C Context headers as outlined earlier. + +However if you choose to pass the trace context explictly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call. + +## How to pass TraceContext + +Since Dapr tracing is built on OpenCensus, user needs to send trace context using OpenCensus SDK. +OpenCensus supports majority of languages. + +| Language | SDK | +|:-------:|:----:| +| Go | [Link](https://pkg.go.dev/go.opencensus.io?tab=overview) +| Java | [Link](https://www.javadoc.io/doc/io.opencensus/opencensus-api/latest/index.html) +| C# | [Link](https://github.com/census-instrumentation/opencensus-csharp/) +| C++ | [Link](https://github.com/census-instrumentation/opencensus-cpp) +| Node.js | [Link](https://github.com/census-instrumentation/opencensus-node) +| Python | [Link](https://census-instrumentation.github.io/opencensus-python/trace/api/index.html) + +For the purpose of example, we will use the same [grpc app](../create-grpc-app) based on Go SDK. + +### Get the OpenCensus Go SDK + +Prerequisites: OpenCensus Go libraries require Go 1.8 or later. For details on installation and prerequisties, refer [here](https://pkg.go.dev/go.opencensus.io?tab=overview). + +`$ go get -u go.opencensus.io` + +1. import the package "go.opencensus.io/trace" +2. Create trace context + +When you want to pass the trace context , you will be starting the trace spans. At high level, since a distributed trace tracks the progression of a single user request as it is handled by the services and processes that make up an application. Each step is called a span in the trace. Spans include metadata about the step, including especially the time spent in the step, called the span’s latency. + +So Span is the unit step in a trace. Each span has a name, latency, status and additional metadata. + +Below we are starting a span for a cache read and ending it when we are done: + +```go +ctx, span := trace.StartSpan(ctx, "cache.Get") +defer span.End() + +// Do work to get from cache. +``` + +The StartSpan call returns 2 values. If you want to propagate trace context within your calls in the same process, you can use `context.Context` to propagate spans. +The returned `span` has the fields 'TraceID' and 'SpanID'. + +You can read more on these fields usage and details [here](https://opencensus.io/tracing/span/) + +When you call the Dapr API through HTTP/gRPC, you need to pass the tracecontext across process. For across the network, OpenCensus provides different propagation methods for different protocols. You can read about the propagation package [here](https://godoc.org/go.opencensus.io/trace/propagation). + +In our example, we will use gRPC calls , for that OpenCensus’ binary propagation format is used. + +3. Passing the trace context to Dapr + +#### gRPC calls +You need to import the package 'go.opencensus.io/trace/propagation'. +Once imported, get the span context from the generated span (as mentioned in above step 2), and convert it to OpenCensus binary propagation format. + +```go +traceContext := span.SpanContext() +traceContextBinary := propagation.Binary(traceContext) + ``` + +You can then pass the trace context through [gRPC metadata]("google.golang.org/grpc/metadata") through 'grpc-trace-bin` header. + +```go +ctx = metadata.AppendToOutgoingContext(ctx, "grpc-trace-bin", string(traceContextBinary)) +``` + +You can then pass this context `ctx` in Dapr gRPC calls as first parameter. For example `InvokeService`, context is passed in first parameter. + +#### HTTP calls + +HTTP integrations use Zipkin’s [B3](https://github.com/openzipkin/b3-propagation) by default but can be configured to use a custom propagation method by setting another propagation.HTTPFormat. + +For control over HTTP client headers, redirect policy, and other settings, you need to create a Client: +For this example, [net/http] (net/http) is used for HTTP calls. + +```go +f := &HTTPFormat{} +req, _ := http.NewRequest("GET", "http://localhost:3500/v1.0/invoke/mathService/method/api/v1/add", nil) + +traceContext := span.SpanContext() +f.SpanContextToRequest(traceContext, req) +``` + +Please go here for [Dapr API reference](https://github.com/dapr/docs/tree/master/reference/api). + +## Configuring Tracing in Dapr +As mentioned earlier, in this tracing example, we are using the same [grpc app](../create-grpc-app). + +So to enable tracing in Dapr, you need to first configure tracing in Dapr. +You can create deployment config yaml e.g. `appconfig.yaml` with following configuration. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + tracing: + samplingRate: "1" +``` + +In Kubernetes, you can apply the configuration as below : + +```bash +kubectl apply -f appconfig.yaml +``` + +You then set the following tracing annotation in your deployment YAML. You can add the following annotaion in sample [grpc app](../create-grpc-app) deployment yaml. + +```yaml +dapr.io/config: "appconfig" +``` + +That't it from Dapr side configuration. + +To view traces, you need to deploy OpenCensus supported exporters. This is independent of Dapr configuration. +You can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) to set up trace exporters. + +## Invoking Dapr With TraceContext + +As mentioned earlier in the [section](#Using TraceContext in Dapr), you can create the trace context and pass it through when calling Dapr or Dapr can generate trace context passed it back to you. + +If you choose to pass the trace context explictly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call. +We are using the same [grpc app](../create-grpc-app), however listing out the complete code for putting it all together. + +The following steps will only show you how to create a Dapr client and call the Save State operation when user is passing the trace context: +Rest code snippet and details , refer the same [grpc app](../create-grpc-app). + +1. Import the package + +```go +package main + +import ( + pb "github.com/dapr/go-sdk/dapr" + "go.opencensus.io/trace" + "go.opencensus.io/trace/propagation" + "google.golang.org/grpc" + "google.golang.org/grpc/metadata" +) +``` + +2. Create the client + +```go + // Get the Dapr port and create a connection + daprPort := os.Getenv("DAPR_GRPC_PORT") + daprAddress := fmt.Sprintf("localhost:%s", daprPort) + conn, err := grpc.Dial(daprAddress, grpc.WithInsecure()) + if err != nil { + fmt.Println(err) + } + defer conn.Close() + + // Create the client + client := pb.NewDaprClient(conn) +``` + +3. Invoke the InvokeService method With Trace Context + +```go + // Create the Trace Context + ctx , span := trace.StartSpan(context.Background(), "InvokeService") + + // The returned context can be used to keep propagating the newly created span in the current context. + // In the same process, context.Context is used to propagate trace context. + + // Across the process, use the propagation format of Trace Context to propagate trace context. + traceContext := propagation.Binary(span.SpanContext()) + ctx = metadata.NewOutgoingContext(ctx, string(traceContext)) + + // Pass the trace context + resp, err := client.InvokeService(ctx, &pb.InvokeServiceRequest{ + Id: "client", + Message: &commonv1pb.InvokeRequest{ + Method: "MyMethod", + ContentType: "text/plain; charset=UTF-8", + Data: &any.Any{Value: []byte("Hello")}, + }, + }) +``` + +That's it !. Now you can correlate the calls in your app and in Dapr across services using the same trace context. + From 7936fdd81d4da8e8776c752778b323dd3a5af5b4 Mon Sep 17 00:00:00 2001 From: Shalabh Mohan Shrivastava Date: Sun, 7 Jun 2020 16:37:16 -0700 Subject: [PATCH 2/9] Separating word TraceContext to Trace Context --- howto/use-w3c-tracecontext/README.md | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md index bbb7f3368..8dd488359 100644 --- a/howto/use-w3c-tracecontext/README.md +++ b/howto/use-w3c-tracecontext/README.md @@ -1,4 +1,4 @@ -# W3C TraceContext - Background +# W3C Trace Context - Background Distributed tracing is a methodology implemented by tracing tools to follow, analyze and debug a transaction across multiple software components. Typically, a distributed trace traverses more than one component which requires it to be uniquely identifiable across all participating systems. Trace context propagation passes along this unique identification. Today, trace context propagation is implemented individually by each tracing vendor. In multi-vendor environments, this causes interoperability problems, like: @@ -22,7 +22,7 @@ Please refer complete W3C context specifications [here](https://www.w3.org/TR/tr ## W3C Trace Headers -### Trace Context HTTP Headers Format +### Trace Context HTTP Headers Format #### Traceparent Header @@ -41,12 +41,12 @@ The tracestate header includes the parent in a potentially vendor-specific forma Please refer tracestate fields details [here](https://www.w3.org/TR/trace-context/#tracestate-header) -### Trace Context gRPC Headers Format +### Trace Context gRPC Headers Format -In the gRPC API calls, trace id is passed through `grpc-trace-bin` header. +In the gRPC API calls, trace context is passed through `grpc-trace-bin` header. -## Using TraceContext in Dapr +## Using Trace Context in Dapr Dapr tracing is built on [OpenCensus](https://opencensus.io/introduction/) specifications that supports official W3C HTTP tracing header. For the gRPC tracing , [here](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/gRPC.md) is more details with OpenCensus. @@ -57,7 +57,7 @@ W3C Context headers as outlined earlier. However if you choose to pass the trace context explictly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call. -## How to pass TraceContext +## How to pass Trace Context Since Dapr tracing is built on OpenCensus, user needs to send trace context using OpenCensus SDK. OpenCensus supports majority of languages. @@ -100,7 +100,7 @@ The returned `span` has the fields 'TraceID' and 'SpanID'. You can read more on these fields usage and details [here](https://opencensus.io/tracing/span/) -When you call the Dapr API through HTTP/gRPC, you need to pass the tracecontext across process. For across the network, OpenCensus provides different propagation methods for different protocols. You can read about the propagation package [here](https://godoc.org/go.opencensus.io/trace/propagation). +When you call the Dapr API through HTTP/gRPC, you need to pass the trace context across process. For across the network, OpenCensus provides different propagation methods for different protocols. You can read about the propagation package [here](https://godoc.org/go.opencensus.io/trace/propagation). In our example, we will use gRPC calls , for that OpenCensus’ binary propagation format is used. @@ -173,9 +173,9 @@ That't it from Dapr side configuration. To view traces, you need to deploy OpenCensus supported exporters. This is independent of Dapr configuration. You can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) to set up trace exporters. -## Invoking Dapr With TraceContext +## Invoking Dapr With Trace Context -As mentioned earlier in the [section](#Using TraceContext in Dapr), you can create the trace context and pass it through when calling Dapr or Dapr can generate trace context passed it back to you. +As mentioned earlier in the [section](#Using-Trace-Context-in-Dapr), you can create the trace context and pass it through when calling Dapr or Dapr can generate trace context passed it back to you. If you choose to pass the trace context explictly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call. We are using the same [grpc app](../create-grpc-app), however listing out the complete code for putting it all together. @@ -239,3 +239,5 @@ import ( That's it !. Now you can correlate the calls in your app and in Dapr across services using the same trace context. +To view traces, you can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) e.g Zipkin/Application Insights. + From bef9178f2e7aa750e70af4ff82d1ce38eccfa78d Mon Sep 17 00:00:00 2001 From: Shalabh Mohan Shrivastava Date: Mon, 8 Jun 2020 11:47:15 -0700 Subject: [PATCH 3/9] Resolving doc review comments --- concepts/observability/traces.md | 2 ++ howto/diagnose-with-tracing/azure-monitor.md | 4 +++ howto/diagnose-with-tracing/zipkin.md | 3 ++ howto/use-w3c-tracecontext/README.md | 32 +++++++++++++++----- 4 files changed, 33 insertions(+), 8 deletions(-) diff --git a/concepts/observability/traces.md b/concepts/observability/traces.md index e3674d4b4..77840291b 100644 --- a/concepts/observability/traces.md +++ b/concepts/observability/traces.md @@ -66,3 +66,5 @@ spec: * [How-To: Set up Application Insights for distributed tracing](../../howto/diagnose-with-tracing/azure-monitor.md) * [How-To: Set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md) +* [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) + diff --git a/howto/diagnose-with-tracing/azure-monitor.md b/howto/diagnose-with-tracing/azure-monitor.md index d1a7b607f..1d34c1af3 100644 --- a/howto/diagnose-with-tracing/azure-monitor.md +++ b/howto/diagnose-with-tracing/azure-monitor.md @@ -180,3 +180,7 @@ samplingRate | string | Set sampling rate for tracing to be enabled or disabled `samplingRate` is used to enable or disable the tracing. To disable the sampling rate , set `samplingRate : "0"` in the configuration. The valid range of samplingRate is between 0 and 1 inclusive. The sampling rate determines whether a trace span should be sampled or not based on value. `samplingRate : "1"` will always sample the traces.By default, the sampling rate is 1 in 10,000 + +## References + +* [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) diff --git a/howto/diagnose-with-tracing/zipkin.md b/howto/diagnose-with-tracing/zipkin.md index e592c1d83..cf4d39d69 100644 --- a/howto/diagnose-with-tracing/zipkin.md +++ b/howto/diagnose-with-tracing/zipkin.md @@ -154,3 +154,6 @@ samplingRate | string | Set sampling rate for tracing to be enabled or disabled `samplingRate` is used to enable or disable the tracing. To disable the sampling rate , set `samplingRate : "0"` in the configuration. The valid range of samplingRate is between 0 and 1 inclusive. The sampling rate determines whether a trace span should be sampled or not based on value. `samplingRate : "1"` will always sample the traces.By default, the sampling rate is 1 in 10,000 +## References + +* [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) \ No newline at end of file diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md index 8dd488359..b567a34dc 100644 --- a/howto/use-w3c-tracecontext/README.md +++ b/howto/use-w3c-tracecontext/README.md @@ -1,4 +1,10 @@ -# W3C Trace Context - Background +## Contents + +- [Background](#Background) +- [Using Trace Context in Dapr](#Using-Trace-Context-in-Dapr) +- [Related Links](#Related-Links) + +# Background Distributed tracing is a methodology implemented by tracing tools to follow, analyze and debug a transaction across multiple software components. Typically, a distributed trace traverses more than one component which requires it to be uniquely identifiable across all participating systems. Trace context propagation passes along this unique identification. Today, trace context propagation is implemented individually by each tracing vendor. In multi-vendor environments, this causes interoperability problems, like: @@ -18,7 +24,7 @@ W3C trace context specification defines a universally agreed-upon format for the A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis. The interoperability provided by trace context is a prerequisite to manage modern micro-service based applications. -Please refer complete W3C context specifications [here](https://www.w3.org/TR/trace-context/). +Please refer complete [W3C trace context](https://www.w3.org/TR/trace-context/) specifications here. ## W3C Trace Headers @@ -46,7 +52,7 @@ Please refer tracestate fields details [here](https://www.w3.org/TR/trace-contex In the gRPC API calls, trace context is passed through `grpc-trace-bin` header. -## Using Trace Context in Dapr +# Using Trace Context in Dapr Dapr tracing is built on [OpenCensus](https://opencensus.io/introduction/) specifications that supports official W3C HTTP tracing header. For the gRPC tracing , [here](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/gRPC.md) is more details with OpenCensus. @@ -71,7 +77,7 @@ OpenCensus supports majority of languages. | Node.js | [Link](https://github.com/census-instrumentation/opencensus-node) | Python | [Link](https://census-instrumentation.github.io/opencensus-python/trace/api/index.html) -For the purpose of example, we will use the same [grpc app](../create-grpc-app) based on Go SDK. +Same [grpc app](../create-grpc-app) based on Go SDK is used for the purpose of the example. ### Get the OpenCensus Go SDK @@ -86,7 +92,7 @@ When you want to pass the trace context , you will be starting the trace spans. So Span is the unit step in a trace. Each span has a name, latency, status and additional metadata. -Below we are starting a span for a cache read and ending it when we are done: +Below code snippet shows starting a span for a cache read and ending it when done: ```go ctx, span := trace.StartSpan(ctx, "cache.Get") @@ -102,7 +108,7 @@ You can read more on these fields usage and details [here](https://opencensus.io When you call the Dapr API through HTTP/gRPC, you need to pass the trace context across process. For across the network, OpenCensus provides different propagation methods for different protocols. You can read about the propagation package [here](https://godoc.org/go.opencensus.io/trace/propagation). -In our example, we will use gRPC calls , for that OpenCensus’ binary propagation format is used. +In our example, since gRPC calls are used , so for that OpenCensus’ binary propagation format is used. 3. Passing the trace context to Dapr @@ -141,7 +147,7 @@ f.SpanContextToRequest(traceContext, req) Please go here for [Dapr API reference](https://github.com/dapr/docs/tree/master/reference/api). ## Configuring Tracing in Dapr -As mentioned earlier, in this tracing example, we are using the same [grpc app](../create-grpc-app). +As mentioned earlier, same [grpc app](../create-grpc-app) based on Go SDK is used for the purpose of the example. So to enable tracing in Dapr, you need to first configure tracing in Dapr. You can create deployment config yaml e.g. `appconfig.yaml` with following configuration. @@ -178,7 +184,8 @@ You can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) to set up As mentioned earlier in the [section](#Using-Trace-Context-in-Dapr), you can create the trace context and pass it through when calling Dapr or Dapr can generate trace context passed it back to you. If you choose to pass the trace context explictly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call. -We are using the same [grpc app](../create-grpc-app), however listing out the complete code for putting it all together. + +Though the same [grpc app](../create-grpc-app) is used for the example, but still listing out the complete code for putting it all together. The following steps will only show you how to create a Dapr client and call the Save State operation when user is passing the trace context: Rest code snippet and details , refer the same [grpc app](../create-grpc-app). @@ -241,3 +248,12 @@ That's it !. Now you can correlate the calls in your app and in Dapr across serv To view traces, you can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) e.g Zipkin/Application Insights. +# Related Links + +* [Observability Concepts](../../concepts/observability/traces.md) +* [Observability Sample](https://github.com/dapr/samples/tree/master/8.observability) +* [How-To: Set up Application Insights for distributed tracing](../../howto/diagnose-with-tracing/azure-monitor.md) +* [How-To: Set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md) +* [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) + + From c9491601860d48ba9a648a06337763b5f11b4391 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Mon, 8 Jun 2020 12:15:38 -0700 Subject: [PATCH 4/9] Fixing article headers --- howto/use-w3c-tracecontext/README.md | 46 ++++++++++++++++------------ 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md index b567a34dc..8b78972b2 100644 --- a/howto/use-w3c-tracecontext/README.md +++ b/howto/use-w3c-tracecontext/README.md @@ -1,10 +1,18 @@ +# W3C Tracing Context + ## Contents -- [Background](#Background) -- [Using Trace Context in Dapr](#Using-Trace-Context-in-Dapr) -- [Related Links](#Related-Links) +- [Background](#background) +- [W3C trace headers](#w3c-trace-headers) + - [Trace context HTTP headers format](#trace-context-http-headers-format) + - [Trace context gRPC headers format](#trace-context-grpc-headers-format) +- [Using trace context in Dapr](#using-trace-context-in-dapr) + - [How to pass a trace context](#how-to-pass-a-trace-context) + - [Configuring tracing in Dapr](#configuring-tracing-in-dapr) + - [Invoking Dapr with trace context](#invoking-dapr-with-trace-context) +- [Related Links](#related-links) -# Background +## Background Distributed tracing is a methodology implemented by tracing tools to follow, analyze and debug a transaction across multiple software components. Typically, a distributed trace traverses more than one component which requires it to be uniquely identifiable across all participating systems. Trace context propagation passes along this unique identification. Today, trace context propagation is implemented individually by each tracing vendor. In multi-vendor environments, this causes interoperability problems, like: @@ -16,7 +24,7 @@ In the past, these problems did not have a significant impact as most applicatio This transformation of modern applications calls for a distributed tracing context propagation standard. -W3C trace context specification defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by +[W3C trace context specification](https://www.w3.org/TR/trace-context/) defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by * providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together. * providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction. @@ -24,11 +32,9 @@ W3C trace context specification defines a universally agreed-upon format for the A unified approach for propagating trace data improves visibility into the behavior of distributed applications, facilitating problem and performance analysis. The interoperability provided by trace context is a prerequisite to manage modern micro-service based applications. -Please refer complete [W3C trace context](https://www.w3.org/TR/trace-context/) specifications here. +## W3C trace headers -## W3C Trace Headers - -### Trace Context HTTP Headers Format +### Trace context HTTP headers format #### Traceparent Header @@ -47,23 +53,23 @@ The tracestate header includes the parent in a potentially vendor-specific forma Please refer tracestate fields details [here](https://www.w3.org/TR/trace-context/#tracestate-header) -### Trace Context gRPC Headers Format +### Trace context gRPC headers format In the gRPC API calls, trace context is passed through `grpc-trace-bin` header. -# Using Trace Context in Dapr +## Using trace context in Dapr Dapr tracing is built on [OpenCensus](https://opencensus.io/introduction/) specifications that supports official W3C HTTP tracing header. For the gRPC tracing , [here](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/gRPC.md) is more details with OpenCensus. Dapr provides in built support of OpenCensus instrmentation of services when tracing configuration is enabled through Dapr annotation. Once the tracing configuration is applied, you will get full instrumentation of traces and you can retrieve the trace correlation id from the standard -W3C Context headers as outlined earlier. +W3C context headers as outlined earlier. However if you choose to pass the trace context explictly, then Dapr will use the passed trace context and propagate all across the HTTP/gRPC call. -## How to pass Trace Context +### How to pass a trace context Since Dapr tracing is built on OpenCensus, user needs to send trace context using OpenCensus SDK. OpenCensus supports majority of languages. @@ -79,7 +85,7 @@ OpenCensus supports majority of languages. Same [grpc app](../create-grpc-app) based on Go SDK is used for the purpose of the example. -### Get the OpenCensus Go SDK +#### Get the OpenCensus Go SDK Prerequisites: OpenCensus Go libraries require Go 1.8 or later. For details on installation and prerequisties, refer [here](https://pkg.go.dev/go.opencensus.io?tab=overview). @@ -112,7 +118,7 @@ In our example, since gRPC calls are used , so for that OpenCensus’ binary pro 3. Passing the trace context to Dapr -#### gRPC calls +##### gRPC calls You need to import the package 'go.opencensus.io/trace/propagation'. Once imported, get the span context from the generated span (as mentioned in above step 2), and convert it to OpenCensus binary propagation format. @@ -129,7 +135,7 @@ ctx = metadata.AppendToOutgoingContext(ctx, "grpc-trace-bin", string(traceContex You can then pass this context `ctx` in Dapr gRPC calls as first parameter. For example `InvokeService`, context is passed in first parameter. -#### HTTP calls +##### HTTP calls HTTP integrations use Zipkin’s [B3](https://github.com/openzipkin/b3-propagation) by default but can be configured to use a custom propagation method by setting another propagation.HTTPFormat. @@ -146,7 +152,7 @@ f.SpanContextToRequest(traceContext, req) Please go here for [Dapr API reference](https://github.com/dapr/docs/tree/master/reference/api). -## Configuring Tracing in Dapr +### Configuring tracing in Dapr As mentioned earlier, same [grpc app](../create-grpc-app) based on Go SDK is used for the purpose of the example. So to enable tracing in Dapr, you need to first configure tracing in Dapr. @@ -179,7 +185,7 @@ That't it from Dapr side configuration. To view traces, you need to deploy OpenCensus supported exporters. This is independent of Dapr configuration. You can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) to set up trace exporters. -## Invoking Dapr With Trace Context +### Invoking Dapr With trace context As mentioned earlier in the [section](#Using-Trace-Context-in-Dapr), you can create the trace context and pass it through when calling Dapr or Dapr can generate trace context passed it back to you. @@ -248,12 +254,12 @@ That's it !. Now you can correlate the calls in your app and in Dapr across serv To view traces, you can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) e.g Zipkin/Application Insights. -# Related Links +## Related Links * [Observability Concepts](../../concepts/observability/traces.md) * [Observability Sample](https://github.com/dapr/samples/tree/master/8.observability) * [How-To: Set up Application Insights for distributed tracing](../../howto/diagnose-with-tracing/azure-monitor.md) * [How-To: Set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md) * [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) - +* [W3C trace context specification](https://www.w3.org/TR/trace-context/) From 383479dcf3eb3ba887166197094aeb42be3421ef Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Mon, 8 Jun 2020 12:17:12 -0700 Subject: [PATCH 5/9] Small header tweak --- howto/use-w3c-tracecontext/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md index 8b78972b2..02b3adf91 100644 --- a/howto/use-w3c-tracecontext/README.md +++ b/howto/use-w3c-tracecontext/README.md @@ -185,7 +185,7 @@ That't it from Dapr side configuration. To view traces, you need to deploy OpenCensus supported exporters. This is independent of Dapr configuration. You can refer [how-to-diagnose-with-tracing](../diagnose-with-tracing) to set up trace exporters. -### Invoking Dapr With trace context +### Invoking Dapr with trace context As mentioned earlier in the [section](#Using-Trace-Context-in-Dapr), you can create the trace context and pass it through when calling Dapr or Dapr can generate trace context passed it back to you. From 74885a7abea798b06e86823d0ddaf4374461ec32 Mon Sep 17 00:00:00 2001 From: Shalabh Mohan Shrivastava Date: Mon, 8 Jun 2020 12:28:43 -0700 Subject: [PATCH 6/9] Adding link from main observability how-to --- howto/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/howto/README.md b/howto/README.md index 3b4529856..40179cf03 100644 --- a/howto/README.md +++ b/howto/README.md @@ -59,6 +59,7 @@ For Actors How Tos see the SDK documentation ### Distributed Tracing * [Diagnose your services with distributed tracing](./diagnose-with-tracing) +* [How-To: Use W3C Trace Context for distributed tracing](./use-w3c-tracecontext/readme.md) ## Security From 883e8c6332ce430c9a4e532930f30982e2298577 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Mon, 8 Jun 2020 12:31:17 -0700 Subject: [PATCH 7/9] Fix to standardize link wording --- howto/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/howto/README.md b/howto/README.md index 40179cf03..e49202534 100644 --- a/howto/README.md +++ b/howto/README.md @@ -59,7 +59,7 @@ For Actors How Tos see the SDK documentation ### Distributed Tracing * [Diagnose your services with distributed tracing](./diagnose-with-tracing) -* [How-To: Use W3C Trace Context for distributed tracing](./use-w3c-tracecontext/readme.md) +* [Use W3C trace context for distributed tracing](./use-w3c-tracecontext/readme.md) ## Security From f062c47ed060f06e48d97c2c85fcc9b60e796365 Mon Sep 17 00:00:00 2001 From: Shalabh Mohan Shrivastava Date: Mon, 8 Jun 2020 12:38:09 -0700 Subject: [PATCH 8/9] Standardized trace context to Trace Context in the link --- howto/use-w3c-tracecontext/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md index 02b3adf91..6f2378323 100644 --- a/howto/use-w3c-tracecontext/README.md +++ b/howto/use-w3c-tracecontext/README.md @@ -24,7 +24,7 @@ In the past, these problems did not have a significant impact as most applicatio This transformation of modern applications calls for a distributed tracing context propagation standard. -[W3C trace context specification](https://www.w3.org/TR/trace-context/) defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by +[W3C Trace Context specification](https://www.w3.org/TR/trace-context/) defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by * providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together. * providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction. @@ -261,5 +261,5 @@ To view traces, you can refer [how-to-diagnose-with-tracing](../diagnose-with-tr * [How-To: Set up Application Insights for distributed tracing](../../howto/diagnose-with-tracing/azure-monitor.md) * [How-To: Set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md) * [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) -* [W3C trace context specification](https://www.w3.org/TR/trace-context/) +* [W3C Trace Context specification](https://www.w3.org/TR/trace-context/) From e829d883a3385e0146c1b6fcbf8820ad71c22b69 Mon Sep 17 00:00:00 2001 From: Shalabh Mohan Shrivastava Date: Mon, 8 Jun 2020 12:56:11 -0700 Subject: [PATCH 9/9] reverting --- howto/use-w3c-tracecontext/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/howto/use-w3c-tracecontext/README.md b/howto/use-w3c-tracecontext/README.md index 6f2378323..02b3adf91 100644 --- a/howto/use-w3c-tracecontext/README.md +++ b/howto/use-w3c-tracecontext/README.md @@ -24,7 +24,7 @@ In the past, these problems did not have a significant impact as most applicatio This transformation of modern applications calls for a distributed tracing context propagation standard. -[W3C Trace Context specification](https://www.w3.org/TR/trace-context/) defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by +[W3C trace context specification](https://www.w3.org/TR/trace-context/) defines a universally agreed-upon format for the exchange of trace context propagation data - referred to as trace context. Trace context solves the problems described above by * providing an unique identifier for individual traces and requests, allowing trace data of multiple providers to be linked together. * providing an agreed-upon mechanism to forward vendor-specific trace data and avoid broken traces when multiple tracing tools participate in a single transaction. @@ -261,5 +261,5 @@ To view traces, you can refer [how-to-diagnose-with-tracing](../diagnose-with-tr * [How-To: Set up Application Insights for distributed tracing](../../howto/diagnose-with-tracing/azure-monitor.md) * [How-To: Set up Zipkin for distributed tracing](../../howto/diagnose-with-tracing/zipkin.md) * [How-To: Use W3C Trace Context for distributed tracing](../../howto/use-w3c-tracecontext/readme.md) -* [W3C Trace Context specification](https://www.w3.org/TR/trace-context/) +* [W3C trace context specification](https://www.w3.org/TR/trace-context/)