diff --git a/CHANGELOG.md b/CHANGELOG.md index d823481daa..3563762c3a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -136,6 +136,9 @@ release. ([#366](https://github.com/open-telemetry/semantic-conventions/pull/366)) - Add `host.ip` resource attribute convention. ([#203](https://github.com/open-telemetry/semantic-conventions/pull/203)) +- BREAKING: Rename/replace `(client|server).socket.(address|port)` attributes + with `network.(peer|local).(address|port)`. + ([#342](https://github.com/open-telemetry/semantic-conventions/pull/342)) ## v1.21.0 (2023-07-13) diff --git a/docs/database/database-spans.md b/docs/database/database-spans.md index 05314a27fd..a767dce76a 100644 --- a/docs/database/database-spans.md +++ b/docs/database/database-spans.md @@ -67,12 +67,12 @@ Some database systems may allow a connection to switch to a different `db.user`, | `db.connection_string` | string | The connection string used to connect to the database. It is recommended to remove embedded credentials. | `Server=(localdb)\v11.0;Integrated Security=true;` | Recommended | | `db.system` | string | An identifier for the database management system (DBMS) product being used. See below for a list of well-known identifiers. | `other_sql` | Required | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [1] | `tcp`; `udp` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [2] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the database host. [3] | `example.com` | Conditionally Required: See alternative attributes below. | -| [`server.port`](../general/attributes.md) | int | Server port number [4] | `80`; `8080`; `443` | Conditionally Required: [5] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [6] | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [7] | `16456` | Recommended: If different than `server.port`. | +| [`server.address`](../general/attributes.md) | string | Name of the database host. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [4] | `80`; `8080`; `443` | Conditionally Required: [5] | **[1]:** The value SHOULD be normalized to lowercase. @@ -89,17 +89,6 @@ the server address behind any intermediaries (e.g. proxies) if it's available. **[5]:** If using a port other than the default port for this DBMS and if `server.address` is set. -**[6]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - -**[7]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* [`server.address`](../general/attributes.md) -* [`server.socket.address`](../general/attributes.md) - `db.system` 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 | diff --git a/docs/database/elasticsearch.md b/docs/database/elasticsearch.md index d62e6cd7ee..9bbddc5663 100644 --- a/docs/database/elasticsearch.md +++ b/docs/database/elasticsearch.md @@ -32,8 +32,8 @@ If the endpoint id is not available, the span name SHOULD be the `http.request.m | [`db.operation`](database-spans.md) | string | The endpoint identifier for the request. [4] | `search`; `ml.close_job`; `cat.aliases` | Required | | [`db.statement`](database-spans.md) | string | The request body for a [search-type query](https://www.elastic.co/guide/en/elasticsearch/reference/current/search.html), as a json string. | `"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"` | Recommended: [5] | | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [6] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Name of the database host. [7] | `example.com` | Conditionally Required: See alternative attributes below. | -| [`server.port`](../general/attributes.md) | int | Server port number [8] | `80`; `8080`; `443` | Conditionally Required: [9] | +| [`server.address`](../general/attributes.md) | string | Name of the database host. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [8] | `80`; `8080`; `443` | Conditionally Required: [9] | | [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [10] | `https://localhost:9200/index/_search?q=user.id:kimchy` | Required | **[1]:** When communicating with an Elastic Cloud deployment, this should be collected from the "X-Found-Handling-Cluster" HTTP response header. diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 6111990606..542a74878d 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -19,13 +19,16 @@ Particular operations may refer to or require some of these attributes. * [Address and port attributes](#address-and-port-attributes) * [Server attributes](#server-attributes) + [`server.address`](#serveraddress) - + [`server.socket.*` attributes](#serversocket-attributes) * [Client attributes](#client-attributes) - + [Connecting through intermediary](#connecting-through-intermediary) * [Source and destination attributes](#source-and-destination-attributes) + [Source](#source) + [Destination](#destination) * [Other network attributes](#other-network-attributes) + + [`network.peer.*` and `network.local.*` attributes](#networkpeer-and-networklocal-attributes) + - [Client/server examples using `network.peer.*`](#clientserver-examples-using--networkpeer) + * [Simple client/server example](#simple-clientserver-example) + * [Client/server example with reverse proxy](#clientserver-example-with-reverse-proxy) + * [Client/server example with forward proxy](#clientserver-example-with-forward-proxy) + [Network connection and carrier attributes](#network-connection-and-carrier-attributes) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) @@ -66,31 +69,18 @@ if they do not cause breaking changes to HTTP semantic conventions. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com` | Recommended | -| `server.port` | int | Server port number [2] | `80`; `8080`; `443` | Recommended | -| `server.socket.address` | string | Server address of the socket connection - IP address or Unix domain socket name. [3] | `10.5.3.2` | Recommended: If different than `server.address`. | -| `server.socket.domain` | string | Immediate server peer's domain name if available without reverse DNS lookup [4] | `proxy.example.com` | Recommended: If different than `server.address`. | -| `server.socket.port` | int | Server port number of the socket connection. [5] | `16456` | Recommended: If different than `server.port`. | +| `server.address` | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `server.port` | int | Server port number. [2] | `80`; `8080`; `443` | Recommended | **[1]:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. **[2]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. - -**[3]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - -**[4]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. `server.address` and `server.port` represent logical server name and port. Semantic conventions that refer to these attributes SHOULD specify what these attributes mean in their context. -Semantic conventions and instrumentations that populate both logical (`server.address` and `server.port`) and socket-level (`server.socket.*`) attributes SHOULD set socket-level attributes only when they don't match logical ones. For example, when direct connection to the remote destination is established and `server.address` is populated, `server.socket.domain` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information. - #### `server.address` For IP-based communication, the name should be a DNS host name of the service. On client side it matches remote service name, on server side, it represents local service name as seen externally on clients. @@ -107,28 +97,6 @@ the name should explicitly be set to the empty string to distinguish it from the For Unix domain socket, `server.address` attribute represents remote endpoint address on the client side and local endpoint address on the server side. -#### `server.socket.*` attributes - -_Note: this section applies to socket connections visible to instrumentations. Instrumentations have limited knowledge about intermediaries communications goes through such as [transparent proxies](https://www.rfc-editor.org/rfc/rfc3040.html#section-2.5) or VPN servers. Higher-level instrumentations such as HTTP don't always have access to the socket-level information and may not be able to populate socket-level attributes._ - -Socket-level attributes identify peer and host that are directly connected to each other. Since instrumentations may have limited knowledge on network information, instrumentations SHOULD populate such attributes to the best of their knowledge when populate them at all. - -_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._ - -For IP-based communication, `server.socket.domain` represents either fully qualified domain name of immediate peer and `server.socket.address` to the IP address (or one specific to network family). - -`server.socket.domain`, `server.socket.address`, and `server.socket.port` describe server side of socket communication. For example, when connecting using `connect(2)` -on [Linux](https://man7.org/linux/man-pages/man2/connect.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect) -with `AF_INET` address family, they represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure. - -On client side, address and port can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html) or -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername). - -On server side address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html) or -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). - -`server.socket.port` SHOULD only be populated for families that have notion of port. - ### Client attributes > **Warning** @@ -139,53 +107,14 @@ if they do not cause breaking changes to HTTP semantic conventions. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `client.address` | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | +| `client.address` | string | 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` | Recommended | | `client.port` | int | Client port number. [2] | `65123` | Recommended | -| `client.socket.address` | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| `client.socket.port` | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | **[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. 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 (e.g. proxies) if it's available. - -**[3]:** When observed from the server side, this SHOULD represent the immediate client peer address. -When observed from the client side, this SHOULD represent the physical client address. - -**[4]:** When observed from the server side, this SHOULD represent the immediate client peer port. -When observed from the client side, this SHOULD represent the physical client port. -`client.socket.address` and `client.socket.port` represent physical client name and port. - -For IP-based communication, the `client.socket.address` should be a IP address, Unix domain name, or another address specific to network type. - -On server side, `client.socket.address` identifies the direct peer endpoint socket address. For example, when using `bind(2)` -on [Linux](https://man7.org/linux/man-pages/man2/bind.2.html) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind) -with `AF_INET` address family, represent `sin_addr` and `sin_port` fields of `sockaddr_in` structure. - -On client side it represents local socket address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html), -[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). - -#### Connecting through intermediary - -When connecting to the remote destination through an intermediary (e.g. proxy), client instrumentations SHOULD set `server.address` and `server.port` to logical remote destination address and `server.socket.name`, `server.socket.address` and `server.socket.port` to the socket peer connection is established with - the intermediary. - -`server.socket.domain` SHOULD be set to the DNS name used to resolve `server.socket.address` if it's readily available. Instrumentations -SHOULD NOT do DNS lookups to obtain `server.socket.address`. If peer information available to instrumentation -can represent DNS name or IP address, instrumentation SHOULD NOT attempt to parse it and SHOULD only set `server.socket.domain`. - -_Note: Telemetry consumers can obtain IP address from telemetry item by first checking `server.socket.address` and if not present, falling back to `server.socket.domain`._ - -For example, [URL Host component](https://www.rfc-editor.org/rfc/rfc3986#section-3.2.2) can contain IP address or DNS name and -instrumentations that don't have access to socket-level communication can only populate `server.socket.domain`. -Instrumentations that have access to socket connection, may be able to populate valid `server.socket.address` instead of or -in addition to DNS name. - -Server instrumentations that leverage `client.address` and `client.port` attributes SHOULD set them to originating client address and port behind all proxies if this information is available. -The `client.socket.address` and `client.socket.port` attributes then SHOULD contain immediate client peer address and port. - -If only immediate peer information is available, it should be set on `client.address` and `client.port` and `client.socket.*` attributes SHOULD NOT be set. - ### Source and destination attributes These attributes may be used to describe the sender and receiver of a network exchange/packet. These should be used @@ -200,11 +129,10 @@ This also covers unidirectional UDP flows and peer-to-peer communication where t | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `source.address` | string | Source address, for example IP address or Unix socket name. | `10.5.3.2` | Recommended | -| `source.domain` | string | The domain name of the source system. [1] | `foo.example.com` | Recommended | +| `source.address` | string | Source address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `source.example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | | `source.port` | int | Source port number | `3389`; `2888` | Recommended | -**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. +**[1]:** When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent the source address behind any intermediaries (e.g. proxies) if it's available. #### Destination @@ -214,11 +142,10 @@ Destination fields capture details about the receiver of a network exchange/pack | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `destination.address` | string | Destination address, for example IP address or UNIX socket name. | `10.5.3.2` | Recommended | -| `destination.domain` | string | The domain name of the destination system. [1] | `foo.example.com` | Recommended | +| `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` | Recommended | | `destination.port` | int | Destination port number | `3389`; `2888` | Recommended | -**[1]:** This value may be a host name, a fully qualified domain name, or another host naming format. +**[1]:** When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent the destination address behind any intermediaries (e.g. proxies) if it's available. @@ -233,6 +160,10 @@ if they do not cause breaking changes to HTTP semantic conventions. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| +| `network.local.address` | string | Local address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `network.local.port` | int | Local port number of the network connection. | `65123` | Recommended | +| `network.peer.address` | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| `network.peer.port` | int | Peer port number of the network connection. | `65123` | Recommended | | `network.protocol.name` | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [1] | `amqp`; `http`; `mqtt` | Recommended | | `network.protocol.version` | string | Version of the protocol specified in `network.protocol.name`. [2] | `3.1.1` | Recommended | | `network.transport` | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | @@ -267,6 +198,45 @@ different processes could be listening on TCP port 12345 and UDP port 12345. | `ipv6` | IPv6 | +#### `network.peer.*` and `network.local.*` attributes + +These attributes identify network peers that are directly connected to each other. + +`network.peer.address` and `network.local.address` should be IP addresses, Unix domain socket names, or other addresses specific to network type. + +_Note: Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use Socket API provided by their environment or sockets implementations._ + +When connecting using `connect(2)` ([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/connect.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-connect)) +or `bind(2)`([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/bind.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-bind)) +with `AF_INET` address family, `network.peer.address` and `network.peer.port` represent `sin_addr` and `sin_port` fields +of `sockaddr_in` structure. + +`network.peer.address` and `network.peer.port` can be obtained by calling `getpeername` method +([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/getpeername.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername)). + +`network.local.address` and `network.local.port` can be obtained by calling `getsockname` method +([Linux or other POSIX systems](https://man7.org/linux/man-pages/man2/getsockname.2.html) / +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname)). + +##### Client/server examples using `network.peer.*` + +Note that `network.local.*` attributes are not included in these examples since they are typically Opt-In. + +###### Simple client/server example + +![simple.png](simple.png) + +###### Client/server example with reverse proxy + +![reverse-proxy.png](reverse-proxy.png) + +###### Client/server example with forward proxy + +![forward-proxy.png](forward-proxy.png) + #### Network connection and carrier attributes diff --git a/docs/general/forward-proxy.png b/docs/general/forward-proxy.png new file mode 100644 index 0000000000..0badc4624c Binary files /dev/null and b/docs/general/forward-proxy.png differ diff --git a/docs/general/reverse-proxy.png b/docs/general/reverse-proxy.png new file mode 100644 index 0000000000..2f21f817d8 Binary files /dev/null and b/docs/general/reverse-proxy.png differ diff --git a/docs/general/simple.png b/docs/general/simple.png new file mode 100644 index 0000000000..b8c48b0748 Binary files /dev/null and b/docs/general/simple.png differ diff --git a/docs/http/http-metrics.md b/docs/http/http-metrics.md index 78c40f8e6c..0227a4d713 100644 --- a/docs/http/http-metrics.md +++ b/docs/http/http-metrics.md @@ -82,7 +82,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | @@ -179,7 +179,7 @@ This metric is optional. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.request.method`](../attributes-registry/http.md) | string | HTTP request method. [1] | `GET`; `POST`; `HEAD` | Required | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com` | Opt-In | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [3] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | @@ -254,7 +254,7 @@ This metric is optional. | [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | @@ -358,7 +358,7 @@ This metric is optional. | [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [4] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [5] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Opt-In | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Opt-In | | [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Opt-In | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | @@ -467,7 +467,7 @@ of `[ 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | @@ -562,7 +562,7 @@ This metric is optional. | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | @@ -657,7 +657,7 @@ This metric is optional. | [`http.response.status_code`](../attributes-registry/http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Conditionally Required: If and only if one was received/sent. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [3] | `amqp`; `http`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [4] | `3.1.1` | Recommended | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com` | Required | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [6] | `80`; `8080`; `443` | Conditionally Required: [7] | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Required | diff --git a/docs/http/http-spans.md b/docs/http/http-spans.md index 6a24aaaa93..9ed59f4f33 100644 --- a/docs/http/http-spans.md +++ b/docs/http/http-spans.md @@ -244,12 +244,11 @@ For an HTTP client span, `SpanKind` MUST be `Client`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`http.resend_count`](../attributes-registry/http.md) | int | The ordinal number of request resending attempt (for any reason, including redirects). [1] | `3` | Recommended: if and only if request was retried. | -| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com` | Required | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`server.address`](../general/attributes.md) | string | Host identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [2] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | | [`server.port`](../general/attributes.md) | int | Port identifier of the ["URI origin"](https://www.rfc-editor.org/rfc/rfc9110.html#name-uri-origin) HTTP request is sent to. [3] | `80`; `8080`; `443` | Conditionally Required: [4] | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [5] | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [6] | `proxy.example.com` | Recommended: If different than `server.address`. | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [7] | `16456` | Recommended: If different than `server.port`. | -| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [8] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | +| [`url.full`](../url/url.md) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [5] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Required | **[1]:** The resend count SHOULD be updated each time an HTTP request gets resent by the client, regardless of what was the cause of the resending (e.g. redirection, authorization failure, 503 Server Unavailable, network issues, or any other). @@ -266,15 +265,7 @@ If an HTTP client request is explicitly made to an IP address, e.g. `http://x.x. **[4]:** If not default (`80` for `http` scheme, `443` for `https`). -**[5]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - -**[6]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[7]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. - -**[8]:** 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. +**[5]:** 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. @@ -377,31 +368,25 @@ For an HTTP server span, `SpanKind` MUST be `Server`. |---|---|---|---|---| | [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `83.164.160.102` | Recommended | | [`client.port`](../general/attributes.md) | int | The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. [2] | `65123` | Recommended | -| [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | -| [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [5] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | -| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [6] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [7] | `80`; `8080`; `443` | Recommended: [8] | -| [`server.socket.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. [9] | `10.5.3.2` | Opt-In | -| [`server.socket.port`](../general/attributes.md) | int | Local socket port. Useful in case of a multi-port host. [10] | `16456` | Opt-In | -| [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [11] | `/search` | Required | -| [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [12] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | +| [`http.route`](../attributes-registry/http.md) | string | The matched route (path template in the format used by the respective server framework). See note below [3] | `/users/:userID?`; `{controller}/{action}/{id?}` | Conditionally Required: If and only if it's available | +| [`network.local.address`](../general/attributes.md) | string | Local socket address. Useful in case of a multi-IP host. | `10.1.2.80`; `/tmp/my.sock` | Opt-In | +| [`network.local.port`](../general/attributes.md) | int | Local socket port. Useful in case of a multi-port host. | `65123` | Opt-In | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended | +| [`server.address`](../general/attributes.md) | string | Name of the local HTTP server that received the request. [4] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Port of the local HTTP server that received the request. [5] | `80`; `8080`; `443` | Recommended: [6] | +| [`url.path`](../url/url.md) | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [7] | `/search` | Required | +| [`url.query`](../url/url.md) | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [8] | `q=OpenTelemetry` | Conditionally Required: If and only if one was received/sent. | | [`url.scheme`](../url/url.md) | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `http`; `https` | Required | **[1]:** The IP address of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded), [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), or a similar header). Otherwise, the immediate client peer address. **[2]:** When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries (e.g. proxies) if it's available. -**[3]:** When observed from the server side, this SHOULD represent the immediate client peer address. -When observed from the client side, this SHOULD represent the physical client address. - -**[4]:** When observed from the server side, this SHOULD represent the immediate client peer port. -When observed from the client side, this SHOULD represent the physical client port. - -**[5]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. +**[3]:** MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it. SHOULD include the [application root](/docs/http/http-spans.md#http-server-definitions) if there is one. -**[6]:** Determined by using the first of the following that applies +**[4]:** Determined by using the first of the following that applies - The [primary server name](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only include host identifier. @@ -411,24 +396,18 @@ SHOULD include the [application root](/docs/http/http-spans.md#http-server-defin SHOULD NOT be set if only IP address is available and capturing name would require a reverse DNS lookup. -**[7]:** Determined by using the first of the following that applies +**[5]:** Determined by using the first of the following that applies - Port identifier of the [primary server host](/docs/http/http-spans.md#http-server-definitions) of the matched virtual host. - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header -**[8]:** If not default (`80` for `http` scheme, `443` for `https`). - -**[9]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - -**[10]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. +**[6]:** If not default (`80` for `http` scheme, `443` for `https`). -**[11]:** When missing, the value is assumed to be `/` +**[7]:** When missing, the value is assumed to be `/` -**[12]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. +**[8]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: diff --git a/docs/messaging/messaging-spans.md b/docs/messaging/messaging-spans.md index 8faceefe39..15fef2213e 100644 --- a/docs/messaging/messaging-spans.md +++ b/docs/messaging/messaging-spans.md @@ -229,14 +229,13 @@ The following operations related to messages are defined for these semantic conv | `messaging.message.id` | string | A value used by the messaging system as an identifier for the message, represented as a string. | `452a7c7c7c7048c2f887f61572b18fc2` | Recommended: [14] | | `messaging.operation` | string | A string identifying the kind of messaging operation as defined in the [Operation names](#operation-names) section above. [15] | `publish` | Required | | `messaging.system` | string | A string identifying the messaging system. | `kafka`; `rabbitmq`; `rocketmq`; `activemq`; `AmazonSQS` | Required | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | | [`network.protocol.name`](../general/attributes.md) | string | [OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent. [16] | `amqp`; `mqtt` | Recommended | | [`network.protocol.version`](../general/attributes.md) | string | Version of the protocol specified in `network.protocol.name`. [17] | `3.1.1` | Recommended | | [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [18] | `tcp`; `udp` | Recommended | | [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [19] | `ipv4`; `ipv6` | Recommended | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [20] | `example.com` | Conditionally Required: If available. | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [21] | `10.5.3.2` | Recommended: If different than `server.address`. | -| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [22] | `proxy.example.com` | Recommended: [23] | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [24] | `16456` | Recommended: If different than `server.port`. | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [20] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Conditionally Required: If available. | **[1]:** Instrumentations SHOULD NOT set `messaging.batch.message_count` on spans that operate with a single message. When a messaging client library supports both batch and single-message API for the same operation, instrumentations SHOULD use `messaging.batch.message_count` for batching APIs and SHOULD NOT use it for single-message APIs. @@ -285,16 +284,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **[20]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[21]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - -**[22]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[23]:** If different than `server.address` and if `server.socket.address` is set. - -**[24]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. - `messaging.operation` 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 | diff --git a/docs/rpc/rpc-metrics.md b/docs/rpc/rpc-metrics.md index ac07909f79..b7b51580ee 100644 --- a/docs/rpc/rpc-metrics.md +++ b/docs/rpc/rpc-metrics.md @@ -225,8 +225,8 @@ measurements. | [`rpc.method`](rpc-spans.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | [`rpc.service`](rpc-spans.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | | [`rpc.system`](rpc-spans.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com` | Recommended | -| [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Recommended | +| [`server.address`](../general/attributes.md) | string | Server address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Recommended | +| [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Recommended | **[1]:** The value SHOULD be normalized to lowercase. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 98d753e20f..e5d8fbb1fb 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -90,10 +90,8 @@ Examples of span names: | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [3] | `exampleMethod` | Recommended | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [4] | `myservice.EchoService` | Recommended | | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | -| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com` | Required | -| [`server.port`](../general/attributes.md) | int | Server port number [6] | `80`; `8080`; `443` | Conditionally Required: See below | -| [`server.socket.address`](../general/attributes.md) | string | Server address of the socket connection - IP address or Unix domain socket name. [7] | `10.5.3.2` | See below | -| [`server.socket.port`](../general/attributes.md) | int | Server port number of the socket connection. [8] | `16456` | Recommended: [9] | +| [`server.address`](../general/attributes.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | Required | +| [`server.port`](../general/attributes.md) | int | Server port number. [6] | `80`; `8080`; `443` | Conditionally Required: See below | **[1]:** The value SHOULD be normalized to lowercase. @@ -111,19 +109,6 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **[6]:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. -**[7]:** When observed from the client side, this SHOULD represent the immediate server peer address. -When observed from the server side, this SHOULD represent the physical server address. - -**[8]:** When observed from the client side, this SHOULD represent the immediate server peer port. -When observed from the server side, this SHOULD represent the physical server port. - -**[9]:** If different than `server.port` and if `server.socket.address` is set. - -**Additional attribute requirements:** At least one of the following sets of attributes is required: - -* [`server.socket.address`](../general/attributes.md) -* [`server.address`](../general/attributes.md) - `rpc.system` 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 | @@ -157,11 +142,8 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`server.socket.domain`](../general/attributes.md) | string | Immediate server peer's domain name if available without reverse DNS lookup [1] | `proxy.example.com` | Recommended: [2] | - -**[1]:** Typically observed from the client side, and represents a proxy or other intermediary domain name. - -**[2]:** If different than `server.address` and if `server.socket.address` is set. +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `server.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | ### Server attributes @@ -169,30 +151,24 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`client.address`](../general/attributes.md) | string | Client address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. [1] | `/tmp/my.sock`; `10.1.2.80` | Recommended | +| [`client.address`](../general/attributes.md) | string | 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` | Recommended | | [`client.port`](../general/attributes.md) | int | Client port number. [2] | `65123` | Recommended | -| [`client.socket.address`](../general/attributes.md) | string | Client address of the socket connection - IP address or Unix domain socket name. [3] | `/tmp/my.sock`; `127.0.0.1` | Recommended: If different than `client.address`. | -| [`client.socket.port`](../general/attributes.md) | int | Client port number of the socket connection. [4] | `35555` | Recommended: If different than `client.port`. | -| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [5] | `tcp`; `udp` | Recommended | -| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [6] | `ipv4`; `ipv6` | Recommended | +| [`network.peer.address`](../general/attributes.md) | string | Peer address of the network connection - IP address or Unix domain socket name. | `10.1.2.80`; `/tmp/my.sock` | Recommended: If different than `client.address`. | +| [`network.peer.port`](../general/attributes.md) | int | Peer port number of the network connection. | `65123` | Recommended: If `network.peer.address` is set. | +| [`network.transport`](../general/attributes.md) | string | [OSI transport layer](https://osi-model.com/transport-layer/) or [inter-process communication method](https://en.wikipedia.org/wiki/Inter-process_communication). [3] | `tcp`; `udp` | Recommended | +| [`network.type`](../general/attributes.md) | string | [OSI network layer](https://osi-model.com/network-layer/) or non-OSI equivalent. [4] | `ipv4`; `ipv6` | Recommended | **[1]:** When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. 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 (e.g. proxies) if it's available. -**[3]:** When observed from the server side, this SHOULD represent the immediate client peer address. -When observed from the client side, this SHOULD represent the physical client address. - -**[4]:** When observed from the server side, this SHOULD represent the immediate client peer port. -When observed from the client side, this SHOULD represent the physical client port. - -**[5]:** The value SHOULD be normalized to lowercase. +**[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. -**[6]:** The value SHOULD be normalized to lowercase. +**[4]:** The value SHOULD be normalized to lowercase. ### Events diff --git a/model/client.yaml b/model/client.yaml index d1d9502183..71d285f7dc 100644 --- a/model/client.yaml +++ b/model/client.yaml @@ -16,7 +16,7 @@ groups: note: > When observed from the server side, and when communicating through an intermediary, `client.address` SHOULD represent the client address behind any intermediaries (e.g. proxies) if it's available. - examples: ['/tmp/my.sock', '10.1.2.80'] + examples: ['client.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int brief: Client port number. @@ -24,23 +24,3 @@ groups: note: > When observed from the server side, and when communicating through an intermediary, `client.port` SHOULD represent the client port behind any intermediaries (e.g. proxies) if it's available. - - id: socket.address - type: string - brief: Client address of the socket connection - IP address or Unix domain socket name. - note: > - When observed from the server side, this SHOULD represent the immediate client peer address. - - When observed from the client side, this SHOULD represent the physical client address. - examples: ['/tmp/my.sock', '127.0.0.1'] - requirement_level: - recommended: If different than `client.address`. - - id: socket.port - type: int - brief: Client port number of the socket connection. - note: > - When observed from the server side, this SHOULD represent the immediate client peer port. - - When observed from the client side, this SHOULD represent the physical client port. - examples: [35555] - requirement_level: - recommended: If different than `client.port`. diff --git a/model/deprecated/network.yaml b/model/deprecated/network.yaml index 17b75b90e3..19e9c22667 100644 --- a/model/deprecated/network.yaml +++ b/model/deprecated/network.yaml @@ -8,19 +8,18 @@ groups: - id: sock.peer.name type: string stability: deprecated - brief: Deprecated, use `server.socket.domain` on client spans. + brief: Deprecated, no replacement at this time. examples: ['/var/my.sock'] - id: sock.peer.addr type: string stability: deprecated - brief: > - Deprecated, use `server.socket.address` on client spans and `client.socket.address` on server spans. + brief: Deprecated, use `network.peer.address`. examples: ['192.168.0.1'] - id: sock.peer.port type: int stability: deprecated examples: [65531] - brief: Deprecated, use `server.socket.port` on client spans and `client.socket.port` on server spans. + brief: Deprecated, use `network.peer.port`. - id: peer.name type: string stability: deprecated @@ -44,12 +43,12 @@ groups: - id: sock.host.addr type: string stability: deprecated - brief: Deprecated, use `server.socket.address`. + brief: Deprecated, use `network.local.address`. examples: ['/var/my.sock'] - id: sock.host.port type: int stability: deprecated - brief: Deprecated, use `server.socket.port`. + brief: Deprecated, use `network.local.port`. examples: [8080] - id: transport type: diff --git a/model/destination.yaml b/model/destination.yaml index a2fd8fd65f..bad57d5a22 100644 --- a/model/destination.yaml +++ b/model/destination.yaml @@ -9,15 +9,13 @@ groups: 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. attributes: - - id: domain - type: string - brief: The domain name of the destination system. - examples: ['foo.example.com'] - note: This value may be a host name, a fully qualified domain name, or another host naming format. - id: address type: string - brief: 'Destination address, for example IP address or UNIX socket name.' - examples: ['10.5.3.2'] + brief: Destination address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + note: > + When observed from the source side, and when communicating through an intermediary, `destination.address` SHOULD represent + the destination address behind any intermediaries (e.g. proxies) if it's available. + examples: ['destination.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int brief: 'Destination port number' diff --git a/model/network.yaml b/model/network.yaml index 2b969ea36e..2652a2fd1b 100644 --- a/model/network.yaml +++ b/model/network.yaml @@ -57,6 +57,22 @@ groups: `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 used has a version of `0.27.2`, but sends HTTP version `1.1`, this attribute should be set to `1.1`. + - id: peer.address + type: string + brief: Peer address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: peer.port + type: int + brief: Peer port number of the network connection. + examples: [65123] + - id: local.address + type: string + brief: Local address of the network connection - IP address or Unix domain socket name. + examples: ['10.1.2.80', '/tmp/my.sock'] + - id: local.port + type: int + brief: Local port number of the network connection. + examples: [65123] - id: network-connection-and-carrier prefix: network diff --git a/model/server.yaml b/model/server.yaml index aed9184905..8f10470221 100644 --- a/model/server.yaml +++ b/model/server.yaml @@ -16,38 +16,11 @@ groups: note: | When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries (e.g. proxies) if it's available. - examples: ['example.com'] + examples: ['example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int - brief: Server port number + brief: Server port number. note: > When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries (e.g. proxies) if it's available. examples: [80, 8080, 443] - - id: socket.domain - type: string - brief: Immediate server peer's domain name if available without reverse DNS lookup - examples: ['proxy.example.com'] - note: Typically observed from the client side, and represents a proxy or other intermediary domain name. - requirement_level: - recommended: If different than `server.address`. - - id: socket.address - type: string - brief: Server address of the socket connection - IP address or Unix domain socket name. - note: > - When observed from the client side, this SHOULD represent the immediate server peer address. - - When observed from the server side, this SHOULD represent the physical server address. - examples: ['10.5.3.2'] - requirement_level: - recommended: If different than `server.address`. - - id: socket.port - type: int - brief: Server port number of the socket connection. - note: > - When observed from the client side, this SHOULD represent the immediate server peer port. - - When observed from the server side, this SHOULD represent the physical server port. - examples: [16456] - requirement_level: - recommended: If different than `server.port`. diff --git a/model/source.yaml b/model/source.yaml index 63fc1bd4b6..9c0aa30a28 100644 --- a/model/source.yaml +++ b/model/source.yaml @@ -9,15 +9,13 @@ groups: 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. attributes: - - id: domain - type: string - brief: The domain name of the source system. - examples: ['foo.example.com'] - note: This value may be a host name, a fully qualified domain name, or another host naming format. - id: address type: string - brief: 'Source address, for example IP address or Unix socket name.' - examples: ['10.5.3.2'] + brief: Source address - domain name if available without reverse DNS lookup, otherwise IP address or Unix domain socket name. + note: > + When observed from the destination side, and when communicating through an intermediary, `source.address` SHOULD represent + the source address behind any intermediaries (e.g. proxies) if it's available. + examples: ['source.example.com', '10.1.2.80', '/tmp/my.sock'] - id: port type: int brief: 'Source port number' diff --git a/model/trace/database.yaml b/model/trace/database.yaml index aeb68fc6af..e7e1659505 100644 --- a/model/trace/database.yaml +++ b/model/trace/database.yaml @@ -230,29 +230,24 @@ groups: examples: ['findAndModify', 'HMSET', 'SELECT'] - ref: server.address tag: connection-level - requirement_level: - conditionally_required: See alternative attributes below. brief: > Name of the database host. - ref: server.port tag: connection-level requirement_level: conditionally_required: If using a port other than the default port for this DBMS and if `server.address` is set. - - ref: server.socket.address + - ref: network.peer.address + requirement_level: + recommended: If different than `server.address`. tag: connection-level - - ref: server.socket.port + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. tag: connection-level - ref: network.transport tag: connection-level - ref: network.type tag: connection-level - - ref: server.socket.domain - requirement_level: - recommended: If different than `server.address` and if `server.socket.address` is set. - constraints: - - any_of: - - 'server.address' - - 'server.socket.address' - id: db.mssql prefix: db.mssql diff --git a/model/trace/http.yaml b/model/trace/http.yaml index 935827cdf9..dd224b7bb5 100644 --- a/model/trace/http.yaml +++ b/model/trace/http.yaml @@ -57,9 +57,12 @@ groups: note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `server.port` MUST match URI port identifier, otherwise it MUST match `Host` header port identifier. - - ref: server.socket.domain - - ref: server.socket.address - - ref: server.socket.port + - ref: network.peer.address + requirement_level: + recommended: If different than `server.address`. + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. - ref: url.full sampling_relevant: true requirement_level: required @@ -99,10 +102,10 @@ groups: - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) if it's sent in absolute-form. - Port identifier of the `Host` header - - ref: server.socket.address + - ref: network.local.address requirement_level: opt_in brief: Local socket address. Useful in case of a multi-IP host. - - ref: server.socket.port + - ref: network.local.port requirement_level: opt_in brief: Local socket port. Useful in case of a multi-port host. - ref: client.address @@ -117,8 +120,8 @@ groups: The port of the original client behind all proxies, if known (e.g. from [Forwarded](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Forwarded) or a similar header). Otherwise, the immediate client peer port. - - ref: client.socket.address - - ref: client.socket.port + - ref: network.peer.address + - ref: network.peer.port - ref: url.path requirement_level: required sampling_relevant: true diff --git a/model/trace/messaging.yaml b/model/trace/messaging.yaml index 19c8f375ed..3313d95f55 100644 --- a/model/trace/messaging.yaml +++ b/model/trace/messaging.yaml @@ -173,18 +173,18 @@ groups: This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. requirement_level: conditionally_required: If available. - - ref: server.socket.address + - ref: network.peer.address + requirement_level: + recommended: If different than `server.address`. tag: connection-level - - ref: server.socket.port + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. tag: connection-level - ref: network.transport tag: connection-level - ref: network.type tag: connection-level - - ref: server.socket.domain - tag: connection-level - requirement_level: - recommended: If different than `server.address` and if `server.socket.address` is set. - ref: network.protocol.name examples: ['amqp', 'mqtt'] - ref: network.protocol.version diff --git a/model/trace/rpc.yaml b/model/trace/rpc.yaml index 38a25016e0..8cee3efc39 100644 --- a/model/trace/rpc.yaml +++ b/model/trace/rpc.yaml @@ -49,10 +49,6 @@ groups: (e.g., method actually executing the call on the server side, RPC client stub method on the client side). examples: "exampleMethod" - - ref: server.socket.address - - ref: server.socket.port - requirement_level: - recommended: If different than `server.port` and if `server.socket.address` is set. - ref: network.transport - ref: network.type - ref: server.address @@ -66,19 +62,18 @@ groups: - ref: server.port requirement_level: conditionally_required: See below - constraints: - - any_of: - - server.socket.address - - server.address - id: rpc.client type: span brief: 'This document defines semantic conventions for remote procedure call client spans.' extends: rpc attributes: - - ref: server.socket.domain + - ref: network.peer.address + requirement_level: + recommended: If different than `server.address`. + - ref: network.peer.port requirement_level: - recommended: If different than `server.address` and if `server.socket.address` is set. + recommended: If `network.peer.address` is set. - id: rpc.server prefix: rpc @@ -89,8 +84,12 @@ groups: attributes: - ref: client.address - ref: client.port - - ref: client.socket.address - - ref: client.socket.port + - ref: network.peer.address + requirement_level: + recommended: If different than `client.address`. + - ref: network.peer.port + requirement_level: + recommended: If `network.peer.address` is set. - ref: network.transport - ref: network.type