From d5090aa8cedf734e6a8d53484fe373142bb437de Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 19 Nov 2021 13:58:55 +0100 Subject: [PATCH] Clarify usage of Distributed Tracing Extension by OpenTelemetry (#1) Signed-off-by: Joao Grassi --- extensions/distributed-tracing.md | 70 ++++++++++++++----------------- 1 file changed, 32 insertions(+), 38 deletions(-) diff --git a/extensions/distributed-tracing.md b/extensions/distributed-tracing.md index ea32bfa6a..1235942ba 100644 --- a/extensions/distributed-tracing.md +++ b/extensions/distributed-tracing.md @@ -1,55 +1,49 @@ # Distributed Tracing extension This extension embeds context from -[Distributed Tracing](https://w3c.github.io/trace-context/) so that distributed -systems can include traces that span an event-driven system. This extension is -meant to contain historical data of the parent trace, in order to diagnose -eventual failures of the system through tracing platforms like Jaeger, Zipkin, -etc. +[W3C TraceContext](https://www.w3.org/TR/trace-context/) into a CloudEvent. +The goal of this extension is to offer means to carry context when instrumenting +CloudEvents based systems with OpenTelemetry. + +The [OpenTelemetry](https://opentelemetry.io/) project is a collection +of tools, APIs and SDKs that can be used to instrument, generate, collect, +and export telemetry data (metrics, logs, and traces) to help you +analyze your software’s performance and behavior. + +The OpenTelemetry specification defines both +[Context](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/context/context.md#overview) +and +[Distributed Tracing](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/overview.md#tracing-signal) +as: + +> A `Context` is a propagation mechanism which carries execution-scoped values across + API boundaries and between logically associated execution units. Cross-cutting + concerns access their data in-process using the same shared `Context` object. +> +> A `Distributed Trace` is a set of events, triggered as a result of a single + logical operation, consolidated across various components of an application. + A distributed trace contains events that cross process, network and security boundaries. + +## Using the Distributed Tracing Extension + +The +[OpenTelemetry Semantic Conventions for CloudEvents](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.9.0/specification/trace/semantic_conventions/cloudevents.md) +define in which scenarios this extension should be used and how to use it. ## Attributes -#### traceparent +### traceparent - Type: `String` - Description: Contains a version, trace ID, span ID, and trace options as - defined in [section 3.2](https://w3c.github.io/trace-context/#traceparent-header) + defined in [section 3.2](https://www.w3.org/TR/trace-context/#traceparent-header) - Constraints - REQUIRED -#### tracestate +### tracestate - Type: `String` - Description: a comma-delimited list of key-value pairs, defined by - [section 3.3](https://w3c.github.io/trace-context/#tracestate-header). + [section 3.3](https://www.w3.org/TR/trace-context/#tracestate-header). - Constraints - OPTIONAL - -## Using the Distributed Tracing Extension - -The Distributed Tracing Extension is not intended to replace the protocol specific headers for tracing, -like the ones described in [W3C Trace Context](https://w3c.github.io/trace-context/) for HTTP. - -Given a single hop event transmission (from sink to source directly), the Distributed Tracing Extension, -if used, MUST carry the same trace information contained in protocol specific tracing headers. - -Given a multi hop event transmission, the Distributed Tracing Extension, if used, MUST -carry the trace information of the starting trace of the transmission. -In other words, it MUST NOT carry trace information of each individual hop, since this information is usually -carried using protocol specific headers, understood by tools like [OpenTelemetry](https://opentelemetry.io/). - -Middleware between the source and the sink of the event could eventually add a Distributed Tracing Extension -if the source didn't include any, in order to provide to the sink the starting trace of the transmission. - -An example with HTTP: - -```bash -CURL -X POST example/webhook.json \ --H 'ce-id: 1' \ --H 'ce-specversion: 1.0' \ --H 'ce-type: example' \ --H 'ce-source: http://localhost' \ --H 'ce-traceparent: 00-0af7651916cd43dd8448eb211c80319c-b9c7c989f97918e1-01' \ --H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' \ --H 'tracestate: rojo=00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01,congo=lZWRzIHRoNhcm5hbCBwbGVhc3VyZS4` -```