Add W3C-specified trace flags to v1 Span proto (open-telemetry#503)

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).

opentelemetry/proto/logs/v1/logs.proto

@@ -110,9 +110,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)
 //

opentelemetry/proto/trace/v1/trace.proto

@@ -109,6 +109,22 @@ 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`.
+  //
+  // 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;
+
   // A description of the span's operation.
   //
   // For example, the name can be a qualified method name or a file name
@@ -242,6 +258,16 @@ 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, 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;
   }
 
   // links is a collection of Links, which are references from this span to a span
@@ -280,3 +306,28 @@ 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.
+//
+// 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.
+  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.
+}