Rename InstrumentationLibrary to InstrumentationScope (#362)

This applies changes described in spec PR open-telemetry/opentelemetry-specification#2276

This is not a breaking change for OTLP. The wire format does not change.

The change is done in a way that the transition can be handled gracefully for OTLP/JSON and for the generated code. See the comments for explanation on how to do it in the senders and receivers.

opentelemetry/proto/common/v1/common.proto

@@ -66,9 +66,22 @@ message KeyValue {
 }
 
 // InstrumentationLibrary is a message representing the instrumentation library information
-// such as the fully qualified name and version. 
+// such as the fully qualified name and version.
+// InstrumentationLibrary is wire-compatible with InstrumentationScope for binary
+// Protobuf format.
+// This message is deprecated and will be removed on June 15, 2022.
 message InstrumentationLibrary {
-  // An empty instrumentation library name means the name is unknown. 
+  option deprecated = true;
+
+  // An empty instrumentation library name means the name is unknown.
+  string name = 1;
+  string version = 2;
+}
+
+// InstrumentationScope is a message representing the instrumentation scope information
+// such as the fully qualified name and version. 
+message InstrumentationScope {
+  // An empty instrumentation scope name means the name is unknown.
   string name = 1;
   string version = 2;
 }

opentelemetry/proto/logs/v1/logs.proto

@@ -43,29 +43,76 @@ message LogsData {
   repeated ResourceLogs resource_logs = 1;
 }
 
-// A collection of InstrumentationLibraryLogs from a Resource.
+// A collection of ScopeLogs from a Resource.
 message ResourceLogs {
   // 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 ScopeLogs that originate from a resource.
+  repeated ScopeLogs scope_logs = 2;
+
   // A list of InstrumentationLibraryLogs that originate from a resource.
-  repeated InstrumentationLibraryLogs instrumentation_library_logs = 2;
+  // This field is deprecated and will be removed after grace period expires on June 15, 2022.
+  //
+  // During the grace period the following rules SHOULD be followed:
+  //
+  // For Binary Protobufs
+  // ====================
+  // Binary Protobuf senders SHOULD NOT set instrumentation_library_logs. Instead
+  // scope_logs SHOULD be set.
+  //
+  // Binary Protobuf receivers SHOULD check if instrumentation_library_logs is set
+  // and scope_logs is not set then the value in instrumentation_library_logs
+  // SHOULD be used instead by converting InstrumentationLibraryLogs into ScopeLogs.
+  // If scope_logs is set then instrumentation_library_logs SHOULD be ignored.
+  //
+  // For JSON
+  // ========
+  // JSON senders that set instrumentation_library_logs field MAY also set
+  // scope_logs to carry the same logs, essentially double-publishing the same data.
+  // Such double-publishing MAY be controlled by a user-settable option.
+  // If double-publishing is not used then the senders SHOULD set scope_logs and
+  // SHOULD NOT set instrumentation_library_logs.
+  //
+  // JSON receivers SHOULD check if instrumentation_library_logs is set and
+  // scope_logs is not set then the value in instrumentation_library_logs
+  // SHOULD be used instead by converting InstrumentationLibraryLogs into ScopeLogs.
+  // If scope_logs is set then instrumentation_library_logs field SHOULD be ignored.
+  repeated InstrumentationLibraryLogs instrumentation_library_logs = 1000 [deprecated = true];
 
   // This schema_url applies to the data in the "resource" field. It does not apply
-  // to the data in the "instrumentation_library_logs" field which have their own
-  // schema_url field.
+  // to the data in the "scope_logs" field which have their own schema_url field.
+  string schema_url = 3;
+}
+
+// A collection of Logs produced by a Scope.
+message ScopeLogs {
+  // The instrumentation scope information for the logs in this message.
+  // Semantically when InstrumentationScope isn't set, it is equivalent with
+  // an empty instrumentation scope name (unknown).
+  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
+
+  // A list of log records.
+  repeated LogRecord log_records = 2;
+
+  // This schema_url applies to all logs in the "logs" field.
   string schema_url = 3;
 }
 
 // A collection of Logs produced by an InstrumentationLibrary.
+// InstrumentationLibraryLogs is wire-compatible with ScopeLogs for binary
+// Protobuf format.
+// This message is deprecated and will be removed on June 15, 2022.
 message InstrumentationLibraryLogs {
+  option deprecated = true;
+
   // 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.
+  // A list of logs that originate from an instrumentation library.
   repeated LogRecord log_records = 2;
 
   // This schema_url applies to all logs in the "logs" field.

opentelemetry/proto/metrics/v1/metrics.proto

@@ -43,23 +43,70 @@ message MetricsData {
   repeated ResourceMetrics resource_metrics = 1;
 }
 
-// A collection of InstrumentationLibraryMetrics from a Resource.
+// A collection of ScopeMetrics from a Resource.
 message ResourceMetrics {
   // The resource for the metrics in this message.
   // If this field is not set then no resource info is known.
   opentelemetry.proto.resource.v1.Resource resource = 1;
 
   // A list of metrics that originate from a resource.
-  repeated InstrumentationLibraryMetrics instrumentation_library_metrics = 2;
+  repeated ScopeMetrics scope_metrics = 2;
+
+  // A list of InstrumentationLibraryMetrics that originate from a resource.
+  // This field is deprecated and will be removed after grace period expires on June 15, 2022.
+  //
+  // During the grace period the following rules SHOULD be followed:
+  //
+  // For Binary Protobufs
+  // ====================
+  // Binary Protobuf senders SHOULD NOT set instrumentation_library_metrics. Instead
+  // scope_metrics SHOULD be set.
+  //
+  // Binary Protobuf receivers SHOULD check if instrumentation_library_metrics is set
+  // and scope_metrics is not set then the value in instrumentation_library_metrics
+  // SHOULD be used instead by converting InstrumentationLibraryMetrics into ScopeMetrics.
+  // If scope_metrics is set then instrumentation_library_metrics SHOULD be ignored.
+  //
+  // For JSON
+  // ========
+  // JSON senders that set instrumentation_library_metrics field MAY also set
+  // scope_metrics to carry the same metrics, essentially double-publishing the same data.
+  // Such double-publishing MAY be controlled by a user-settable option.
+  // If double-publishing is not used then the senders SHOULD set scope_metrics and
+  // SHOULD NOT set instrumentation_library_metrics.
+  //
+  // JSON receivers SHOULD check if instrumentation_library_metrics is set and
+  // scope_metrics is not set then the value in instrumentation_library_metrics
+  // SHOULD be used instead by converting InstrumentationLibraryMetrics into ScopeMetrics.
+  // If scope_metrics is set then instrumentation_library_metrics field SHOULD be ignored.
+  repeated InstrumentationLibraryMetrics instrumentation_library_metrics = 1000 [deprecated = true];
 
   // This schema_url applies to the data in the "resource" field. It does not apply
-  // to the data in the "instrumentation_library_metrics" field which have their own
-  // schema_url field.
+  // to the data in the "scope_metrics" field which have their own schema_url field.
+  string schema_url = 3;
+}
+
+// A collection of Metrics produced by an Scope.
+message ScopeMetrics {
+  // The instrumentation scope information for the metrics in this message.
+  // Semantically when InstrumentationScope isn't set, it is equivalent with
+  // an empty instrumentation scope name (unknown).
+  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
+
+  // A list of metrics that originate from an instrumentation library.
+  repeated Metric metrics = 2;
+
+  // This schema_url applies to all metrics in the "metrics" field.
   string schema_url = 3;
 }
 
 // A collection of Metrics produced by an InstrumentationLibrary.
+// InstrumentationLibraryMetrics is wire-compatible with ScopeMetrics for binary
+// Protobuf format.
+// This message is deprecated and will be removed on June 15, 2022.
 message InstrumentationLibraryMetrics {
+  option deprecated = true;
+
   // The instrumentation library information for the metrics in this message.
   // Semantically when InstrumentationLibrary isn't set, it is equivalent with
   // an empty instrumentation library name (unknown).

opentelemetry/proto/trace/v1/trace.proto

@@ -43,23 +43,70 @@ message TracesData {
   repeated ResourceSpans resource_spans = 1;
 }
 
-// A collection of InstrumentationLibrarySpans from a Resource.
+// A collection of ScopeSpans from a Resource.
 message ResourceSpans {
   // The resource for the spans in this message.
   // If this field is not set then no resource info is known.
   opentelemetry.proto.resource.v1.Resource resource = 1;
 
+  // A list of ScopeSpans that originate from a resource.
+  repeated ScopeSpans scope_spans = 2;
+
   // A list of InstrumentationLibrarySpans that originate from a resource.
-  repeated InstrumentationLibrarySpans instrumentation_library_spans = 2;
+  // This field is deprecated and will be removed after grace period expires on June 15, 2022.
+  //
+  // During the grace period the following rules SHOULD be followed:
+  //
+  // For Binary Protobufs
+  // ====================
+  // Binary Protobuf senders SHOULD NOT set instrumentation_library_spans. Instead
+  // scope_spans SHOULD be set.
+  //
+  // Binary Protobuf receivers SHOULD check if instrumentation_library_spans is set
+  // and scope_spans is not set then the value in instrumentation_library_spans
+  // SHOULD be used instead by converting InstrumentationLibrarySpans into ScopeSpans.
+  // If scope_spans is set then instrumentation_library_spans SHOULD be ignored.
+  //
+  // For JSON
+  // ========
+  // JSON senders that set instrumentation_library_spans field MAY also set
+  // scope_spans to carry the same spans, essentially double-publishing the same data.
+  // Such double-publishing MAY be controlled by a user-settable option.
+  // If double-publishing is not used then the senders SHOULD set scope_spans and
+  // SHOULD NOT set instrumentation_library_spans.
+  //
+  // JSON receivers SHOULD check if instrumentation_library_spans is set and
+  // scope_spans is not set then the value in instrumentation_library_spans
+  // SHOULD be used instead by converting InstrumentationLibrarySpans into ScopeSpans.
+  // If scope_spans is set then instrumentation_library_spans field SHOULD be ignored.
+  repeated InstrumentationLibrarySpans instrumentation_library_spans = 1000 [deprecated = true];
 
   // This schema_url applies to the data in the "resource" field. It does not apply
-  // to the data in the "instrumentation_library_spans" field which have their own
-  // schema_url field.
+  // to the data in the "scope_spans" field which have their own schema_url field.
+  string schema_url = 3;
+}
+
+// A collection of Spans produced by an InstrumentationScope.
+message ScopeSpans {
+  // The instrumentation scope information for the spans in this message.
+  // Semantically when InstrumentationScope isn't set, it is equivalent with
+  // an empty instrumentation scope name (unknown).
+  opentelemetry.proto.common.v1.InstrumentationScope scope = 1;
+
+  // A list of Spans that originate from an instrumentation scope.
+  repeated Span spans = 2;
+
+  // This schema_url applies to all spans and span events in the "spans" field.
   string schema_url = 3;
 }
 
 // A collection of Spans produced by an InstrumentationLibrary.
+// InstrumentationLibrarySpans is wire-compatible with ScopeSpans for binary
+// Protobuf format.
+// This message is deprecated and will be removed on June 15, 2022.
 message InstrumentationLibrarySpans {
+  option deprecated = true;
+
   // The instrumentation library information for the spans in this message.
   // Semantically when InstrumentationLibrary isn't set, it is equivalent with
   // an empty instrumentation library name (unknown).