Merge branch 'main' into new-profile-signal

CHANGELOG.md

@@ -2,7 +2,33 @@
 
 ## Unreleased
 
-Full list of differences found in [this compare](https://github.com/open-telemetry/opentelemetry-proto/compare/v1.0.0...main).
+Full list of differences found in [this compare](https://github.com/open-telemetry/opentelemetry-proto/compare/v1.1.0...main).
+
+### Added
+
+* Add metric.metadata for supporting additional metadata on metrics
+  [#514](https://github.com/open-telemetry/opentelemetry-proto/pull/514)
+
+### Changed
+
+## 1.1.0 - 2024-01-10
+
+Full list of differences found in [this compare](https://github.com/open-telemetry/opentelemetry-proto/compare/v1.0.0...v1.1.0).
+
+### Added
+
+* 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
+
+* Update and fix OTLP JSON examples. [#516](https://github.com/open-telemetry/opentelemetry-proto/pull/516),
+  [#510](https://github.com/open-telemetry/opentelemetry-proto/pull/510),
+  [#499](https://github.com/open-telemetry/opentelemetry-proto/pull/499)
+* Remove irrelevant comments from metric name field. [#512](https://github.com/open-telemetry/opentelemetry-proto/pull/512)
+* Add comment to explain schema_url fields. [#504](https://github.com/open-telemetry/opentelemetry-proto/pull/504)
 
 ## 1.0.0 - 2023-07-03
 

docs/requirements.md

@@ -84,7 +84,7 @@ Ideally it must also support very fast pass-through mode (when no modifications
 
 The protocol must impose minimal pressure on memory manager, including pass-through scenarios, when deserialized data is short-lived and must be serialized as-is shortly after and when such short-lived data is created and discarded at high frequency (think telemetry data forwarders).
 
-The implementation of telemetry protocol must aim to minimize the number of memory allocations and dealocations performed during serialization and deserialization and aim to minimize the pressure on Garbage Collection (for GC languages).
+The implementation of telemetry protocol must aim to minimize the number of memory allocations and deallocations performed during serialization and deserialization and aim to minimize the pressure on Garbage Collection (for GC languages).
 
 ### Level 7 Load Balancer Friendly
 

docs/specification.md

@@ -5,16 +5,12 @@ aliases:
   - /docs/reference/specification/protocol/otlp
   - /docs/specs/otel/protocol/otlp
 spelling:
-  cSpell:ignore backoff backpressure dealocations errdetails nanos proto reconnections retryable
+  cSpell:ignore backoff backpressure errdetails nanos proto reconnections retryable
 cascade:
   body_class: otel-docs-spec
   github_repo: &repo https://github.com/open-telemetry/opentelemetry-proto
-  github_subdir: docs
-  path_base_for_github_subdir: content/en/docs/specs/otlp/
+  path_base_for_github_subdir: tmp/otlp
   github_project_repo: *repo
-path_base_for_github_subdir:
-  from: content/en/docs/specs/otlp/_index.md
-  to: specification.md
 --->
 
 # OpenTelemetry Protocol Specification

examples/logs.json

@@ -27,8 +27,9 @@
           },
           "logRecords": [
             {
-              "timeUnixNano": 1544712660300000000,
-              "observedTimeUnixNano": 1544712660300000000,
+              "timeUnixNano": "1544712660300000000",
+              "observedTimeUnixNano": "1544712660300000000",
+              "severityNumber": 10,
               "severityText": "Information",
               "traceId": "5B8EFFF798038103D269B633813FC60C",
               "spanId": "EEE19B7EC3C1B174",
@@ -51,7 +52,7 @@
                 {
                   "key": "int.attribute",
                   "value": {
-                    "intValue": 10
+                    "intValue": "10"
                   }
                 },
                 {

examples/metrics.json

@@ -36,8 +36,8 @@
                 "dataPoints": [
                   {
                     "asDouble": 5,
-                    "startTimeUnixNano": 1544712660300000000,
-                    "timeUnixNano": 1544712660300000000,
+                    "startTimeUnixNano": "1544712660300000000",
+                    "timeUnixNano": "1544712660300000000",
                     "attributes": [
                       {
                         "key": "my.counter.attr",
@@ -58,7 +58,7 @@
                 "dataPoints": [
                   {
                     "asDouble": 10,
-                    "timeUnixNano": 1544712660300000000,
+                    "timeUnixNano": "1544712660300000000",
                     "attributes": [
                       {
                         "key": "my.gauge.attr",
@@ -79,14 +79,14 @@
                 "aggregationTemporality": 1,
                 "dataPoints": [
                   {
-                    "startTimeUnixNano": 1544712660300000000,
-                    "timeUnixNano": 1544712660300000000,
-                    "count": 3,
-                    "sum": 3,
-                    "bucketCounts": [1,1,1],
+                    "startTimeUnixNano": "1544712660300000000",
+                    "timeUnixNano": "1544712660300000000",
+                    "count": 2,
+                    "sum": 2,
+                    "bucketCounts": [1,1],
                     "explicitBounds": [1],
-                    "min": 1,
-                    "max": 1,
+                    "min": 0,
+                    "max": 2,
                     "attributes": [
                       {
                         "key": "my.histogram.attr",

examples/trace.json

@@ -31,8 +31,8 @@
               "spanId": "EEE19B7EC3C1B174",
               "parentSpanId": "EEE19B7EC3C1B173",
               "name": "I'm a server span",
-              "startTimeUnixNano": 1544712660000000000,
-              "endTimeUnixNano": 1544712661000000000,
+              "startTimeUnixNano": "1544712660000000000",
+              "endTimeUnixNano": "1544712661000000000",
               "kind": 2,
               "attributes": [
                 {

opentelemetry/proto/logs/v1/logs.proto

@@ -55,6 +55,9 @@ message ResourceLogs {
   // A list of ScopeLogs that originate from a resource.
   repeated ScopeLogs scope_logs = 2;
 
+  // The Schema URL, if known. This is the identifier of the Schema that the resource data
+  // is recorded in. To learn more about Schema URL see
+  // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to the data in the "resource" field. It does not apply
   // to the data in the "scope_logs" field which have their own schema_url field.
   string schema_url = 3;
@@ -70,6 +73,9 @@ message ScopeLogs {
   // A list of log records.
   repeated LogRecord log_records = 2;
 
+  // The Schema URL, if known. This is the identifier of the Schema that the log data
+  // is recorded in. To learn more about Schema URL see
+  // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to all logs in the "logs" field.
   string schema_url = 3;
 }
@@ -104,9 +110,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/metrics/v1/metrics.proto

@@ -55,6 +55,9 @@ message ResourceMetrics {
   // A list of metrics that originate from a resource.
   repeated ScopeMetrics scope_metrics = 2;
 
+  // The Schema URL, if known. This is the identifier of the Schema that the resource data
+  // is recorded in. To learn more about Schema URL see
+  // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to the data in the "resource" field. It does not apply
   // to the data in the "scope_metrics" field which have their own schema_url field.
   string schema_url = 3;
@@ -70,6 +73,9 @@ message ScopeMetrics {
   // A list of metrics that originate from an instrumentation library.
   repeated Metric metrics = 2;
 
+  // The Schema URL, if known. This is the identifier of the Schema that the metric data
+  // is recorded in. To learn more about Schema URL see
+  // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to all metrics in the "metrics" field.
   string schema_url = 3;
 }
@@ -162,7 +168,7 @@ message ScopeMetrics {
 message Metric {
   reserved 4, 6, 8;
 
-  // name of the metric, including its DNS name prefix. It must be unique.
+  // name of the metric.
   string name = 1;
 
   // description of the metric, which can be used in documentation.
@@ -182,6 +188,15 @@ message Metric {
     ExponentialHistogram exponential_histogram = 10;
     Summary summary = 11;
   }
+
+  // Additional metadata attributes that describe the metric. [Optional].
+  // Attributes are non-identifying.
+  // Consumers SHOULD NOT need to be aware of these attributes.
+  // These attributes MAY be used to encode information allowing
+  // for lossless roundtrip translation to / from another data model.
+  // Attribute keys MUST be unique (it is not allowed to have more than one
+  // attribute with the same key).
+  repeated opentelemetry.proto.common.v1.KeyValue metadata = 12;
 }
 
 // Gauge represents the type of a scalar metric that always exports the

opentelemetry/proto/trace/v1/trace.proto

@@ -55,6 +55,9 @@ message ResourceSpans {
   // A list of ScopeSpans that originate from a resource.
   repeated ScopeSpans scope_spans = 2;
 
+  // The Schema URL, if known. This is the identifier of the Schema that the resource data
+  // is recorded in. To learn more about Schema URL see
+  // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to the data in the "resource" field. It does not apply
   // to the data in the "scope_spans" field which have their own schema_url field.
   string schema_url = 3;
@@ -70,6 +73,9 @@ message ScopeSpans {
   // A list of Spans that originate from an instrumentation scope.
   repeated Span spans = 2;
 
+  // The Schema URL, if known. This is the identifier of the Schema that the span data
+  // is recorded in. To learn more about Schema URL see
+  // https://opentelemetry.io/docs/specs/otel/schemas/#schema-url
   // This schema_url applies to all spans and span events in the "spans" field.
   string schema_url = 3;
 }
@@ -103,6 +109,29 @@ message Span {
   // field must be empty. The ID is an 8-byte array.
   bytes parent_span_id = 4;
 
+  // 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) != 0`.
+  // To read whether the span is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
+  //
+  // 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 22 bits MUST
+  // be set to zero.
+  // Readers MUST NOT assume that bits 10-31 (22 most significant bits) will be zero.
+  //
+  // [Optional].
+  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 +265,25 @@ 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.
+    //
+    // 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) != 0`.
+    // To read whether the link is remote, use `(flags & SPAN_FLAGS_CONTEXT_IS_REMOTE_MASK) != 0`.
+    //
+    // 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;
   }
 
   // links is a collection of Links, which are references from this span to a span
@@ -274,3 +322,34 @@ 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 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.
+}