From 93565f4ae8193dd123d324aeadaa5c94a28e4605 Mon Sep 17 00:00:00 2001
From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
Date: Tue, 16 Jul 2024 10:24:15 +0200
Subject: [PATCH] doc: link distributed tracing extension to otel semconv

Signed-off-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
---
 cloudevents/extensions/distributed-tracing.md | 38 +++++++++++++++----
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/cloudevents/extensions/distributed-tracing.md b/cloudevents/extensions/distributed-tracing.md
index a1c44e5b7..dea27e79e 100644
--- a/cloudevents/extensions/distributed-tracing.md
+++ b/cloudevents/extensions/distributed-tracing.md
@@ -1,11 +1,28 @@
 # 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.
 
 ## Notational Conventions
 
@@ -16,12 +33,12 @@ described in [RFC 2119](https://tools.ietf.org/html/rfc2119).
 
 However, the scope of these key words is limited to when this extension is
 used. For example, an attribute being marked as "REQUIRED" does not mean
-it needs to be in all CloudEvents, rather it needs to be included only when 
+it needs to be in all CloudEvents, rather it needs to be included only when
 this extension is being used.
 
 ## Attributes
 
-#### traceparent
+### traceparent
 
 - Type: `String`
 - Description: Contains a version, trace ID, span ID, and trace options as
@@ -29,7 +46,7 @@ this extension is being used.
 - Constraints
   - REQUIRED
 
-#### tracestate
+### tracestate
 
 - Type: `String`
 - Description: a comma-delimited list of key-value pairs, defined by
@@ -50,6 +67,11 @@ 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/).
 
+The
+[OpenTelemetry Semantic Conventions for CloudEvents](https://opentelemetry.io/docs/specs/semconv/cloudevents/cloudevents-spans/)
+define the trace structure to follow when instrumenting CloudEvent systems and
+in which scenarios this extension can be used and how to use it to achieve said structure.
+
 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.