diff --git a/schemas/1.11.0 b/schemas/1.11.0 index 0c7f23bc02d..778a2eba1cc 100644 --- a/schemas/1.11.0 +++ b/schemas/1.11.0 @@ -7,7 +7,7 @@ versions: - rename_attributes: attribute_map: net.peer.ip: net.sock.peer.addr - net.host.port: net.sock.host.port + net.host.ip: net.sock.host.addr 1.10.0: 1.9.0: diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index cb7059c06f3..58177ff3e60 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -229,8 +229,6 @@ groups: conditional: Required if using a port other than the default port for this DBMS. - ref: net.sock.family tag: connection-level - required: - conditional: if applicable and if any of `net.sock.peer.addr` or `net.peer.name` are set. - ref: net.transport tag: connection-level required: @@ -250,7 +248,7 @@ groups: tag: connection-level-tech-specific type: string note: > - If setting a `db.mssql.instance_name`, `net.sock.peer.port` is no longer + If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). brief: > The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index 876d5e14c55..07b7cb0faa9 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -71,24 +71,28 @@ groups: type: int brief: 'Logical remote port number' examples: [80, 8080, 443] + - id: host.name + type: string + brief: 'Logical local hostname or similar, see note below.' + examples: 'localhost' + - id: host.port + type: int + brief: 'Logical local port number, preferably the one that the peer used to connect' + examples: 8080 - id: sock.host.addr type: string brief: 'Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host.' note: > Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) - or [Windows](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname) + or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. examples: '192.168.0.1' - id: sock.host.port type: int required: conditional: if `net.sock.host.addr` is set and `net.sock.family` has a notion of port - brief: 'Like `net.sock.peer.port` but for the host port.' + brief: 'Local socket peer port (if defined for the address family).' examples: 35555 - - id: host.name - type: string - brief: 'Logical local hostname or similar, see note below.' - examples: 'localhost' - id: host.connection.type type: allow_custom_values: true diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index ebdc569be9d..b674e12fbba 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -116,6 +116,17 @@ groups: examples: 3 - ref: net.sock.peer.addr - ref: net.sock.peer.port + - ref: net.sock.family + + constraints: + - include: network + + - id: http.client + prefix: http + extends: http + span_kind: client + brief: 'Semantic Convention for HTTP Client' + attributes: - ref: net.peer.name sampling_relevant: true brief: > @@ -134,18 +145,6 @@ groups: note: > When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port component, otherwise it MUST match `Host` header port component. - - constraints: - - include: network - - - id: http.client - prefix: http - extends: http - span_kind: client - brief: 'Semantic Convention for HTTP Client' - attributes: - - ref: net.peer.name - sampling_relevant: true constraints: - any_of: - [http.url] @@ -191,12 +190,28 @@ groups: one is at least somewhat confident that the address is not that of the closest proxy. examples: '83.164.160.102' + - ref: net.host.name + sampling_relevant: true + brief: > + Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. + note: > + When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set + `net.host.name` to the IP address provided in the host component. + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match + URI host component, otherwise `Host` header host component SHOULD be used. + - ref: net.host.port + sampling_relevant: true + brief: > + Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. + note: > + When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match + URI port component, otherwise `Host` header port component SHOULD be used. - ref: net.sock.host.addr - ref: net.sock.host.port constraints: - any_of: - [http.scheme, http.host, http.target] - - [http.scheme, http.server_name, net.sock.host.port, http.target] - - [http.scheme, net.host.name, net.sock.host.port, http.target] + - [http.scheme, http.server_name, net.host.port, http.target] + - [http.scheme, net.host.name, net.host.port, http.target] - [http.url] diff --git a/specification/metrics/datamodel.md b/specification/metrics/datamodel.md index a09d69c5791..7376b022c35 100644 --- a/specification/metrics/datamodel.md +++ b/specification/metrics/datamodel.md @@ -1292,7 +1292,7 @@ attributes, and MUST NOT be added as metric attributes: | OTLP Resource Attribute | Description | | ----------------------- | ----------- | | `net.host.name` | The `` portion of the target's URL that was scraped | -| `net.sock.host.port` | The `` portion of the target's URL that was scraped | +| `net.host.port` | The `` portion of the target's URL that was scraped | | `http.scheme` | `http` or `https` | In addition to the attributes above, the diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 5b04f6153e2..0c64a1c497c 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -47,7 +47,7 @@ and whether they should be on server, client, or both types of HTTP metric event | `net.sock.peer.addr` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | | `http.server_name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). | | `net.host.name` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.sock.host.port` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `net.host.port` | `server` | see [2] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | The following attributes SHOULD be included in the `http.server.active_requests` observation: @@ -93,13 +93,12 @@ path. * `http.url` * `http.scheme`, `http.host`, `http.target` * `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` -* `http.scheme`, `net.sock.peer.addr`, `net.peer.port`, `http.target` **[2]** For server metric attributes, `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. ). It is thus preferred to supply the raw data that _is_ available. Namely, one of the following sets is RECOMMENDED (in order of usual preference unless for a particular web server/framework it is known that some other set is preferable for some reason; all strings must be non-empty): * `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `http.server_name`, `net.sock.host.port`, `http.target` -* `http.scheme`, `net.host.name`, `net.sock.host.port`, `http.target` +* `http.scheme`, `http.server_name`, `net.host.port`, `http.target` +* `http.scheme`, `net.host.name`, `net.host.port`, `http.target` * `http.url` diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 0651b1bf3dc..2a7f9415776 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -43,21 +43,19 @@ 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;` | No | | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | No | | [`net.peer.name`](span-general.md) | string | Database hostname. [1] | `example.com` | See below. | -| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | Conditional [2] | +| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | No | | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address (IPv4 or IPv6 for internet protocols, path for local communication, - [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). [3] | `127.0.0.1`; `/tmp/mysql.sock` | See below. | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditional [4] | -| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [5] | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). [2] | `127.0.0.1`; `/tmp/mysql.sock` | See below. | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditional [3] | +| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditional [4] | **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[2]:** if applicable and if any of `net.sock.peer.addr` or `net.peer.name` are set. +**[2]:** 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) with format specific to protocol address family. -**[3]:** 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) with format specific to protocol address family. +**[3]:** Required if using a port other than the default port for this DBMS. -**[4]:** Required if using a port other than the default port for this DBMS. - -**[5]:** Recommended in general, required for in-process databases (`"inproc"`). +**[4]:** Recommended in general, required for in-process databases (`"inproc"`). **Additional attribute requirements:** At least one of the following sets of attributes is required: @@ -143,7 +141,7 @@ When additional attributes are added that only apply to a specific DBMS, its ide | `db.jdbc.driver_classname` | string | The fully-qualified class name of the [Java Database Connectivity (JDBC)](https://docs.oracle.com/javase/8/docs/technotes/guides/jdbc/) driver used to connect. | `org.postgresql.Driver`; `com.microsoft.sqlserver.jdbc.SQLServerDriver` | No | | `db.mssql.instance_name` | string | The Microsoft SQL Server [instance name](https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15) connecting to. This name is used to determine the port of a named instance. [1] | `MSSQLSERVER` | No | -**[1]:** If setting a `db.mssql.instance_name`, `net.sock.peer.port` is no longer required (but still recommended if non-standard). +**[1]:** If setting a `db.mssql.instance_name`, `net.peer.port` is no longer required (but still recommended if non-standard). ## Call-level attributes diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 14b4098f837..803ec0313eb 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -74,10 +74,9 @@ Don't set the span status description if the reason can be inferred from `http.s | `http.response_content_length` | 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://tools.ietf.org/html/rfc7230#section-3.3.2) header. For requests using transport encoding, this should be the compressed size. | `3495` | No | | `http.response_content_length_uncompressed` | int | The size of the uncompressed response payload body after transport decoding. Not set if transport encoding not used. | `5493` | No | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | If and only if a request was retried. | -| [`net.peer.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [4] | `example.com` | No | -| [`net.peer.port`](span-general.md) | int | Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [5] | `80`; `8080`; `443` | if not default for request scheme. | +| [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | No | | [`net.sock.peer.addr`](span-general.md) | string | Remote socket peer address (IPv4 or IPv6 for internet protocols, path for local communication, - [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). [6] | `127.0.0.1`; `/tmp/mysql.sock` | No | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | No | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | No | **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case the attribute's value should be `https://www.example.com/`. @@ -86,11 +85,7 @@ Don't set the span status description if the reason can be inferred from `http.s **[3]:** If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. -**[4]:** When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.peer.name` to the IP address provided in the host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used. - -**[5]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port component, otherwise it MUST match `Host` header port component. - -**[6]:** 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) with format specific to protocol address family. +**[4]:** 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) with format specific to protocol address family. `http.flavor` 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. @@ -110,11 +105,9 @@ Following attributes MUST be provided **at span creation time** (when provided a * `http.target` * `http.host` * `http.scheme` -* [`net.peer.name`](span-general.md) -* [`net.peer.port`](span-general.md) -It is recommended to also use the general [network attributes][], especially `net.sock.peer.addr`. If `net.transport` is not specified, it can be assumed to be `IP.TCP` except if `http.flavor` is `QUIC`, in which case `IP.UDP` is assumed. +It is recommended to also use the general [network attributes][] (`net.sock.peer.addr` and `net.sock.peer.port`) when available. ### HTTP request and response headers @@ -156,9 +149,12 @@ before any HTTP-redirects that may happen when executing the request. | Attribute | Type | Description | Examples | Required | |---|---|---|---|---| -| [`net.peer.name`](span-general.md) | string | Logical remote hostname, see note below. [1] | `example.com` | See below | +| [`net.peer.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [1] | `example.com` | See below | +| [`net.peer.port`](span-general.md) | int | Port identifier of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [2] | `80`; `8080`; `443` | if not default for request scheme. | + +**[1]:** When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.peer.name` to the IP address provided in the host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used. -**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[2]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.peer.name` MUST match URI port component, otherwise it MUST match `Host` header port component. **Additional attribute requirements:** At least one of the following sets of attributes is required: @@ -169,6 +165,7 @@ before any HTTP-redirects that may happen when executing the request. Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: * [`net.peer.name`](span-general.md) +* [`net.peer.port`](span-general.md) Note that in some cases `http.host` might be different @@ -242,8 +239,10 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | `http.server_name` | string | The primary server name of the matched virtual host. This should be obtained via configuration. If no such configuration can be obtained, this attribute MUST NOT be set ( `net.host.name` should be used instead). [1] | `example.com` | See below | | `http.route` | string | The matched route (path template). | `/users/:userID?` | No | | `http.client_ip` | string | The IP address of the original client behind all proxies, if known (e.g. from [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)). [2] | `83.164.160.102` | No | -| [`net.sock.host.addr`](span-general.md) | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [3] | `192.168.0.1` | No | -| [`net.sock.host.port`](span-general.md) | int | Like `net.sock.peer.port` but for the host port. | `35555` | See below | +| [`net.host.name`](span-general.md) | string | Host component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [3] | `localhost` | See below | +| [`net.host.port`](span-general.md) | int | Port component of the ["origin"](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.6) server HTTP request is sent to. [4] | `8080` | See below | +| [`net.sock.host.addr`](span-general.md) | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [5] | `192.168.0.1` | No | +| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | No | **[1]:** `http.url` is usually not readily available on the server side but would have to be assembled in a cumbersome and sometimes lossy process from other information (see e.g. open-telemetry/opentelemetry-python/pull/148). It is thus preferred to supply the raw data that is available. @@ -259,14 +258,23 @@ comes from a proxy, reverse proxy, or the actual client. Setting one is at least somewhat confident that the address is not that of the closest proxy. -**[3]:** Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) or [Windows](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. +**[3]:** When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set `net.host.name` to the IP address provided in the host component. When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.name` SHOULD match URI host component, otherwise `Host` header host component SHOULD be used. + +**[4]:** When [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource) is absolute URI, `net.host.port` SHOULD match URI port component, otherwise `Host` header port component SHOULD be used. + +**[5]:** Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. **Additional attribute requirements:** At least one of the following sets of attributes is required: * `http.scheme`, `http.host`, `http.target` -* `http.scheme`, `http.server_name`, [`net.sock.host.port`](span-general.md), `http.target` -* `http.scheme`, [`net.host.name`](span-general.md), [`net.sock.host.port`](span-general.md), `http.target` +* `http.scheme`, `http.server_name`, [`net.host.port`](span-general.md), `http.target` +* `http.scheme`, [`net.host.name`](span-general.md), [`net.host.port`](span-general.md), `http.target` * `http.url` + +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* [`net.host.name`](span-general.md) +* [`net.host.port`](span-general.md) Of course, more than the required attributes can be supplied, but this is recommended only if they cannot be inferred from the sent ones. diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index cc25efd4c10..52885b3b6e1 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -118,9 +118,9 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | No | | [`net.sock.family`](span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | No | | [`net.sock.host.addr`](span-general.md) | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [1] | `192.168.0.1` | No | -| [`net.sock.host.port`](span-general.md) | int | Like `net.sock.peer.port` but for the host port. | `35555` | No | +| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | No | -**[1]:** Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) or [Windows](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. +**[1]:** Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. ### Events diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 5c22b44c77d..33d1f7d9e31 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -41,9 +41,10 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.sock.family` | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `AF_INET`; `AF_BLUETOOTH` | Conditional [3] | | `net.peer.name` | string | Logical remote hostname, see note below. [4] | `example.com` | No | | `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | No | -| `net.sock.host.addr` | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [5] | `192.168.0.1` | No | -| `net.sock.host.port` | int | Like `net.sock.peer.port` but for the host port. | `35555` | Conditional [6] | | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | No | +| `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | No | +| `net.sock.host.addr` | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [5] | `192.168.0.1` | No | +| `net.sock.host.port` | int | Local socket peer port (if defined for the address family). | `35555` | Conditional [6] | | `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | No | | `net.host.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` | No | | `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | No | @@ -59,7 +60,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[4]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[5]:** Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) or [Windows](https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. +**[5]:** Can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.htmll) or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname) with format specific to protocol address family. **[6]:** if `net.sock.host.addr` is set and `net.sock.family` has a notion of port @@ -124,27 +125,36 @@ For `Unix` and `pipe`, since the connection goes over the file system instead of ### `net.*.name` attributes -`net.peer.name` and `net.host.name` represent logical remote destinations. Semantic conventions that refer to these attributes SHOULD +`net.peer.name` and `net.host.name` represent logical host names. Semantic conventions that refer to these attributes SHOULD specify what these attributes mean in their context. -For IP-based communication, the name should be a DNS host name of the origin server. +For IP-based communication, the name should be a DNS host name. -For `net.peer.name`, this should be the name of logical remote destination that was used to look up the IP address that was connected to. E.g., `"example.com"` if connecting to an URL `https://example.com/foo`. -Sometimes hostname is only available to instrumentation as a string and may contain DNS name or IP address, `net.peer.name` SHOULD be set to the available known hostname (e.g., `"127.0.0.1"` if connecting to an URL `https://127.0.0.1.com/foo`). Reverse DNS lookup SHOULD NOT be used to obtain DNS name. +#### `net.peer.name` -`net.host.name` should be the host name of the local host, preferably the one that the peer used to connect for the current operation. -If that is not known, a public hostname should be preferred over a private one. However, in that case it may be redundant with information already contained in resources and may be left out. -It will usually not make sense to use reverse-lookup to obtain `net.host.name`, as that would result in static information that is better stored as resource information. +`net.peer.name` should be the name of logical remote destination, e.g., `"example.com"` if connecting to an URL `https://example.com/foo`. +Sometimes host name is only available to instrumentation as a string which may contain DNS name or IP address. `net.peer.name` SHOULD be set to the available known hostname (e.g., `"127.0.0.1"` if connecting to an URL `https://127.0.0.1.com/foo`). + +If only IP address is available via `net.sock.peer.addr`, `net.peer.name` SHOULD NOT be set. Reverse DNS lookup SHOULD NOT be used to obtain DNS name. If `net.transport` is `"pipe"`, the absolute path to the file representing it should be used as `net.peer.name` (`net.host.name` doesn't make sense in that context). If there is no such file (e.g., anonymous pipe), the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation. -For Unix domain socket, `net.sock.peer.addr` attribute represents destination name. +For Unix domain socket, `net.sock.peer.addr` attribute represents destination name and `net.peer.name` SHOULD NOT be set. + +#### `net.host.name` + +`net.host.name` should be the host name of the local host, preferably the one that the peer used to connect for the current operation. +If that is not known, a public hostname should be preferred over a private one. However, in that case it may be redundant with information already contained in resources and may be left out. +It will usually not make sense to use reverse-lookup to obtain `net.host.name`, as that would result in static information that is better stored as resource information. ### Connecting over proxy -When connecting to the remote destination through a proxy, client instrumentations SHOULD set `net.peer.name` and `net.peer.port` SHOULD be set to logical remote destination address and `net.sock.peer.addr` and `net.sock.peer.port` to the proxy address and proxy port respectively. +When connecting to the remote destination through a proxy, client instrumentations SHOULD set `net.peer.name` and `net.peer.port` to logical remote destination address and `net.sock.peer.addr` and `net.sock.peer.port` to the proxy address and proxy port respectively. + +Server instrumentations that use `net.host.name` and `net.host.port` SHOULD set them to logical local host; `net.sock.peer.addr` and `net.sock.peer.port` SHOULD be set to the proxy address. +Server semantic conventions SHOULD define additional attribute(s) representing originating peer address for reverse-proxy scenarios when such information is available. ## General remote service attributes