-
Notifications
You must be signed in to change notification settings - Fork 583
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Clarify usage of Distributed Tracing Extension by OpenTelemetry (#1)
- Loading branch information
1 parent
246ec9a
commit 6c0c753
Showing
1 changed file
with
32 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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` | ||
| ``` |