diff --git a/CHANGELOG.md b/CHANGELOG.md index ab793a015..f5d257a8d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,8 +10,10 @@ Full list of differences found in [this compare](https://github.com/open-telemet ### Added -* Add `flags` field to `Span` and `Span/Link` for W3C-specified Trace Context flags . +* Add `flags` field to `Span` and `Span/Link` for W3C-specified Trace Context flags. [#503](https://github.com/open-telemetry/opentelemetry-proto/pull/503) +* Indicate if a `Span`'s parent or link is remote using 2 bit flag. + [#484](https://github.com/open-telemetry/opentelemetry-proto/pull/484) ### Changed diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto index a1fdfa3ac..2fa5b9fbd 100644 --- a/opentelemetry/proto/trace/v1/trace.proto +++ b/opentelemetry/proto/trace/v1/trace.proto @@ -109,20 +109,27 @@ 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. Readers - // MUST not assume that 24 most significant bits will be zero. - // To read the 8-bit W3C trace flag, use `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`. + // Flags, a bit field. + // + // Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace + // Context specification. To read the 8-bit W3C trace flag, use + // `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`. + // + // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. + // + // Bits 8 and 9 represent the 3 states of whether a span's parent + // is remote. The states are (unknown, is not remote, is remote). + // To read whether the value is known, use `flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK`. + // To read whether the span is remote, use `flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_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 + // (such as a runtime representation of an OpenTelemetry span), the high 22 bits MUST // be set to zero. + // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero. // // [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. @@ -259,14 +266,23 @@ 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. 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. + // + // Bits 0-7 (8 least significant bits) are the trace flags as defined in W3C Trace + // Context specification. To read the 8-bit W3C trace flag, use + // `flags & SPAN_FLAGS_TRACE_FLAGS_MASK`. // // See https://www.w3.org/TR/trace-context-2/#trace-flags for the flag definitions. + // + // Bits 8 and 9 represent the 3 states of whether the link is remote. + // The states are (unknown, is not remote, is remote). + // To read whether the value is known, use `flags & SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK`. + // To read whether the link is remote, use `flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK`. + // + // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero. + // When creating new spans, bits 10-31 (most-significant 22-bits) MUST be zero. + // + // [Optional]. fixed32 flags = 6; } @@ -329,5 +345,11 @@ enum SpanFlags { // Bits 0-7 are used for trace flags. SPAN_FLAGS_TRACE_FLAGS_MASK = 0x000000FF; - // Bits 8-31 are reserved for future use. + // Bits 8 and 9 are used to indicate that the parent span or link span is remote. + // Bit 8 (`HAS_IS_REMOTE`) indicates whether the value is known. + // Bit 9 (`IS_REMOTE`) indicates whether the span or link is remote. + SPAN_FLAGS_CONTEXT_HAS_IS_REMOTE_MASK = 0x00000100; + SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK = 0x00000200; + + // Bits 10-31 are reserved for future use. }