From 2bdeb79c7646d205c3e05322789afe30cb9ebaa8 Mon Sep 17 00:00:00 2001
From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com>
Date: Thu, 26 Jan 2023 19:50:35 -0500
Subject: [PATCH] Clarify behavior for empty/not present/invalid trace_id and
 span_id fields (#442)

Resolves https://github.com/open-telemetry/opentelemetry-specification/issues/3040

This is not a breaking change:

- For Span it now defines more precisely the receiver behavior that was
  previously defined vaguely (e.g. it was unclear what "empty" means for
  bytes field).

- For LogRecord it now defines the receiver behavior that was previously
  unspecified. This ensures that the wording are consistent with what we
  have for the Span.
---
 opentelemetry/proto/logs/v1/logs.proto   | 27 ++++++++++++++++++------
 opentelemetry/proto/trace/v1/trace.proto | 10 +++++----
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/opentelemetry/proto/logs/v1/logs.proto b/opentelemetry/proto/logs/v1/logs.proto
index 9d0e376..69928de 100644
--- a/opentelemetry/proto/logs/v1/logs.proto
+++ b/opentelemetry/proto/logs/v1/logs.proto
@@ -164,14 +164,29 @@ message LogRecord {
   fixed32 flags = 8;
 
   // A unique identifier for a trace. All logs from the same trace share
-  // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes
-  // is considered invalid. Can be set for logs that are part of request processing
-  // and have an assigned trace id. [Optional].
+  // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR
+  // of length other than 16 bytes is considered invalid (empty string in OTLP/JSON
+  // is zero-length and thus is also invalid).
+  //
+  // This field is optional.
+  //
+  // The receivers SHOULD assume that the log record is not associated with a
+  // trace if any of the following is true:
+  //   - the field is not present,
+  //   - the field contains an invalid value.
   bytes trace_id = 9;
 
   // A unique identifier for a span within a trace, assigned when the span
-  // is created. The ID is an 8-byte array. An ID with all zeroes is considered
-  // invalid. Can be set for logs that are part of a particular processing span.
-  // If span_id is present trace_id SHOULD be also present. [Optional].
+  // is created. The ID is an 8-byte array. An ID with all zeroes OR of length
+  // other than 8 bytes is considered invalid (empty string in OTLP/JSON
+  // is zero-length and thus is also invalid).
+  //
+  // This field is optional. If the sender specifies a valid span_id then it SHOULD also
+  // specify a valid trace_id.
+  //
+  // The receivers SHOULD assume that the log record is not associated with a
+  // span if any of the following is true:
+  //   - the field is not present,
+  //   - the field contains an invalid value.
   bytes span_id = 10;
 }
diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto
index 3103fe7..beefc34 100644
--- a/opentelemetry/proto/trace/v1/trace.proto
+++ b/opentelemetry/proto/trace/v1/trace.proto
@@ -79,15 +79,17 @@ message ScopeSpans {
 // 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
-  // is considered invalid.
+  // the same `trace_id`. The ID is a 16-byte array. An ID with all zeroes OR
+  // of length other than 16 bytes is considered invalid (empty string in OTLP/JSON
+  // is zero-length and thus is also invalid).
   //
   // This field is required.
   bytes trace_id = 1;
 
   // A unique identifier for a span within a trace, assigned when the span
-  // is created. The ID is an 8-byte array. An ID with all zeroes is considered
-  // invalid.
+  // is created. The ID is an 8-byte array. An ID with all zeroes OR of length
+  // other than 8 bytes is considered invalid (empty string in OTLP/JSON
+  // is zero-length and thus is also invalid).
   //
   // This field is required.
   bytes span_id = 2;