Merge branch 'main' into add-gcp

CHANGELOG.md

@@ -9,6 +9,29 @@ release.
 
 ### Breaking
 
+- Update `jvm.gc.duration` histogram buckets to `[ 0.01, 0.1, 1, 10 ]`
+  ([#317](https://github.com/open-telemetry/semantic-conventions/pull/317))
+- BREAKING: Change type of `host.cpu.model.id` and `host.cpu.model.family` to string.
+  ([#495](https://github.com/open-telemetry/semantic-conventions/issues/495))
+
+### Features
+
+- Add `code.stacktrace` attribute
+  ([#435](https://github.com/open-telemetry/semantic-conventions/pull/435))
+- Add `http.flavor` and `http.user_agent` to list of deprecated attributes
+  ([#503](https://github.com/open-telemetry/semantic-conventions/pull/503))
+- Add Semantic conventions for TLS/SSL encrypted communication.
+  ([#21](https://github.com/open-telemetry/semantic-conventions/pull/21))
+
+### Fixes
+
+## v1.23.0 (2023-11-03)
+
+This release marks the first where the core of HTTP semantic conventions have
+stabilized.
+
+### Breaking
+
 - BREAKING: Rename http.resend_count to http.request.resend_count.
   ([#374](https://github.com/open-telemetry/semantic-conventions/pull/374))
 - BREAKING: Change `network.protocol.name` from recommended to opt-in in HTTP semconv.
@@ -68,6 +91,8 @@ release.
   ([#409](https://github.com/open-telemetry/semantic-conventions/pull/409))
 - Add `host.mac` resource attribute convention.
   ([#340](https://github.com/open-telemetry/semantic-conventions/pull/340))
+- Mark HTTP semantic conventions as stable.
+  ([#377](https://github.com/open-telemetry/semantic-conventions/pull/377))
 
 ### Fixes
 
@@ -87,6 +112,7 @@ release.
 - Change the precedence between `:authority` and `Host` headers when populating
   `server.address` and `server.port` attributes.
   ([#455](https://github.com/open-telemetry/semantic-conventions/pull/455))
+- Explain `deployment.environment` impact on service identity. ([#481](https://github.com/open-telemetry/semantic-conventions/pull/481))
 
 ## v1.22.0 (2023-10-12)
 

Makefile

@@ -90,13 +90,13 @@ yamllint:
 .PHONY: table-generation
 table-generation:
 	docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \
-		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec
+		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-use-badges --md-stable
 
 # Check if current markdown tables differ from the ones that would be generated from YAML definitions
 .PHONY: table-check
 table-check:
 	docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec \
-		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check
+		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check --md-use-badges --md-stable
 
 .PHONY: schema-check
 schema-check:

docs/attributes-registry/README.md

@@ -27,14 +27,24 @@ All registered attributes are listed by namespace in this registry.
 
 Currently, the following namespaces exist:
 
+* [Client](client.md)
 * [Cloud](cloud.md)
 * [Code](code.md)
 * [Container](container.md)
+* [Destination](destination.md)
+* [Device](device.md)
+* [Error](error.md)
+* [Host](host.md)
 * [HTTP](http.md)
 * [Network](network.md)
 * [OCI](oci.md)
+* [OS](os.md)
+* [Process](process.md)
 * [RPC](rpc.md)
+* [Server](server.md)
+* [Source](source.md)
 * [Thread](thread.md)
+* [TLS](tls.md)
 * [URL](url.md)
 * [User agent](user-agent.md)
 

docs/attributes-registry/client.md

@@ -0,0 +1,23 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Client
+--->
+
+# Client Attributes
+
+These attributes may be used to describe the client in a connection-based network interaction
+where there is one side that initiates the connection (the client is the side that initiates the connection).
+This covers all TCP network interactions since TCP is connection-based and one side initiates the
+connection (an exception is made for peer-to-peer communication over TCP where the "user-facing" surface of the
+protocol / API does not expose a clear notion of client and server).
+This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.
+
+<!-- semconv client(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `client.address` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` |
+| `client.port` | int | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Client port number. [2] | `65123` |
+
+**[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries,  for example proxies, if it's available.
+
+**[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries,  for example proxies, if it's available.
+<!-- endsemconv -->

docs/attributes-registry/code.md

@@ -15,4 +15,5 @@ These attributes allow to report this unit of code and therefore to provide more
 | `code.function` | string | The method or function name, or equivalent (usually rightmost part of the code unit's name). | `serveRequest` |
 | `code.lineno` | int | The line number in `code.filepath` best representing the operation. It SHOULD point within the code unit named in `code.function`. | `42` |
 | `code.namespace` | string | The "namespace" within which `code.function` is defined. Usually the qualified class or module name, such that `code.namespace` + some separator + `code.function` form a unique identifier for the code unit. | `com.example.MyHttpService` |
+| `code.stacktrace` | string | A stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG. | `at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)` |
 <!-- endsemconv -->

docs/attributes-registry/destination.md

@@ -0,0 +1,21 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Destination
+--->
+
+# Destination Attributes
+
+These attributes may be used to describe the receiver of a network exchange/packet. These should be used
+when there is no client/server relationship between the two sides, or when that relationship is unknown.
+This covers low-level network interactions (e.g. packet tracing) where you don't know if
+there was a connection or which side initiated it.
+This also covers unidirectional UDP flows and peer-to-peer communication where the
+"user-facing" surface of the protocol / API does not expose a clear notion of client and server.
+
+<!-- semconv destination(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `destination.address` | string | Destination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1] | `destination.example.com`; `10.1.2.80`; `/tmp/my.sock` |
+| `destination.port` | int | Destination port number | `3389`; `2888` |
+
+**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries, for example proxies, if it's available.
+<!-- endsemconv -->

docs/attributes-registry/device.md

@@ -0,0 +1,23 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Device
+
+## Device Attributes
+
+<!-- semconv registry.device(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` |
+| `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` |
+| `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` |
+| `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` |
+
+**[1]:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
+
+**[2]:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.
+
+**[3]:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.
+
+**[4]:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.
+<!-- endsemconv -->

docs/attributes-registry/error.md

@@ -0,0 +1,34 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Error
+
+## Error Attributes
+
+<!-- semconv registry.error(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `error.type` | string | ![Stable](https://img.shields.io/badge/-stable-lightgreen)<br>Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` |
+
+**[1]:** The `error.type` SHOULD be predictable and SHOULD have low cardinality.
+Instrumentations SHOULD document the list of errors they report.
+
+The cardinality of `error.type` within one instrumentation library SHOULD be low.
+Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
+should be prepared for `error.type` to have high cardinality at query time when no
+additional filters are applied.
+
+If the operation has completed successfully, instrumentations SHOULD NOT set `error.type`.
+
+If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes),
+it's RECOMMENDED to:
+
+* Use a domain-specific attribute
+* Set `error.type` to capture all errors, regardless of whether they are defined within the domain-specific set or not.
+
+`error.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |
+<!-- endsemconv -->

docs/attributes-registry/host.md

@@ -0,0 +1,44 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+# Host
+
+## Host Attributes
+
+<!-- semconv registry.host(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `host.arch` | string | The CPU architecture the host system is running on. | `amd64` |
+| `host.cpu.cache.l2.size` | int | The amount of level 2 memory cache available to the processor (in Bytes). | `12288000` |
+| `host.cpu.family` | string | Family or generation of the CPU. | `6`; `PA-RISC 1.1e` |
+| `host.cpu.model.id` | string | Model identifier. It provides more granular information about the CPU, distinguishing it from other CPUs within the same family. | `6`; `9000/778/B180L` |
+| `host.cpu.model.name` | string | Model designation of the processor. | `11th Gen Intel(R) Core(TM) i7-1185G7 @ 3.00GHz` |
+| `host.cpu.stepping` | int | Stepping or core revisions. | `1` |
+| `host.cpu.vendor.id` | string | Processor manufacturer identifier. A maximum 12-character string. [1] | `GenuineIntel` |
+| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` |
+| `host.image.id` | string | VM image ID or host OS image ID. For Cloud, this value is from the provider. | `ami-07b06b442921831e5` |
+| `host.image.name` | string | Name of the VM image or OS install the host was instantiated from. | `infra-ami-eks-worker-node-7d4ec78312`; `CentOS-8-x86_64-1905` |
+| `host.image.version` | string | The version string of the VM image or host OS as defined in [Version Attributes](/docs/resource/README.md#version-attributes). | `0.1` |
+| `host.ip` | string[] | Available IP addresses of the host, excluding loopback interfaces. [2] | `[192.168.1.140, fe80::abc2:4a28:737a:609e]` |
+| `host.mac` | string[] | Available MAC addresses of the host, excluding loopback interfaces. [3] | `[AC-DE-48-23-45-67, AC-DE-48-23-45-67-01-9F]` |
+| `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` |
+| `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` |
+
+**[1]:** [CPUID](https://wiki.osdev.org/CPUID) command returns the vendor ID string in EBX, EDX and ECX registers. Writing these to memory in this order results in a 12-character string.
+
+**[2]:** IPv4 Addresses MUST be specified in dotted-quad notation. IPv6 addresses MUST be specified in the [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952.html) format.
+
+**[3]:** MAC Addresses MUST be represented in [IEEE RA hexadecimal form](https://standards.ieee.org/wp-content/uploads/import/documents/tutorials/eui.pdf): as hyphen-separated octets in uppercase hexadecimal form from most to least significant.
+
+`host.arch` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+
+| Value  | Description |
+|---|---|
+| `amd64` | AMD64 |
+| `arm32` | ARM32 |
+| `arm64` | ARM64 |
+| `ia64` | Itanium |
+| `ppc32` | 32-bit PowerPC |
+| `ppc64` | 64-bit PowerPC |
+| `s390x` | IBM z/Architecture |
+| `x86` | 32-bit x86 |
+<!-- endsemconv -->