Clarify what empty instrumentation name means, and missing instrumentation library (#245)

bogdandrutu · yurishkuro · tigrannajaryan · web-flow · commit 286810dc20d4 · 2020-12-08T18:53:11.000-08:00
* Clarify what empty instrumentation name means, and missing instrumentation library

Signed-off-by: Bogdan Drutu &lt;bogdandrutu@gmail.com&gt;

* Update opentelemetry/proto/logs/v1/logs.proto

Co-authored-by: Yuri Shkuro &lt;yurishkuro@users.noreply.github.com&gt;

* Update opentelemetry/proto/logs/v1/logs.proto

Co-authored-by: Yuri Shkuro &lt;yurishkuro@users.noreply.github.com&gt;

* Update opentelemetry/proto/logs/v1/logs.proto

Co-authored-by: Yuri Shkuro &lt;yurishkuro@users.noreply.github.com&gt;

* Update opentelemetry/proto/common/v1/common.proto

Co-authored-by: Tigran Najaryan &lt;4194920+tigrannajaryan@users.noreply.github.com&gt;

* Update common.proto

Co-authored-by: Yuri Shkuro &lt;yurishkuro@users.noreply.github.com&gt;
Co-authored-by: Tigran Najaryan &lt;4194920+tigrannajaryan@users.noreply.github.com&gt;
diff --git a/opentelemetry/proto/common/v1/common.proto b/opentelemetry/proto/common/v1/common.proto
@@ -72,6 +72,7 @@ message StringKeyValue {
 // InstrumentationLibrary is a message representing the instrumentation library information
 // such as the fully qualified name and version. 
 message InstrumentationLibrary {
+  // An empty instrumentation library name means the name is unknown. 
   string name = 1;
   string version = 2;
 }
diff --git a/opentelemetry/proto/logs/v1/logs.proto b/opentelemetry/proto/logs/v1/logs.proto
@@ -26,106 +26,107 @@ option go_package = "github.com/open-telemetry/opentelemetry-proto/gen/go/logs/v
 
 // A collection of InstrumentationLibraryLogs from a Resource.
 message ResourceLogs {
-    // The resource for the logs in this message.
-    // If this field is not set then no resource info is known.
-    opentelemetry.proto.resource.v1.Resource resource = 1;
+  // The resource for the logs in this message.
+  // If this field is not set then resource info is unknown.
+  opentelemetry.proto.resource.v1.Resource resource = 1;
 
-    // A list of InstrumentationLibraryLogs that originate from a resource.
-    repeated InstrumentationLibraryLogs instrumentation_library_logs = 2;
+  // A list of InstrumentationLibraryLogs that originate from a resource.
+  repeated InstrumentationLibraryLogs instrumentation_library_logs = 2;
 }
 
 // A collection of Logs produced by an InstrumentationLibrary.
 message InstrumentationLibraryLogs {
-    // The instrumentation library information for the logs in this message.
-    // If this field is not set then no library info is known.
-    opentelemetry.proto.common.v1.InstrumentationLibrary instrumentation_library = 1;
+  // The instrumentation library information for the logs in this message.
+  // Semantically when InstrumentationLibrary isn't set, it is equivalent with
+  // an empty instrumentation library name (unknown).
+  opentelemetry.proto.common.v1.InstrumentationLibrary instrumentation_library = 1;
 
-    // A list of log records.
-    repeated LogRecord logs = 2;
+  // A list of log records.
+  repeated LogRecord logs = 2;
 }
 
 // Possible values for LogRecord.SeverityNumber.
 enum SeverityNumber {
-    // UNSPECIFIED is the default SeverityNumber, it MUST not be used.
-    SEVERITY_NUMBER_UNSPECIFIED = 0;
-    SEVERITY_NUMBER_TRACE  = 1;
-    SEVERITY_NUMBER_TRACE2 = 2;
-    SEVERITY_NUMBER_TRACE3 = 3;
-    SEVERITY_NUMBER_TRACE4 = 4;
-    SEVERITY_NUMBER_DEBUG  = 5;
-    SEVERITY_NUMBER_DEBUG2 = 6;
-    SEVERITY_NUMBER_DEBUG3 = 7;
-    SEVERITY_NUMBER_DEBUG4 = 8;
-    SEVERITY_NUMBER_INFO   = 9;
-    SEVERITY_NUMBER_INFO2  = 10;
-    SEVERITY_NUMBER_INFO3  = 11;
-    SEVERITY_NUMBER_INFO4  = 12;
-    SEVERITY_NUMBER_WARN   = 13;
-    SEVERITY_NUMBER_WARN2  = 14;
-    SEVERITY_NUMBER_WARN3  = 15;
-    SEVERITY_NUMBER_WARN4  = 16;
-    SEVERITY_NUMBER_ERROR  = 17;
-    SEVERITY_NUMBER_ERROR2 = 18;
-    SEVERITY_NUMBER_ERROR3 = 19;
-    SEVERITY_NUMBER_ERROR4 = 20;
-    SEVERITY_NUMBER_FATAL  = 21;
-    SEVERITY_NUMBER_FATAL2 = 22;
-    SEVERITY_NUMBER_FATAL3 = 23;
-    SEVERITY_NUMBER_FATAL4 = 24;
+  // UNSPECIFIED is the default SeverityNumber, it MUST NOT be used.
+  SEVERITY_NUMBER_UNSPECIFIED = 0;
+  SEVERITY_NUMBER_TRACE  = 1;
+  SEVERITY_NUMBER_TRACE2 = 2;
+  SEVERITY_NUMBER_TRACE3 = 3;
+  SEVERITY_NUMBER_TRACE4 = 4;
+  SEVERITY_NUMBER_DEBUG  = 5;
+  SEVERITY_NUMBER_DEBUG2 = 6;
+  SEVERITY_NUMBER_DEBUG3 = 7;
+  SEVERITY_NUMBER_DEBUG4 = 8;
+  SEVERITY_NUMBER_INFO   = 9;
+  SEVERITY_NUMBER_INFO2  = 10;
+  SEVERITY_NUMBER_INFO3  = 11;
+  SEVERITY_NUMBER_INFO4  = 12;
+  SEVERITY_NUMBER_WARN   = 13;
+  SEVERITY_NUMBER_WARN2  = 14;
+  SEVERITY_NUMBER_WARN3  = 15;
+  SEVERITY_NUMBER_WARN4  = 16;
+  SEVERITY_NUMBER_ERROR  = 17;
+  SEVERITY_NUMBER_ERROR2 = 18;
+  SEVERITY_NUMBER_ERROR3 = 19;
+  SEVERITY_NUMBER_ERROR4 = 20;
+  SEVERITY_NUMBER_FATAL  = 21;
+  SEVERITY_NUMBER_FATAL2 = 22;
+  SEVERITY_NUMBER_FATAL3 = 23;
+  SEVERITY_NUMBER_FATAL4 = 24;
 }
 
 // Masks for LogRecord.flags field.
 enum LogRecordFlags {
-    LOG_RECORD_FLAG_UNSPECIFIED = 0;
-    LOG_RECORD_FLAG_TRACE_FLAGS_MASK = 0x000000FF;
+  LOG_RECORD_FLAG_UNSPECIFIED = 0;
+  LOG_RECORD_FLAG_TRACE_FLAGS_MASK = 0x000000FF;
 }
 
 // A log record according to OpenTelemetry Log Data Model:
 // https://github.com/open-telemetry/oteps/blob/master/text/logs/0097-log-data-model.md
 message LogRecord {
-    // time_unix_nano is the time when the event occurred.
-    // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
-    // Value of 0 indicates unknown or missing timestamp.
-    fixed64 time_unix_nano = 1;
-
-    // Numerical value of the severity, normalized to values described in Log Data Model.
-    // [Optional].
-    SeverityNumber severity_number = 2;
-
-    // The severity text (also known as log level). The original string representation as
-    // it is known at the source. [Optional].
-    string severity_text = 3;
-
-    // Short event identifier that does not contain varying parts. Name describes
-    // what happened (e.g. "ProcessStarted"). Recommended to be no longer than 50
-    // characters. Not guaranteed to be unique in any way. [Optional].
-    string name = 4;
-
-    // A value containing the body of the log record. Can be for example a human-readable
-    // string message (including multi-line) describing the event in a free form or it can
-    // be a structured data composed of arrays and maps of other values. [Optional].
-    opentelemetry.proto.common.v1.AnyValue body = 5;
-
-    // Additional attributes that describe the specific event occurrence. [Optional].
-    repeated opentelemetry.proto.common.v1.KeyValue attributes = 6;
-    uint32 dropped_attributes_count = 7;
-
-    // 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 & TRACE_FLAGS_MASK). [Optional].
-    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].
-    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].
-    bytes span_id = 10;
+  // time_unix_nano is the time when the event occurred.
+  // Value is UNIX Epoch time in nanoseconds since 00:00:00 UTC on 1 January 1970.
+  // Value of 0 indicates unknown or missing timestamp.
+  fixed64 time_unix_nano = 1;
+
+  // Numerical value of the severity, normalized to values described in Log Data Model.
+  // [Optional].
+  SeverityNumber severity_number = 2;
+
+  // The severity text (also known as log level). The original string representation as
+  // it is known at the source. [Optional].
+  string severity_text = 3;
+
+  // Short event identifier that does not contain varying parts. Name describes
+  // what happened (e.g. "ProcessStarted"). Recommended to be no longer than 50
+  // characters. Not guaranteed to be unique in any way. [Optional].
+  string name = 4;
+
+  // A value containing the body of the log record. Can be for example a human-readable
+  // string message (including multi-line) describing the event in a free form or it can
+  // be a structured data composed of arrays and maps of other values. [Optional].
+  opentelemetry.proto.common.v1.AnyValue body = 5;
+
+  // Additional attributes that describe the specific event occurrence. [Optional].
+  repeated opentelemetry.proto.common.v1.KeyValue attributes = 6;
+  uint32 dropped_attributes_count = 7;
+
+  // 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 & TRACE_FLAGS_MASK). [Optional].
+  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].
+  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].
+  bytes span_id = 10;
 }
