From 2df5ad193c9b34c5a3196d228565f3d16919319f Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Fri, 4 Aug 2023 11:01:11 -0700 Subject: [PATCH 01/11] Add W3C-specified trace flags to v1 Span proto --- opentelemetry/proto/trace/v1/trace.proto | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index b2869edc4..c8a939e1a 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -76,7 +76,7 @@ message ScopeSpans { // A Span represents a single operation performed by a single component of the system. // -// The next available field id is 17. +// The next available field id is 18. message Span { // A unique identifier for a trace. All spans from the same trace share // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR @@ -103,6 +103,12 @@ message Span { // field must be empty. The ID is an 8-byte array. bytes parent_span_id = 4; + // Flags from the W3C traceparent, if provided. + // There are two flags defined in the W3C Trace Context Level 2 spec: + // - sampled = 0x1 + // - random = 0x2 + uint32 trace_flags = 17; + // A description of the span's operation. // // For example, the name can be a qualified method name or a file name @@ -236,6 +242,12 @@ message Span { // dropped_attributes_count is the number of dropped attributes. If the value is 0, // then no attributes were dropped. uint32 dropped_attributes_count = 5; + + // Flags from the W3C traceparent, if provided. + // There are two flags defined in the W3C Trace Context Level 2 spec: + // - sampled = 0x1 + // - random = 0x2 + uint32 trace_flags = 6; } // links is a collection of Links, which are references from this span to a span From 3beb053c443b3a2bf0ab3354be84075966ce434b Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Fri, 4 Aug 2023 11:04:48 -0700 Subject: [PATCH 02/11] draft changelog --- CHANGELOG.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b93bd0618..470f1f43e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,11 @@ Full list of differences found in [this compare](https://github.com/open-telemetry/opentelemetry-proto/compare/v1.0.0...main). +### Added + +* Add a field for W3C-specified Trace Context flags to the `Span` and `Link`. + [#503](https://github.com/open-telemetry/opentelemetry-proto/pull/503) + ## 1.0.0 - 2023-07-03 Full list of differences found in [this compare](https://github.com/open-telemetry/opentelemetry-proto/compare/v0.20.0...v1.0.0). From d26fab16f590f17ac1423160331122d5b8cd03a4 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 10 Aug 2023 09:31:51 -0700 Subject: [PATCH 03/11] Link context is for the link --- opentelemetry/proto/trace/v1/trace.proto | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index c8a939e1a..648b874fe 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -243,7 +243,7 @@ message Span { // then no attributes were dropped. uint32 dropped_attributes_count = 5; - // Flags from the W3C traceparent, if provided. + // Flags from the linked span's traceparent, if provided. // There are two flags defined in the W3C Trace Context Level 2 spec: // - sampled = 0x1 // - random = 0x2 From 493d1a3824120f16e70f0e69debbd6235eb4520e Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 10 Aug 2023 09:33:11 -0700 Subject: [PATCH 04/11] use 16 --- opentelemetry/proto/trace/v1/trace.proto | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 648b874fe..371ab351b 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -76,7 +76,7 @@ message ScopeSpans { // A Span represents a single operation performed by a single component of the system. // -// The next available field id is 18. +// The next available field id is 17. message Span { // A unique identifier for a trace. All spans from the same trace share // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR @@ -107,7 +107,7 @@ message Span { // There are two flags defined in the W3C Trace Context Level 2 spec: // - sampled = 0x1 // - random = 0x2 - uint32 trace_flags = 17; + uint32 trace_flags = 16; // A description of the span's operation. // From 05e412fbc8a6d4a5af55ddc1b56c7d09f0ffcba9 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 21 Aug 2023 11:28:19 -0700 Subject: [PATCH 05/11] feedback applied --- opentelemetry/proto/logs/v1/logs.proto | 8 +++-- opentelemetry/proto/trace/v1/trace.proto | 46 ++++++++++++++++++------ 2 files changed, 41 insertions(+), 13 deletions(-) diff --git a/opentelemetry/proto/logs/v1/logs.proto b/opentelemetry/proto/logs/v1/logs.proto index 0b4b64972..7a11b5378 100644 --- a/opentelemetry/proto/logs/v1/logs.proto +++ b/opentelemetry/proto/logs/v1/logs.proto @@ -104,9 +104,11 @@ enum SeverityNumber { SEVERITY_NUMBER_FATAL4 = 24; } -// LogRecordFlags is defined as a protobuf 'uint32' type and is to be used as -// bit-fields. Each non-zero value defined in this enum is a bit-mask. -// To extract the bit-field, for example, use an expression like: +// LogRecordFlags represents constants used to interpret the +// LogRecord.flags field, which is protobuf 'fixed32' type and is to +// be used as bit-fields. Each non-zero value defined in this enum is +// a bit-mask. To extract the bit-field, for example, use an +// expression like: // // (logRecord.flags & LOG_RECORD_FLAGS_TRACE_FLAGS_MASK) // diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 371ab351b..9499f4a79 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -103,11 +103,14 @@ message Span { // field must be empty. The ID is an 8-byte array. bytes parent_span_id = 4; - // Flags from the W3C traceparent, if provided. - // There are two flags defined in the W3C Trace Context Level 2 spec: - // - sampled = 0x1 - // - random = 0x2 - uint32 trace_flags = 16; + // Flags, a bit field. 8 least significant bits are the trace flags as + // defined in W3C Trace Context specification. 24 most significant bits are reserved + // and must be set to 0. Readers must not assume that 24 most significant bits + // will be zero and must correctly mask the bits when reading 8-bit trace flag (use + // flags & SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. + // + // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. + fixed32 flags = 16; // A description of the span's operation. // @@ -243,11 +246,14 @@ message Span { // then no attributes were dropped. uint32 dropped_attributes_count = 5; - // Flags from the linked span's traceparent, if provided. - // There are two flags defined in the W3C Trace Context Level 2 spec: - // - sampled = 0x1 - // - random = 0x2 - uint32 trace_flags = 6; + // Flags, a bit field. 8 least significant bits are the trace flags as + // defined in W3C Trace Context specification. 24 most significant bits are reserved + // and must be set to 0. Readers must not assume that 24 most significant bits + // will be zero and must correctly mask the bits when reading 8-bit trace flag (use + // flags & SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. + // + // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. + fixed32 flags = 6; } // links is a collection of Links, which are references from this span to a span @@ -286,3 +292,23 @@ message Status { // The status code. StatusCode code = 3; } + +// SpanFlags represents constants used to interpret the +// Span.flags field, which is protobuf 'fixed32' type and is to +// be used as bit-fields. Each non-zero value defined in this enum is +// a bit-mask. To extract the bit-field, for example, use an +// expression like: +// +// (span.flags & SPAN_FLAGS_TRACE_FLAGS_MASK) +// +// See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. +enum SpanFlags { + // The zero value for the enum. Should not be used for comparisons. + // Instead use bitwise "and" with the appropriate mask as shown above. + SPAN_FLAGS_DO_NOT_USE = 0; + + // Bits 0-7 are used for trace flags. + SPAN_FLAGS_TRACE_FLAGS_MASK = 0x000000FF; + + // Bits 8-31 are reserved for future use. +} From 5fc27d9462e2939686b1eb4c0a895807aa4c5b5d Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Mon, 21 Aug 2023 11:49:53 -0700 Subject: [PATCH 06/11] comment on new field --- opentelemetry/proto/trace/v1/trace.proto | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 9499f4a79..b8853c877 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -302,6 +302,11 @@ message Status { // (span.flags & SPAN_FLAGS_TRACE_FLAGS_MASK) // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. +// +// Note that Span flags were introduced in version 1.1 of the +// OpenTelemetry protocol. Older Span producers do not set this +// field, consequently consumers should not rely on the absence of a +// particular flag bit to indicate the presence of a particular feature. enum SpanFlags { // The zero value for the enum. Should not be used for comparisons. // Instead use bitwise "and" with the appropriate mask as shown above. From 703950f74478ea722592e9dd76998567a606ff64 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Thu, 24 Aug 2023 08:38:05 -0700 Subject: [PATCH 07/11] new spans should zero 24 bits; use tag 18 --- opentelemetry/proto/trace/v1/trace.proto | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index b8853c877..2e1fbed1d 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -106,11 +106,12 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace flags as // defined in W3C Trace Context specification. 24 most significant bits are reserved // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero and must correctly mask the bits when reading 8-bit trace flag (use - // flags & SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. + // will be zero. When writing new spans, SDKs must set the most-significant 24-bits + // to zero. To read the 8-bit trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). + // [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. - fixed32 flags = 16; + fixed32 flags = 18; // A description of the span's operation. // @@ -249,8 +250,9 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace flags as // defined in W3C Trace Context specification. 24 most significant bits are reserved // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero and must correctly mask the bits when reading 8-bit trace flag (use - // flags & SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. + // will be zero. When writing new spans, SDKs must set the most-significant 24-bits + // to zero. To read the 8-bit trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). + // [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. fixed32 flags = 6; From 8505a5a280ebb0f874d2919fc4644b597c94fc01 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 5 Sep 2023 08:31:12 -0700 Subject: [PATCH 08/11] refine comment --- opentelemetry/proto/trace/v1/trace.proto | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 2e1fbed1d..6ca051717 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -76,7 +76,7 @@ message ScopeSpans { // A Span represents a single operation performed by a single component of the system. // -// The next available field id is 17. +// The next available field id is 19. message Span { // A unique identifier for a trace. All spans from the same trace share // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR @@ -106,8 +106,8 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace flags as // defined in W3C Trace Context specification. 24 most significant bits are reserved // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero. When writing new spans, SDKs must set the most-significant 24-bits - // to zero. To read the 8-bit trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). + // will be zero. When writing new spans, the most-significant 24-bits MUST be + // zero. To read the 8-bit W3C trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). // [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. @@ -250,8 +250,8 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace flags as // defined in W3C Trace Context specification. 24 most significant bits are reserved // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero. When writing new spans, SDKs must set the most-significant 24-bits - // to zero. To read the 8-bit trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). + // will be zero. When writing new spans, the most-significant 24-bits MUST be + // zero. To read the 8-bit W3C trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). // [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. From 42516044129c747b04513b92843227b820b45059 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 5 Sep 2023 08:35:50 -0700 Subject: [PATCH 09/11] merge --- opentelemetry/proto/trace/v1/trace.proto | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index 5d13c1b9e..d6913201f 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -82,7 +82,7 @@ message ScopeSpans { // A Span represents a single operation performed by a single component of the system. // -// The next available field id is 19. +// The next available field id is 17. message Span { // A unique identifier for a trace. All spans from the same trace share // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR @@ -112,12 +112,12 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace flags as // defined in W3C Trace Context specification. 24 most significant bits are reserved // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero. When writing new spans, the most-significant 24-bits MUST be + // will be zero. When creating new spans, the most-significant 24-bits MUST be // zero. To read the 8-bit W3C trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). // [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. - fixed32 flags = 18; + fixed32 flags = 16; // A description of the span's operation. // @@ -256,7 +256,7 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace flags as // defined in W3C Trace Context specification. 24 most significant bits are reserved // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero. When writing new spans, the most-significant 24-bits MUST be + // will be zero. When creating new spans, the most-significant 24-bits MUST be // zero. To read the 8-bit W3C trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). // [Optional]. // From 7b33da248fd77ca873792c951e5baf16bc4a6256 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Tue, 5 Sep 2023 08:38:54 -0700 Subject: [PATCH 10/11] revise --- opentelemetry/proto/trace/v1/trace.proto | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index d6913201f..e36eff688 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -109,12 +109,12 @@ message Span { // field must be empty. The ID is an 8-byte array. bytes parent_span_id = 4; - // Flags, a bit field. 8 least significant bits are the trace flags as - // defined in W3C Trace Context specification. 24 most significant bits are reserved - // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero. When creating new spans, the most-significant 24-bits MUST be - // zero. To read the 8-bit W3C trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). - // [Optional]. + // Flags, a bit field. 8 least significant bits are the trace + // flags as defined in W3C Trace Context specification. Readers + // MUST not assume that 24 most significant bits will be zero. + // When creating new spans, the most-significant 24-bits MUST be + // zero. To read the 8-bit W3C trace flag (use flags & + // SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. fixed32 flags = 16; @@ -253,12 +253,12 @@ message Span { // then no attributes were dropped. uint32 dropped_attributes_count = 5; - // Flags, a bit field. 8 least significant bits are the trace flags as - // defined in W3C Trace Context specification. 24 most significant bits are reserved - // and must be set to 0. Readers must not assume that 24 most significant bits - // will be zero. When creating new spans, the most-significant 24-bits MUST be - // zero. To read the 8-bit W3C trace flag (use flags & SPAN_FLAGS_TRACE_FLAGS_MASK). - // [Optional]. + // Flags, a bit field. 8 least significant bits are the trace + // flags as defined in W3C Trace Context specification. Readers + // MUST not assume that 24 most significant bits will be zero. + // When creating new spans, the most-significant 24-bits MUST be + // zero. To read the 8-bit W3C trace flag (use flags & + // SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. fixed32 flags = 6; From de0b00539055e5d94b2c3d19e63adef3fb815361 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Wed, 13 Sep 2023 07:33:53 -0700 Subject: [PATCH 11/11] Update opentelemetry/proto/trace/v1/trace.proto MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- opentelemetry/proto/trace/v1/trace.proto | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index e36eff688..a1fdfa3ac 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -112,9 +112,15 @@ message Span { // Flags, a bit field. 8 least significant bits are the trace // flags as defined in W3C Trace Context specification. Readers // MUST not assume that 24 most significant bits will be zero. - // When creating new spans, the most-significant 24-bits MUST be - // zero. To read the 8-bit W3C trace flag (use flags & - // SPAN_FLAGS_TRACE_FLAGS_MASK). [Optional]. + // To read the 8-bit W3C trace flag, use `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`. + // + // When creating span messages, if the message is logically forwarded from another source + // with an equivalent flags fields (i.e., usually another OTLP span message), the field SHOULD + // be copied as-is. If creating from a source that does not have an equivalent flags field + // (such as a runtime representation of an OpenTelemetry span), the high 24 bits MUST + // be set to zero. + // + // [Optional]. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. fixed32 flags = 16;