Indicate if a span's parent or link is remote using 2 bit flag as described in OTEP 0182

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
 

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