diff --git a/opentelemetry/proto/metrics/v1/metrics.proto b/opentelemetry/proto/metrics/v1/metrics.proto
@@ -37,7 +37,8 @@ message ResourceMetrics {
 // A collection of Metrics produced by an InstrumentationLibrary.
 message InstrumentationLibraryMetrics {
   // The instrumentation library information for the metrics in this message.
-  // If this field is not set then no library info is known.
+  // Semantically when InstrumentationLibrary isn't set, it is equivalent with
+  // an empty instrumentation library name (unknown).
   opentelemetry.proto.common.v1.InstrumentationLibrary instrumentation_library = 1;
 
   // A list of metrics that originate from an instrumentation library.
diff --git a/opentelemetry/proto/trace/v1/trace.proto b/opentelemetry/proto/trace/v1/trace.proto
@@ -37,7 +37,8 @@ message ResourceSpans {
 // A collection of Spans produced by an InstrumentationLibrary.
 message InstrumentationLibrarySpans {
   // The instrumentation library information for the spans in this message.
-  // If this field is not set then no library info is known.
+  // Semantically when InstrumentationLibrary isn't set, it is equivalent with
+  // an empty instrumentation library name (unknown).
   opentelemetry.proto.common.v1.InstrumentationLibrary instrumentation_library = 1;
 
   // A list of Spans that originate from an instrumentation library.

Original file line number	Diff line number	Diff line change
`@@ -72,6 +72,7 @@ message StringKeyValue {`
`72`	`72`	`// InstrumentationLibrary is a message representing the instrumentation library information`
`73`	`73`	`// such as the fully qualified name and version.`
`74`	`74`	`message InstrumentationLibrary {`
	`75`	`+ // An empty instrumentation library name means the name is unknown.`
`75`	`76`	`string name = 1;`
`76`	`77`	`string version = 2;`
`77`	`78`	`}`