Merge branch 'main' into http-header-attr-keys

.github/CODEOWNERS

@@ -6,13 +6,13 @@
 #
 # Learn about membership in OpenTelemetry community:
 #  https://github.com/open-telemetry/community/blob/main/community-membership.md
-# 
 #
-# Learn about CODEOWNERS file format: 
-#  https://help.github.com/en/articles/about-code-owners
+#
+# Learn about CODEOWNERS file format:
+#  https://help.github.com/articles/about-code-owners
 #
 
-# Global owners, will be the owners for everything in the repo. Membership is tracked via https://github.com/open-telemetry/community/blob/main/community-members.md 
+# Global owners, will be the owners for everything in the repo. Membership is tracked via https://github.com/open-telemetry/community/blob/main/community-members.md
 *   @open-telemetry/specs-semconv-maintainers @open-telemetry/specs-semconv-approvers
 
 # Schemas and schema file tooling

CHANGELOG.md

@@ -11,9 +11,22 @@ release.
 
 - 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.
+  ([#398](https://github.com/open-telemetry/semantic-conventions/pull/398))
+- BREAKING: Define url.scheme in terms of logical operation in HTTP server semconv.
+  ([#376](https://github.com/open-telemetry/semantic-conventions/pull/376))
+- BREAKING: Change `network.transport` from recommended to opt-in in HTTP semconv.
+  ([#402](https://github.com/open-telemetry/semantic-conventions/pull/402))
+- BREAKING: Change `network.type` from recommended to opt-in in HTTP semconv.
+  ([#410](https://github.com/open-telemetry/semantic-conventions/pull/410))
+- BREAKING: Factor in `X-Forwarded-Host` / `Forwarded` when capturing `server.address` and `server.port`.
+  ([#411](https://github.com/open-telemetry/semantic-conventions/pull/411))
 
 ### Features
 
+- Metric namespaces SHOULD NOT be pluralized.
+  ([#267](https://github.com/open-telemetry/opentelemetry-specification/pull/267))
+
 ### Fixes
 
 - Clarify that `error.type` should be the fully-qualified exception class name
@@ -23,6 +36,10 @@ release.
   ([#401](https://github.com/open-telemetry/semantic-conventions/pull/401))
 - Change `server.port` from recommended to conditionally required on HTTP server semconv.
   ([#399](https://github.com/open-telemetry/semantic-conventions/pull/399))
+- Add cardinality warning about two opt-in HTTP metric attributes to all HTTP metrics.
+  ([#412](https://github.com/open-telemetry/semantic-conventions/pull/412))
+- Remove outdated note about not recording HTTP `server.address` when only IP address available.
+  ([#413](https://github.com/open-telemetry/semantic-conventions/pull/413))
 
 ## v1.22.0 (2023-10-12)
 

docs/attributes-registry/README.md

@@ -14,7 +14,7 @@ The attributes registry is the place where attributes are defined. An attribute
 
 Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context.
 
-A definition of an attribute in the registry does not necessarily imply that the attribute is used in any of the semantic conventions.
+A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions.
 
 If applicable, application developers are encouraged to use existing attributes from this registry. See also [these recommendations][developers recommendations] regarding attribute selection and attribute naming for custom use cases.
 
@@ -28,5 +28,7 @@ All registered attributes are listed by namespace in this registry.
 Currently, the following namespaces exist:
 
 * [HTTP](http.md)
+* [Network](network.md)
+* [URL](url.md)
 
 [developers recommendations]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/attribute-naming.md#recommendations-for-application-developers

docs/attributes-registry/http.md

@@ -16,7 +16,7 @@
 | `http.response.body.size` | int | The size of the response payload body in bytes. This is the number of bytes transferred excluding headers and is often, but not always, present as the [Content-Length](https://www.rfc-editor.org/rfc/rfc9110.html#field.content-length) header. For requests using transport encoding, this should be the compressed size. | `3495` |
 | `http.response.header.<key>` | string[] | HTTP response headers, `<key>` being the normalized HTTP Header name (lowercase), the value being the header values. [4] | `http.response.header.content-type=["application/json"]`; `http.response.header.my-custom-header=["abc", "def"]` |
 | `http.response.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` |
-| `http.route` | string | The matched route (path template in the format used by the respective server framework). See note below [5] | `/users/:userID?`; `{controller}/{action}/{id?}` |
+| `http.route` | string | The matched route, that is, the path template in the format used by the respective server framework. [5] | `/users/:userID?`; `{controller}/{action}/{id?}` |
 
 **[1]:** Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.
 The `User-Agent` header is already captured in the `user_agent.original` attribute. Users MAY explicitly configure instrumentations to capture them even though it is not recommended.

docs/attributes-registry/network.md

@@ -0,0 +1,131 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+# Network
+
+These attributes may be used for any network related operation.
+
+## Network Attributes
+
+<!-- semconv registry.network(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `network.carrier.icc` | string | The ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network. | `DE` |
+| `network.carrier.mcc` | string | The mobile carrier country code. | `310` |
+| `network.carrier.mnc` | string | The mobile carrier network code. | `001` |
+| `network.carrier.name` | string | The name of the mobile carrier. | `sprint` |
+| `network.connection.subtype` | string | This describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection. | `LTE` |
+| `network.connection.type` | string | The internet connection type. | `wifi` |
+| `network.local.address` | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` |
+| `network.local.port` | int | Local port number of the network connection. | `65123` |
+| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` |
+| `network.peer.port` | int | Peer port number of the network connection. | `65123` |
+| `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` |
+| `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` |
+| `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` |
+| `network.type` | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` |
+
+**[1]:** The value SHOULD be normalized to lowercase.
+
+**[2]:** `network.protocol.version` refers to the version of the protocol used and might be different from the protocol client's version. If the HTTP client has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`.
+
+**[3]:** The value SHOULD be normalized to lowercase.
+
+Consider always setting the transport when setting a port number, since
+a port number is ambiguous without knowing the transport. For example
+different processes could be listening on TCP port 12345 and UDP port 12345.
+
+**[4]:** The value SHOULD be normalized to lowercase.
+
+`network.connection.subtype` 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 |
+|---|---|
+| `gprs` | GPRS |
+| `edge` | EDGE |
+| `umts` | UMTS |
+| `cdma` | CDMA |
+| `evdo_0` | EVDO Rel. 0 |
+| `evdo_a` | EVDO Rev. A |
+| `cdma2000_1xrtt` | CDMA2000 1XRTT |
+| `hsdpa` | HSDPA |
+| `hsupa` | HSUPA |
+| `hspa` | HSPA |
+| `iden` | IDEN |
+| `evdo_b` | EVDO Rev. B |
+| `lte` | LTE |
+| `ehrpd` | EHRPD |
+| `hspap` | HSPAP |
+| `gsm` | GSM |
+| `td_scdma` | TD-SCDMA |
+| `iwlan` | IWLAN |
+| `nr` | 5G NR (New Radio) |
+| `nrnsa` | 5G NRNSA (New Radio Non-Standalone) |
+| `lte_ca` | LTE CA |
+
+`network.connection.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 |
+|---|---|
+| `wifi` | wifi |
+| `wired` | wired |
+| `cell` | cell |
+| `unavailable` | unavailable |
+| `unknown` | unknown |
+
+`network.transport` 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 |
+|---|---|
+| `tcp` | TCP |
+| `udp` | UDP |
+| `pipe` | Named or anonymous pipe. |
+| `unix` | Unix domain socket |
+
+`network.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 |
+|---|---|
+| `ipv4` | IPv4 |
+| `ipv6` | IPv6 |
+<!-- endsemconv -->
+
+## Deprecated Network Attributes
+
+<!-- semconv network-deprecated(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `net.host.name` | string | Deprecated, use `server.address`. | `example.com` |
+| `net.host.port` | int | Deprecated, use `server.port`. | `8080` |
+| `net.peer.name` | string | Deprecated, use `server.address` on client spans and `client.address` on server spans. | `example.com` |
+| `net.peer.port` | int | Deprecated, use `server.port` on client spans and `client.port` on server spans. | `8080` |
+| `net.protocol.name` | string | Deprecated, use `network.protocol.name`. | `amqp`; `http`; `mqtt` |
+| `net.protocol.version` | string | Deprecated, use `network.protocol.version`. | `3.1.1` |
+| `net.sock.family` | string | Deprecated, use `network.transport` and `network.type`. | `inet` |
+| `net.sock.host.addr` | string | Deprecated, use `network.local.address`. | `/var/my.sock` |
+| `net.sock.host.port` | int | Deprecated, use `network.local.port`. | `8080` |
+| `net.sock.peer.addr` | string | Deprecated, use `network.peer.address`. | `192.168.0.1` |
+| `net.sock.peer.name` | string | Deprecated, no replacement at this time. | `/var/my.sock` |
+| `net.sock.peer.port` | int | Deprecated, use `network.peer.port`. | `65531` |
+| `net.transport` | string | Deprecated, use `network.transport`. | `ip_tcp` |
+
+`net.sock.family` 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 |
+|---|---|
+| `inet` | IPv4 address |
+| `inet6` | IPv6 address |
+| `unix` | Unix domain socket path |
+
+`net.transport` 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 |
+|---|---|
+| `ip_tcp` | ip_tcp |
+| `ip_udp` | ip_udp |
+| `pipe` | Named or anonymous pipe. |
+| `inproc` | In-process communication. [1] |
+| `other` | Something else (non IP-based). |
+
+**[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case.
+<!-- endsemconv -->

docs/attributes-registry/url.md

@@ -0,0 +1,24 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: URL
+--->
+# URL
+
+## URL Attributes
+
+<!-- semconv registry.url(omit_requirement_level) -->
+| Attribute  | Type | Description  | Examples  |
+|---|---|---|---|
+| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` |
+| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` |
+| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` |
+| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` |
+| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` |
+
+**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless.
+`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`.
+`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes.
+
+**[2]:** When missing, the value is assumed to be `/`
+
+**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it.
+<!-- endsemconv -->

docs/cloudevents/cloudevents-spans.md

@@ -40,7 +40,7 @@ document.
 A CloudEvent can be sent directly from producer to consumer.
 For such a scenario, the traditional parent-child trace model works well.
 However, CloudEvents are also used in distributed systems where an event
-can go through many [hops](<https://en.wikipedia.org/wiki/Hop_(networking)>)
+can go through many [hops](<https://wikipedia.org/wiki/Hop_(networking)>)
 until it reaches a consumer. In this scenario, the traditional parent-child
 trace model is not sufficient to produce a meaningful trace.