Merge branch 'main' into messaging_attributes_client_id

.gitignore

@@ -28,3 +28,6 @@ internal/tools/bin
 # Node.js files for tools (e.g. markdown-toc)
 node_modules/
 package-lock.json
+
+# Visual Studio Code
+.vscode

CHANGELOG.md

@@ -13,18 +13,75 @@ release.
 
 ### Metrics
 
+- Add experimental histogram advice API.
+  ([#3216](https://github.com/open-telemetry/opentelemetry-specification/pull/3216))
+
+### Logs
+
+- Clarify parameters for emitting a log record.
+  ([#3345](https://github.com/open-telemetry/opentelemetry-specification/pull/3354))
+
+### Resource
+
+### Semantic Conventions
+
+### Compatibility
+
+### OpenTelemetry Protocol
+
+### SDK Configuration
+
+- Lay initial groundwork for file configuration
+  ([#3360](https://github.com/open-telemetry/opentelemetry-specification/pull/3360))
+
+### Telemetry Schemas
+
+### Common
+
+## v1.20.0 (2023-04-07)
+
+### Context
+
+- No changes.
+
+### Traces
+
+- Clarify required parent information in ReadableSpan. Technically a relaxation,
+  but previously it was easy to overlook certain properties were required.
+  [#3257](https://github.com/open-telemetry/opentelemetry-specification/pull/3257)
+- Remove underspecified and unused Span decorator from Trace SDK.
+  ([#3363](https://github.com/open-telemetry/opentelemetry-specification/pull/3363))
+
+### Metrics
+
 - Clarify that units should use UCUM case sensitive variant.
   ([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306))
+- Recommended non-prefixed units for metric instrument semantic conventions.
+  ([#3312](https://github.com/open-telemetry/opentelemetry-specification/pull/3312))
+- Remove No-Op instrument and Meter creation requirements.
+  ([#3322](https://github.com/open-telemetry/opentelemetry-specification/pull/3322))
+- Fixed attributes requirement level in semantic conventions for hardware metrics
+  ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
 
 ### Logs
 
 - Update log readme "request context" to "trace context".
   ([#3332](https://github.com/open-telemetry/opentelemetry-specification/pull/3332))
 - Remove log readme document status.
   ([#3334](https://github.com/open-telemetry/opentelemetry-specification/pull/3334))
+- Break out compatibility document on recording trace context in non-OTLP Log Format
+  ([#3331](https://github.com/open-telemetry/opentelemetry-specification/pull/3331))
+- Ensure Logs Bridge API doesn't contain SDK implementation details
+  ([#3275](https://github.com/open-telemetry/opentelemetry-specification/pull/3275))
+- Add Log Bridge API artifact naming guidance
+  ([#3346](https://github.com/open-telemetry/opentelemetry-specification/pull/3346))
+- Add log appender / bridge to glossary.
+  ([#3335](https://github.com/open-telemetry/opentelemetry-specification/pull/3335))
 
 ### Resource
 
+- No changes.
+
 ### Semantic Conventions
 
 - Clarify that attribute requirement levels apply to the instrumentation library
@@ -38,18 +95,54 @@ release.
 - Metric requirement levels are now stable
   ([#3271](https://github.com/open-telemetry/opentelemetry-specification/pull/3271))
 - BREAKING: remove `messaging.destination.kind` and `messaging.source.kind`.
-  ([#3214](https://github.com/open-telemetry/opentelemetry-specification/pull/3214))
+  ([#3214](https://github.com/open-telemetry/opentelemetry-specification/pull/3214),
+  [#3348](https://github.com/open-telemetry/opentelemetry-specification/pull/3348))
+- Define attributes collected for `cosmosdb` by Cosmos DB SDK
+  ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
+- Clarify stability requirements of semantic conventions
+  ([#3225](https://github.com/open-telemetry/opentelemetry-specification/pull/3225))
+- BREAKING: Change span statuses for gRPC server spans.
+  ([#3333](https://github.com/open-telemetry/opentelemetry-specification/pull/3333))
+- Stabilize key components of `service.*` and `telemetry.sdk.*` resource
+  semantic conventions.
+  ([#3202](https://github.com/open-telemetry/opentelemetry-specification/pull/3202))
+- Fixed attributes requirement level in semantic conventions for hardware metrics
+  ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258))
+- Added AWS S3 semantic conventions.
+  ([#3251](https://github.com/open-telemetry/opentelemetry-specification/pull/3251))
+- Fix units in the Kafka metric semantic conventions.
+  ([#3300](https://github.com/open-telemetry/opentelemetry-specification/pull/3300))
+- Add Trino to Database specific conventions
+  ([#3347](https://github.com/open-telemetry/opentelemetry-specification/pull/3347))
+- Change `db.statement` to only be collected if there is sanitization.
+  ([#3127](https://github.com/open-telemetry/opentelemetry-specification/pull/3127))
+- BREAKING: Remove `http.status_code` attribute from the
+  `http.server.active_requests` metric.
+  ([#3366](https://github.com/open-telemetry/opentelemetry-specification/pull/3366))
+- Mark attribute requirement levels as stable
+  ([#3368](https://github.com/open-telemetry/opentelemetry-specification/pull/3368))
 
 ### Compatibility
 
+- No changes.
+
 ### OpenTelemetry Protocol
 
+- Declare OTLP stable.
+  ([#3274](https://github.com/open-telemetry/opentelemetry-specification/pull/3274))
+
 ### SDK Configuration
 
+- No changes.
+
 ### Telemetry Schemas
 
+- No changes.
+
 ### Common
 
+- No changes.
+
 ## v1.19.0 (2023-03-06)
 
 ### Context
@@ -112,8 +205,6 @@ release.
   ([#3190](https://github.com/open-telemetry/opentelemetry-specification/pull/3190))
 - Expand the declaration of `pool.name`.
   ([#3050](https://github.com/open-telemetry/opentelemetry-specification/pull/3050))
-- Define attributes collected for `cosmosdb` by Cosmos DB SDK
-  ([#3097](https://github.com/open-telemetry/opentelemetry-specification/pull/3097))
 
 ### Compatibility
 

semantic_conventions/logs/general.yaml

@@ -0,0 +1,19 @@
+groups:
+  - id: log.record
+    prefix: log.record
+    type: attribute_group
+    brief: >
+      The attributes described in this section are rather generic. They may be used in any Log Record they apply to.
+    attributes:
+      - id: uid
+        type: string
+        requirement_level: opt_in
+        brief: >
+          A unique identifier for the Log Record.
+        note: >
+          If an id is provided, other log records with the same id will be considered duplicates and can be removed safely.
+          This means, that two distinguishable log records MUST have different values.
+
+          The id MAY be an [Universally Unique Lexicographically Sortable Identifier (ULID)](https://github.com/ulid/spec),
+          but other identifiers (e.g. UUID) may be used as needed.
+        examples: ["01ARZ3NDEKTSV4RRFFQ69G5FAV"]

semantic_conventions/metrics/http.yaml

@@ -21,7 +21,6 @@ groups:
     unit: "{request}"
     attributes:
       - ref: http.method
-      - ref: http.status_code
       - ref: http.scheme
       - ref: net.host.name
         requirement_level: required

semantic_conventions/resource/faas.yaml

@@ -60,3 +60,4 @@ groups:
           On AWS Lambda, the environment variable `AWS_LAMBDA_FUNCTION_MEMORY_SIZE`
           provides this information (which must be multiplied by 1,048,576).
         examples: 134217728
+      - ref: cloud.resource_id

semantic_conventions/resource/host.yaml

@@ -3,7 +3,7 @@ groups:
     prefix: host
     type: resource
     brief: >
-        A host is defined as a general computing instance.
+        A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array.
     attributes:
       - id: id
         type: string
@@ -62,11 +62,11 @@ groups:
       - id: image.id
         type: string
         brief: >
-          VM image ID. For Cloud, this value is from the provider.
+          VM image ID or host OS image ID. For Cloud, this value is from the provider.
         examples: ['ami-07b06b442921831e5']
       - id: image.version
         type: string
         brief: >
-          The version string of the VM image as defined in
+          The version string of the VM image or host OS as defined in
           [Version Attributes](README.md#version-attributes).
         examples: ['0.1']

semantic_conventions/resource/service.yaml

@@ -16,38 +16,3 @@ groups:
           with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`.
           If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
         examples: ["shoppingcart"]
-      - id: namespace
-        type: string
-        brief: >
-          A namespace for `service.name`.
-        note: >
-          A string value having a meaning that helps to distinguish a group of services,
-          for example the team name that owns a group of services.
-          `service.name` is expected to be unique within the same namespace.
-          If `service.namespace` is not specified in the Resource then `service.name`
-          is expected to be unique for all services that have no explicit namespace defined
-          (so the empty/unspecified namespace is simply one more valid namespace).
-          Zero-length namespace string is assumed equal to unspecified namespace.
-        examples: ["Shop"]
-      - id: instance.id
-        type: string
-        brief: >
-          The string ID of the service instance.
-        note: >
-          MUST be unique for each instance of the same `service.namespace,service.name` pair
-          (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique).
-          The ID helps to distinguish instances of the same service that exist at the same time
-          (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent
-          and stay the same for the lifetime of the service instance, however it is acceptable that
-          the ID is ephemeral and changes during important lifetime events for the service
-          (e.g. service restarts).
-          If the service has no inherent unique ID that can be used as the value of this attribute
-          it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID
-          (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122
-          for more recommendations).
-        examples: ["627cc493-f310-47de-96bd-71410b7dec09"]
-      - id: version
-        type: string
-        brief: >
-          The version string of the service API or implementation.
-        examples: ["2.0.0"]

semantic_conventions/resource/service_experimental.yaml

@@ -0,0 +1,42 @@
+groups:
+  - id: service_experimental
+    prefix: service
+    type: resource
+    brief: >
+      A service instance.
+    attributes:
+      - id: namespace
+        type: string
+        brief: >
+          A namespace for `service.name`.
+        note: >
+          A string value having a meaning that helps to distinguish a group of services,
+          for example the team name that owns a group of services.
+          `service.name` is expected to be unique within the same namespace.
+          If `service.namespace` is not specified in the Resource then `service.name`
+          is expected to be unique for all services that have no explicit namespace defined
+          (so the empty/unspecified namespace is simply one more valid namespace).
+          Zero-length namespace string is assumed equal to unspecified namespace.
+        examples: ["Shop"]
+      - id: instance.id
+        type: string
+        brief: >
+          The string ID of the service instance.
+        note: >
+          MUST be unique for each instance of the same `service.namespace,service.name` pair
+          (in other words `service.namespace,service.name,service.instance.id` triplet MUST be globally unique).
+          The ID helps to distinguish instances of the same service that exist at the same time
+          (e.g. instances of a horizontally scaled service). It is preferable for the ID to be persistent
+          and stay the same for the lifetime of the service instance, however it is acceptable that
+          the ID is ephemeral and changes during important lifetime events for the service
+          (e.g. service restarts).
+          If the service has no inherent unique ID that can be used as the value of this attribute
+          it is recommended to generate a random Version 1 or Version 4 RFC 4122 UUID
+          (services aiming for reproducible UUIDs may also use Version 5, see RFC 4122
+          for more recommendations).
+        examples: ["my-k8s-pod-deployment-1", "627cc493-f310-47de-96bd-71410b7dec09"]
+      - id: version
+        type: string
+        brief: >
+          The version string of the service API or implementation.
+        examples: ["2.0.0"]

semantic_conventions/resource/telemetry.yaml

@@ -7,6 +7,7 @@ groups:
     attributes:
       - id: sdk.name
         type: string
+        requirement_level: required
         brief: >
           The name of the telemetry SDK as defined above.
         examples: ["opentelemetry"]
@@ -36,15 +37,12 @@ groups:
               value: "webjs"
             - id: swift
               value: "swift"
+        requirement_level: required
         brief: >
           The language of the telemetry SDK.
       - id: sdk.version
         type: string
+        requirement_level: required
         brief: >
           The version string of the telemetry SDK.
         examples: ["1.2.3"]
-      - id: auto.version
-        type: string
-        brief: >
-          The version string of the auto instrumentation agent, if used.
-        examples: ["1.2.3"]

semantic_conventions/resource/telemetry_experimental.yaml

@@ -0,0 +1,12 @@
+groups:
+  - id: telemetry_experimental
+    prefix: telemetry
+    type: resource
+    brief: >
+      The telemetry SDK used to capture data recorded by the instrumentation libraries.
+    attributes:
+      - id: auto.version
+        type: string
+        brief: >
+          The version string of the auto instrumentation agent, if used.
+        examples: ["1.2.3"]

semantic_conventions/trace/database.yaml

@@ -166,6 +166,9 @@ groups:
             - id: spanner
               value: 'spanner'
               brief: 'Cloud Spanner'
+            - id: trino
+              value: 'trino'
+              brief: 'Trino'
       - id: connection_string
         tag: connection-level
         type: string
@@ -204,11 +207,10 @@ groups:
         tag: call-level
         type: string
         requirement_level:
-          conditionally_required: >
-            If applicable and not explicitly disabled via instrumentation configuration.
+          recommended: >
+            Should be collected by default only if there is sanitization that excludes sensitive information.
         brief: >
           The database statement being executed.
-        note: The value may be sanitized to exclude sensitive information.
         examples: ['SELECT * FROM wuser_table', 'SET mykey "WuValue"']
       - id: operation
         tag: call-level
@@ -451,6 +453,19 @@ groups:
         requirement_level:
           conditionally_required: when performing one of the operations in this list
       - ref: user_agent.original
+        brief: 'Full user-agent string is generated by Cosmos DB SDK'
+        note: >
+          The user-agent value is generated by SDK which is a combination of<br>
+          `sdk_version` : Current version of SDK. e.g. 'cosmos-netstandard-sdk/3.23.0'<br>
+          `direct_pkg_version` : Direct package version used by Cosmos DB SDK. e.g. '3.23.1'<br>
+          `number_of_client_instances` : Number of cosmos client instances created by the application. e.g. '1'<br>
+          `type_of_machine_architecture` : Machine architecture. e.g. 'X64'<br>
+          `operating_system` : Operating System. e.g. 'Linux 5.4.0-1098-azure 104 18'<br>
+          `runtime_framework` : Runtime Framework. e.g. '.NET Core 3.1.32'<br>
+          `failover_information` : Generated key to determine if region failover enabled.
+             Format Reg-{D (Disabled discovery)}-S(application region)|L(List of preferred regions)|N(None, user did not configure it).
+             Default value is "NS".
+        examples: ['cosmos-netstandard-sdk/3.23.0\|3.23.1\|1\|X64\|Linux 5.4.0-1098-azure 104 18\|.NET Core 3.1.32\|S\|']
       - id: connection_mode
         type:
           allow_custom_values: false

semantic_conventions/trace/general.yaml

@@ -1,5 +1,5 @@
 groups:
-  - id: network
+  - id: network-core
     prefix: net
     type: attribute_group
     brief: >
@@ -108,6 +108,12 @@ groups:
         requirement_level:
           conditionally_required: If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. In other cases, it is still recommended to set this.
         examples: 35555
+  - id: network-connection-and-carrier
+    prefix: net
+    type: attribute_group
+    brief: >
+      These attributes may be used for any network related operation.
+    attributes:
       - id: host.connection.type
         type:
           allow_custom_values: true

semantic_conventions/trace/messaging.yaml

@@ -159,8 +159,6 @@ groups:
       - ref: net.protocol.name
         examples: ['amqp', 'mqtt']
       - ref: net.protocol.version
-    constraints:
-      - include: network
 
   - id: messaging.producer
     prefix: messaging