Add W3C-specified trace flags to v1 Span proto

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

@@ -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)
 //

opentelemetry/proto/trace/v1/trace.proto

@@ -103,6 +103,15 @@ 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 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.
   //
   // For example, the name can be a qualified method name or a file name
@@ -236,6 +245,15 @@ 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. 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
@@ -274,3 +292,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.
+}