From c7f4f1a6bb1cb7609f5ce54deea4e76bea2cfa20 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 9 Jun 2022 20:33:41 -0700 Subject: [PATCH 01/11] Define net.sock attributes --- schemas/1.11.0 | 6 ++ semantic_conventions/trace/database.yaml | 18 +++- semantic_conventions/trace/general.yaml | 83 +++++++++++++----- semantic_conventions/trace/http.yaml | 54 +++++++++--- semantic_conventions/trace/messaging.yaml | 6 +- semantic_conventions/trace/rpc.yaml | 18 +++- .../common/attribute-requirement-level.md | 2 +- .../semantic_conventions/http-metrics.md | 3 +- .../metrics/semantic_conventions/rpc.md | 16 ++-- .../trace/semantic_conventions/database.md | 25 ++++-- .../trace/semantic_conventions/http.md | 54 ++++++++---- .../trace/semantic_conventions/messaging.md | 9 +- .../trace/semantic_conventions/rpc.md | 22 +++-- .../semantic_conventions/span-general.md | 87 +++++++++++++++---- 14 files changed, 303 insertions(+), 100 deletions(-) diff --git a/schemas/1.11.0 b/schemas/1.11.0 index abadb0343ff..c2148e86232 100644 --- a/schemas/1.11.0 +++ b/schemas/1.11.0 @@ -2,6 +2,12 @@ file_format: 1.0.0 schema_url: https://opentelemetry.io/schemas/1.11.0 versions: 1.11.0: + spans: + changes: + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr 1.10.0: 1.9.0: 1.8.0: diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index 31bb41fa28e..902b5b2409a 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -217,14 +217,24 @@ groups: tag: connection-level requirement_level: conditionally_required: See alternative attributes below. - - ref: net.peer.ip + brief: > + Database hostname. + - ref: net.peer.port + tag: connection-level + requirement_level: + conditionally_required: If using a port other than the default port for this DBMS. + - ref: net.sock.peer.addr tag: connection-level requirement_level: conditionally_required: See alternative attributes below. - - ref: net.peer.port + - ref: net.sock.peer.port tag: connection-level requirement_level: - conditionally_required: If using a port other than the default port for this DBMS. + conditionally_required: if using a port other than the default port for this DBMS. + - ref: net.sock.family + tag: connection-level + requirement_level: + conditionally_required: if applicable and if `net.sock.peer.addr` is set. - ref: net.transport tag: connection-level requirement_level: @@ -232,7 +242,7 @@ groups: constraints: - any_of: - 'net.peer.name' - - 'net.peer.ip' + - 'net.sock.peer.addr' - id: db.mssql prefix: db.mssql diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index a172ac79023..af39772bed9 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -6,18 +6,12 @@ groups: attributes: - id: transport type: - allow_custom_values: false + allow_custom_values: true members: - id: ip_tcp value: "ip_tcp" - id: ip_udp value: "ip_udp" - - id: ip - value: "ip" - brief: 'Another IP-based protocol' - - id: unix - value: "unix" - brief: 'Unix Domain socket. See below.' - id: pipe value: "pipe" brief: 'Named or anonymous pipe. See note below.' @@ -48,31 +42,80 @@ groups: - id: peer.ip type: string brief: > - Remote address of the peer (dotted decimal for IPv4 or + Remote address of the logical peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) examples: '127.0.0.1' - - id: peer.port + - id: sock.peer.name + type: string + brief: > + Remote socket peer name. + examples: proxy.example.com + - id: sock.peer.addr + type: string + brief: > + 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)). + note: > + 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. + examples: ['127.0.0.1', '/tmp/mysql.sock' ] + - id: sock.peer.port type: int - brief: 'Remote port number.' - examples: [80, 8080, 443] + requirement_level: + conditionally_required: if `net.sock.peer.addr` is set and `net.sock.family` has a notion of port + brief: 'Remote socket peer port (if defined for the address family).' + examples: 16456 + - id: sock.family + type: + allow_custom_values: true + members: + - id: inet + value: 'AF_INET' + brief: "IPv4 address" + - id: inet6 + value: 'AF_INET6' + brief: "IPv6 address" + - id: unix + value: 'AF_UNIX' + brief: "Unix domain socket path/" + requirement_level: + conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set + brief: > + Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. + examples: ['AF_INET', 'AF_BLUETOOTH'] - id: peer.name type: string - brief: 'Remote hostname or similar, see note below.' + brief: 'Logical remote hostname, see note below.' examples: 'example.com' note: > `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. - - id: host.ip - type: string - brief: 'Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host.' - examples: '192.168.0.1' - - id: host.port + - id: peer.port type: int - brief: 'Like `net.peer.port` but for the host port.' - examples: 35555 + brief: 'Logical remote port number' + examples: [80, 8080, 443] - id: host.name type: string - brief: 'Local hostname or similar, see note below.' + 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.html) + 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 + requirement_level: + conditionally_required: if `net.sock.host.addr` is set and `net.sock.family` has a notion of port + brief: 'Local socket peer port (if defined for the address family).' + examples: 35555 - id: host.connection.type type: allow_custom_values: true diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index e4c4c4adb10..68b5b8ec2ad 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -114,10 +114,11 @@ groups: requirement_level: recommended: If and only if a request was retried. examples: 3 - - ref: net.peer.ip - sampling_relevant: true - - ref: net.peer.port - sampling_relevant: true + - ref: net.sock.peer.addr + - ref: net.sock.peer.port + - ref: net.sock.family + requirement_level: + conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set constraints: - include: network @@ -129,12 +130,27 @@ groups: attributes: - ref: net.peer.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.peer.name` to the provided 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. + - ref: net.peer.port + sampling_relevant: true + requirement_level: + conditionally_required: if not default for request scheme. + brief: > + Port identifier 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.peer.name` MUST match + URI port component, otherwise it MUST match `Host` header port component. constraints: - any_of: - [http.url] - [http.scheme, http.host, http.target] - [http.scheme, net.peer.name, net.peer.port, http.target] - - [http.scheme, net.peer.ip, net.peer.port, http.target] - id: http.server prefix: http @@ -163,18 +179,36 @@ groups: 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)). note: | - This is not necessarily the same as `net.peer.ip`, which would + This is not necessarily the same as `net.sock.peer.addr`, which would identify the network-level peer, which may be a proxy. This attribute should be set when a source of information different - from the one used for `net.peer.ip`, is available even if that other - source just confirms the same value as `net.peer.ip`. - Rationale: For `net.peer.ip`, one typically does not know if it + from the one used for `net.sock.peer.addr`, is available even if that other + source just confirms the same value as `net.sock.peer.addr`. + Rationale: For `net.sock.peer.addr`, one typically does not know if it comes from a proxy, reverse proxy, or the actual client. Setting - `http.client_ip` when it's the same as `net.peer.ip` means that + `http.client_ip` when it's the same as `net.sock.peer.addr` means that 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] diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 1ae44f24c06..395d06b3f56 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -72,10 +72,14 @@ 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: net.peer.ip + - ref: net.sock.peer.addr tag: connection-level requirement_level: conditionally_required: If available. + - ref: net.sock.peer.port + tag: connection-level + - ref: net.sock.family + tag: connection-level constraints: - include: network diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 6ca4a990461..3a2c8534cad 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -45,17 +45,27 @@ groups: (e.g., method actually executing the call on the server side, RPC client stub method on the client side). examples: "exampleMethod" - - ref: net.peer.ip + - ref: net.sock.peer.addr + - ref: net.sock.peer.port + - ref: net.sock.family - ref: net.peer.name + requirement_level: required + brief: > + RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). + note: > + May contain server IP address, DNS name, or local socket name. 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. - ref: net.peer.port requirement_level: conditionally_required: See below + brief: > + RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) - ref: net.transport requirement_level: conditionally_required: See below constraints: - any_of: - - net.peer.ip - net.peer.name - include: network @@ -66,7 +76,9 @@ groups: brief: 'Semantic Convention for RPC server spans' attributes: - ref: net.host.name - - ref: net.host.ip + - ref: net.sock.host.addr + - ref: net.sock.host.port + - ref: net.sock.family - id: rpc.grpc prefix: rpc.grpc diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 5a7d6e323d3..181f9415b79 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -48,7 +48,7 @@ All instrumentations MUST add the attribute when given condition is satisfied. S When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute. -For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.peer.ip` is available, instrumentation can do a DNS lookup, cache and populate `net.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. +For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. ## Recommended diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index adfa821c9de..5eab40ea73f 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -52,7 +52,7 @@ and whether they should be on server, client, or both types of HTTP metric event | `http.flavor` | `client` & `server` | Recommended | Kind of HTTP protocol used: `"1.0"`, `"1.1"`, `"2"`, `"SPDY"` or `"QUIC"`. | | `net.peer.name` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | | `net.peer.port` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | -| `net.peer.ip` | `client` | see [1] in [attribute alternatives](#attribute-alternatives) | See [general network connection attributes](../../trace/semantic_conventions/span-general.md#general-network-connection-attributes) | +| `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.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) | @@ -101,7 +101,6 @@ path. * `http.url` * `http.scheme`, `http.host`, `http.target` * `http.scheme`, `net.peer.name`, `net.peer.port`, `http.target` -* `http.scheme`, `net.peer.ip`, `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. diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 06b75ab252c..f77853fa10a 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -69,20 +69,24 @@ measurements. | [`rpc.system`](../../trace/semantic_conventions/rpc.md) | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | -| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | See below | -| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: See below | +| [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | +| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) | `80`; `8080`; `443` | Conditionally Required: See below | +| [`net.sock.family`](../../trace/semantic_conventions/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` | Recommended | +| [`net.sock.peer.addr`](../../trace/semantic_conventions/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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). **[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -**[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[3]:** May contain server IP address, DNS name, or local socket name. 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. + +**[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. **Additional attribute requirements:** At least one of the following sets of attributes is required: -* [`net.peer.ip`](../../trace/semantic_conventions/span-general.md) * [`net.peer.name`](../../trace/semantic_conventions/span-general.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. @@ -96,7 +100,7 @@ measurements. To avoid high cardinality, implementations should prefer the most stable of `net.peer.name` or -`net.peer.ip`, depending on expected deployment profile. For many cloud applications, this is likely +`net.sock.peer.addr`, depending on expected deployment profile. For many cloud applications, this is likely `net.peer.name` as names can be recycled even across re-instantiation of a server with a different `ip`. For client-side metrics `net.peer.port` is required if the connection is IP-based and the port is available (it describes the server port they are connecting to). diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 413589fbf28..8a9de27e7f7 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -42,21 +42,28 @@ Some database systems may allow a connection to switch to a different `db.user`, | `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.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.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Conditionally Required: See alternative attributes below. | -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [1] | `example.com` | Conditionally Required: See alternative attributes below. | -| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: [2] | -| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [3] | +| [`net.peer.name`](span-general.md) | string | Database hostname. [1] | `example.com` | Conditionally Required: See alternative attributes below. | +| [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: [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` | Conditionally Required: if applicable and if `net.sock.peer.addr` is set. | +| [`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` | Conditionally Required: See alternative attributes below. | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditionally Required: [4] | +| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [5] | **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. **[2]:** If using a port other than the default port for this DBMS. -**[3]:** If database type is in-process (`"inproc"`), recommended for other database types. +**[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. + +**[4]:** if using a port other than the default port for this DBMS. + +**[5]:** If database type is in-process (`"inproc"`), recommended for other database types. **Additional attribute requirements:** At least one of the following sets of attributes is required: * [`net.peer.name`](span-general.md) -* [`net.peer.ip`](span-general.md) +* [`net.sock.peer.addr`](span-general.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. @@ -216,7 +223,7 @@ Separated for clarity. | `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` | | `db.user` | `"billing_user"` | | `net.peer.name` | `"shopdb.example.com"` | -| `net.peer.ip` | `"192.0.2.12"` | +| `net.sock.peer.addr` | `"192.0.2.12"` | | `net.peer.port` | `3306` | | `net.transport` | `"IP.TCP"` | | `db.name` | `"ShopDb"` | @@ -226,7 +233,7 @@ Separated for clarity. ### Redis -In this example, Redis is connected using a unix domain socket and therefore the connection string and `net.peer.ip` are left out. +In this example, Redis is connected using a unix domain socket and therefore the connection string and `net.sock.peer.addr` are left out. Furthermore, `db.name` is not specified as there is no database name in Redis and `db.redis.database_index` is set instead. | Key | Value | @@ -251,7 +258,7 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an | `db.connection_string` | not set | | `db.user` | `"the_user"` | | `net.peer.name` | `"mongodb0.example.com"` | -| `net.peer.ip` | `"192.0.2.14"` | +| `net.sock.peer.addr` | `"192.0.2.14"` | | `net.peer.port` | `27017` | | `net.transport` | `"IP.TCP"` | | `db.name` | `"shopDb"` | diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 5d6cf79e6d9..410169a9f16 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -74,8 +74,10 @@ 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` | Recommended | | `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` | Recommended | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. | -| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended | -| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Recommended | +| [`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` | Conditionally Required: [4] | +| [`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)). [5] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | **[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/`. @@ -83,6 +85,10 @@ 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]:** if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set + +**[5]:** 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. | Value | Description | @@ -101,11 +107,9 @@ Following attributes MUST be provided **at span creation time** (when provided a * `http.target` * `http.host` * `http.scheme` -* [`net.peer.ip`](span-general.md) -* [`net.peer.port`](span-general.md) -It is recommended to also use the general [network attributes][], especially `net.peer.ip`. 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 @@ -147,25 +151,28 @@ before any HTTP-redirects that may happen when executing the request. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, 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` | Conditionally Required: if not default for request scheme. | -**[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[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 provided 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. + +**[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: * `http.url` * `http.scheme`, `http.host`, `http.target` * `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target` -* `http.scheme`, [`net.peer.ip`](span-general.md), [`net.peer.port`](span-general.md), `http.target` 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 from the `net.peer.name` -used to look up the `net.peer.ip` that is actually connected to. +used to look up the `net.sock.peer.addr` that is actually connected to. In that case it is strongly recommended to set the `net.peer.name` attribute in addition to `http.host`. ## HTTP server @@ -234,27 +241,42 @@ 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?` | Recommended | | `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` | Recommended | +| [`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` | Recommended | +| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | **[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. -**[2]:** This is not necessarily the same as `net.peer.ip`, which would +**[2]:** This is not necessarily the same as `net.sock.peer.addr`, which would identify the network-level peer, which may be a proxy. This attribute should be set when a source of information different -from the one used for `net.peer.ip`, is available even if that other -source just confirms the same value as `net.peer.ip`. -Rationale: For `net.peer.ip`, one typically does not know if it +from the one used for `net.sock.peer.addr`, is available even if that other +source just confirms the same value as `net.sock.peer.addr`. +Rationale: For `net.sock.peer.addr`, one typically does not know if it comes from a proxy, reverse proxy, or the actual client. Setting -`http.client_ip` when it's the same as `net.peer.ip` means that +`http.client_ip` when it's the same as `net.sock.peer.addr` means that one is at least somewhat confident that the address is not that of the closest proxy. +**[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.html) 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.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. @@ -273,7 +295,7 @@ Span name: `HTTP GET` | `http.method` | `"GET"` | | `http.flavor` | `"1.1"` | | `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | -| `net.peer.ip` | `"192.0.2.5"` | +| `net.sock.peer.addr` | `"192.0.2.5"` | | `http.status_code` | `200` | The corresponding server Span may look like this: @@ -292,7 +314,7 @@ Span name: `/webshop/articles/:article_id`. | `http.route` | `"/webshop/articles/:article_id"` | | `http.status_code` | `200` | | `http.client_ip` | `"192.0.2.4"` | -| `net.peer.ip` | `"192.0.2.5"` (the client goes through a proxy) | +| `net.sock.peer.addr` | `"192.0.2.5"` (the client goes through a proxy) | | `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | Note that following the recommendations above, `http.url` is not set in the above example. diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index d08fc0fed0c..4d087d22e00 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -139,8 +139,11 @@ The following operations related to messages are defined for these semantic conv | `messaging.conversation_id` | string | The [conversation ID](#conversations) identifying the conversation to which the message belongs, represented as a string. Sometimes called "Correlation ID". | `MyConversationId` | Recommended | | `messaging.message_payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended | | `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended | -| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Conditionally Required: If available. | -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | Conditionally Required: If available. | +| [`net.peer.name`](span-general.md) | string | Logical remote hostname, see note below. [3] | `example.com` | Conditionally Required: If available. | +| [`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` | Recommended | +| [`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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Conditionally Required: If available. | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | **[1]:** If the message destination is either a `queue` or `topic`. @@ -148,6 +151,8 @@ The following operations related to messages are defined for these semantic conv **[3]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. +**[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. + `messaging.destination_kind` MUST be one of the following: | Value | Description | diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 6cbee348d7b..243a53a548e 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -60,20 +60,24 @@ Examples of span names: | `rpc.system` | string | A string identifying the remoting system. See below for a list of well-known identifiers. | `grpc` | Required | | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | -| [`net.peer.ip`](span-general.md) | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | See below | -| [`net.peer.name`](span-general.md) | string | Remote hostname or similar, see note below. [3] | `example.com` | See below | -| [`net.peer.port`](span-general.md) | int | Remote port number. | `80`; `8080`; `443` | Conditionally Required: See below | +| [`net.peer.name`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | +| [`net.peer.port`](span-general.md) | int | RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) | `80`; `8080`; `443` | Conditionally Required: 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` | Recommended | +| [`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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). **[2]:** This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The `code.function` attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side). -**[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[3]:** May contain server IP address, DNS name, or local socket name. 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. + +**[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. **Additional attribute requirements:** At least one of the following sets of attributes is required: -* [`net.peer.ip`](span-general.md) * [`net.peer.name`](span-general.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. @@ -111,8 +115,12 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| [`net.host.ip`](span-general.md) | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended | -| [`net.host.name`](span-general.md) | string | Local hostname or similar, see note below. | `localhost` | Recommended | +| [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | +| [`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` | Recommended | +| [`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` | Recommended | +| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | + +**[1]:** 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) 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 fc0e07185dc..6282ab8ec51 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -13,6 +13,9 @@ Particular operations may refer to or require some of these attributes. - [General network connection attributes](#general-network-connection-attributes) * [Network transport attributes](#network-transport-attributes) * [`net.*.name` attributes](#netname-attributes) + + [`net.peer.name`](#netpeername) + + [`net.host.name`](#nethostname) + + [Connecting through intermediary](#connecting-through-intermediary) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) - [General thread attributes](#general-thread-attributes) @@ -37,12 +40,18 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | Recommended | | `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | -| `net.peer.ip` | string | Remote address of the peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended | -| `net.peer.port` | int | Remote port number. | `80`; `8080`; `443` | Recommended | -| `net.peer.name` | string | Remote hostname or similar, see note below. [2] | `example.com` | Recommended | -| `net.host.ip` | string | Like `net.peer.ip` but for the host IP. Useful in case of a multi-IP host. | `192.168.0.1` | Recommended | -| `net.host.port` | int | Like `net.peer.port` but for the host port. | `35555` | Recommended | -| `net.host.name` | string | Local hostname or similar, see note below. | `localhost` | Recommended | +| `net.peer.ip` | string | Remote address of the logical peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended | +| `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended | +| `net.sock.peer.addr` | 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)). [2] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| `net.sock.peer.port` | int | Remote socket peer port (if defined for the address family). | `16456` | Conditionally Required: [3] | +| `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` | Conditionally Required: [4] | +| `net.peer.name` | string | Logical remote hostname, see note below. [5] | `example.com` | Recommended | +| `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | Recommended | +| `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | +| `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended | +| `net.sock.host.addr` | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [6] | `192.168.0.1` | Recommended | +| `net.sock.host.port` | int | Local socket peer port (if defined for the address family). | `35555` | Conditionally Required: [7] | | `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended | | `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` | Recommended | | `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | @@ -52,22 +61,38 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[1]:** `net.app.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`. -**[2]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[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. -`net.transport` MUST be one of the following: +**[3]:** if `net.sock.peer.addr` is set and `net.sock.family` has a notion of port + +**[4]:** if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set + +**[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. + +**[6]:** 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) with format specific to protocol address family. + +**[7]:** if `net.sock.host.addr` is set and `net.sock.family` has a notion of port + +`net.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | |---|---| | `ip_tcp` | ip_tcp | | `ip_udp` | ip_udp | -| `ip` | Another IP-based protocol | -| `unix` | Unix Domain socket. See below. | | `pipe` | Named or anonymous pipe. See note below. | | `inproc` | In-process communication. [1] | | `other` | Something else (non IP-based). | **[1]:** Signals that there is only in-process communication not using a "real" network protocol in cases where network attributes would normally be expected. Usually all other network attributes can be left out in that case. +`net.sock.family` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. + +| Value | Description | +|---|---| +| `AF_INET` | IPv4 address | +| `AF_INET6` | IPv6 address | +| `AF_UNIX` | Unix domain socket path/ | + `net.host.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | @@ -109,20 +134,44 @@ 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 host names. Semantic conventions that refer to these attributes SHOULD +specify what these attributes mean in their context. + +Semantic conventions and instrumentations that populate both logical (`net.peer.name`, `net.host.name`) and socket-level (`net.sock.*.name`) attributes SHOULD only set socket-level attributes when they don't match logical ones. For example, when direct connection to the remote destination is established and when `net.peer.name` is populated, `net.sock.peer.name` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information. + +#### `net.peer.name` + For IP-based communication, the name should be a DNS host name. -For `net.peer.name`, this should be the name that was used to look up the IP address that was connected to -(i.e., matching `net.peer.ip` if that one is set; e.g., `"example.com"` if connecting to an URL `https://example.com/foo`). -If only the IP address but no host name is available, reverse DNS lookup SHOULD NOT be used to obtain `net.peer.name`, -and `net.peer.name` SHOULD NOT be set. -`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. -If `net.transport` is `"unix"` or `"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). +`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 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 through intermediary + +When connecting to the remote destination through an intermediary (e.g. 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 intermediary address and port respectively. `net.sock.peer.name` SHOULD be set to intermediary DNS name if readily available. + +Instrumentations SHOULD NOT do DNS lookups to obtain `net.sock.peer.addr` or `net.sock.peer.name`. If intermediary information available to instrumentation can represent DNS name or address, +it SHOULD NOT attempt parsing it and SHOULD set `net.sock.peer.name`. + +For example, [WebProxy in .NET](https://docs.microsoft.com/dotnet/api/system.net.webproxy.address) does not differentiate IP address and DNS name and HTTP instrumentations that don't have access to socket-level communication can only populate `net.sock.peer.name`. Instrumentations that have access to socket-level information, may be able to populate valid `net.sock.peer.addr` instead of or in addition to DNS name. + +Server instrumentations that use `net.host.name` and `net.host.port` SHOULD set them to logical local host; If `net.sock.peer.addr` and `net.sock.peer.port` are used, they SHOULD be set to the address of intermediary connection is established with. +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 This attribute may be used for any operation that accesses some remote service. From 99ef5069947489dcc37b5b052418ed5e841003c1 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 21 Jun 2022 08:33:13 -0700 Subject: [PATCH 02/11] lint --- CHANGELOG.md | 3 + schemas/1.11.0 | 6 -- schemas/1.12.0 | 6 ++ semantic_conventions/trace/database.yaml | 13 +-- semantic_conventions/trace/general.yaml | 21 +---- semantic_conventions/trace/http.yaml | 8 +- semantic_conventions/trace/messaging.yaml | 11 ++- semantic_conventions/trace/rpc.yaml | 14 +++- .../metrics/semantic_conventions/rpc.md | 14 ++-- .../trace/semantic_conventions/database.md | 20 ++--- .../trace/semantic_conventions/http.md | 59 ++++++------- .../trace/semantic_conventions/messaging.md | 11 ++- .../trace/semantic_conventions/rpc.md | 24 ++++-- .../semantic_conventions/span-general.md | 83 +++++++++++++------ 14 files changed, 177 insertions(+), 116 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7752515b01b..c5fd31adb6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,6 +47,9 @@ release. - Add `http.*.*.size` metric semantic conventions for tracking size of requests / responses for http servers / clients ([#2588](https://github.com/open-telemetry/opentelemetry-specification/pull/2588)). +- BREAKING: rename `net.peer.ip` to `net.sock.peer.addr` and `net.host.ip` to `net.sock.host.addr`. + Define socket-level attributes and clarify logical peer and host attributes meaning. + ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594)) ### Compatibility diff --git a/schemas/1.11.0 b/schemas/1.11.0 index c2148e86232..abadb0343ff 100644 --- a/schemas/1.11.0 +++ b/schemas/1.11.0 @@ -2,12 +2,6 @@ file_format: 1.0.0 schema_url: https://opentelemetry.io/schemas/1.11.0 versions: 1.11.0: - spans: - changes: - - rename_attributes: - attribute_map: - net.peer.ip: net.sock.peer.addr - net.host.ip: net.sock.host.addr 1.10.0: 1.9.0: 1.8.0: diff --git a/schemas/1.12.0 b/schemas/1.12.0 index 0cc1fa819dc..5f660482d84 100644 --- a/schemas/1.12.0 +++ b/schemas/1.12.0 @@ -2,6 +2,12 @@ file_format: 1.0.0 schema_url: https://opentelemetry.io/schemas/1.12.0 versions: 1.12.0: + spans: + changes: + - rename_attributes: + attribute_map: + net.peer.ip: net.sock.peer.addr + net.host.ip: net.sock.host.addr 1.11.0: 1.10.0: 1.9.0: diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index 902b5b2409a..307ce16ad8f 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -218,23 +218,24 @@ groups: requirement_level: conditionally_required: See alternative attributes below. brief: > - Database hostname. + Name of the database host. - ref: net.peer.port tag: connection-level requirement_level: conditionally_required: If using a port other than the default port for this DBMS. - ref: net.sock.peer.addr tag: connection-level - requirement_level: - conditionally_required: See alternative attributes below. - ref: net.sock.peer.port - tag: connection-level requirement_level: - conditionally_required: if using a port other than the default port for this DBMS. + recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. + tag: connection-level - ref: net.sock.family tag: connection-level requirement_level: - conditionally_required: if applicable and if `net.sock.peer.addr` is set. + conditionally_required: If and only if `net.sock.peer.addr` is set. + - ref: net.sock.peer.name + requirement_level: + recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. - ref: net.transport tag: connection-level requirement_level: diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index af39772bed9..e9cbaa6748f 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -47,24 +47,17 @@ groups: examples: '127.0.0.1' - id: sock.peer.name type: string - brief: > - Remote socket peer name. + brief: Remote socket peer name. examples: proxy.example.com - id: sock.peer.addr type: string brief: > 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)). - note: > - 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. examples: ['127.0.0.1', '/tmp/mysql.sock' ] - id: sock.peer.port type: int - requirement_level: - conditionally_required: if `net.sock.peer.addr` is set and `net.sock.family` has a notion of port - brief: 'Remote socket peer port (if defined for the address family).' + brief: Remote socket peer port (if defined for the address family). examples: 16456 - id: sock.family type: @@ -79,7 +72,7 @@ groups: - id: unix value: 'AF_UNIX' brief: "Unix domain socket path/" - requirement_level: + requirement_level: conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set brief: > Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. @@ -104,16 +97,10 @@ groups: 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.html) - or [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname) - with format specific to protocol address family. + brief: Local socket address. Useful in case of a multi-IP host.' examples: '192.168.0.1' - id: sock.host.port type: int - requirement_level: - conditionally_required: if `net.sock.host.addr` is set and `net.sock.family` has a notion of port brief: 'Local socket peer port (if defined for the address family).' examples: 35555 - id: host.connection.type diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 68b5b8ec2ad..0a0df4fa11c 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -116,9 +116,15 @@ groups: examples: 3 - ref: net.sock.peer.addr - ref: net.sock.peer.port + requirement_level: + recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. + - ref: net.sock.peer.name + requirement_level: + recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. - ref: net.sock.family requirement_level: - conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set + conditionally_required: If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. + constraints: - include: network diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 395d06b3f56..7e9411937ca 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -74,12 +74,19 @@ groups: conditionally_required: If available. - ref: net.sock.peer.addr tag: connection-level - requirement_level: - conditionally_required: If available. - ref: net.sock.peer.port + requirement_level: + recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. tag: connection-level - ref: net.sock.family tag: connection-level + requirement_level: + conditionally_required: If and only if `net.sock.peer.addr` is set. + - ref: net.sock.peer.name + tag: connection-level + requirement_level: + recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. + constraints: - include: network diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 3a2c8534cad..9905690ccbc 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -47,7 +47,14 @@ groups: examples: "exampleMethod" - ref: net.sock.peer.addr - ref: net.sock.peer.port + requirement_level: + recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. - ref: net.sock.family + requirement_level: + conditionally_required: If and only if `net.sock.peer.addr` is set. + - ref: net.sock.peer.name + requirement_level: + recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. - ref: net.peer.name requirement_level: required brief: > @@ -59,13 +66,12 @@ groups: - ref: net.peer.port requirement_level: conditionally_required: See below - brief: > - RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) - ref: net.transport requirement_level: conditionally_required: See below constraints: - any_of: + - net.sock.peer.addr - net.peer.name - include: network @@ -78,7 +84,11 @@ groups: - ref: net.host.name - ref: net.sock.host.addr - ref: net.sock.host.port + requirement_level: + recommended: If different than `net.host.port` and if `net.sock.host.addr` is set. - ref: net.sock.family + requirement_level: + conditionally_required: If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. - id: rpc.grpc prefix: rpc.grpc diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index f77853fa10a..75253afaa16 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -70,11 +70,12 @@ measurements. | [`rpc.service`](../../trace/semantic_conventions/rpc.md) | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) | `80`; `8080`; `443` | Conditionally Required: See below | -| [`net.sock.family`](../../trace/semantic_conventions/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` | Recommended | +| [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: See below | +| [`net.sock.family`](../../trace/semantic_conventions/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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`net.sock.peer.addr`](../../trace/semantic_conventions/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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | +| [`net.sock.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | +| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] | | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). @@ -83,10 +84,13 @@ measurements. **[3]:** May contain server IP address, DNS name, or local socket name. 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. -**[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. +**[4]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. + +**[5]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. **Additional attribute requirements:** At least one of the following sets of attributes is required: +* [`net.sock.peer.addr`](../../trace/semantic_conventions/span-general.md) * [`net.peer.name`](../../trace/semantic_conventions/span-general.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. diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 8a9de27e7f7..3a5f4318a32 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -42,23 +42,21 @@ Some database systems may allow a connection to switch to a different `db.user`, | `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.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.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | -| [`net.peer.name`](span-general.md) | string | Database hostname. [1] | `example.com` | Conditionally Required: See alternative attributes below. | +| [`net.peer.name`](span-general.md) | string | Name of the database host. [1] | `example.com` | Conditionally Required: See alternative attributes below. | | [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: [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` | Conditionally Required: if applicable and if `net.sock.peer.addr` is set. | +| [`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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`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` | Conditionally Required: See alternative attributes below. | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Conditionally Required: [4] | -| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [5] | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `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` | Recommended: [3] | +| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [4] | **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. **[2]:** If using a port other than the default port for this DBMS. -**[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]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. -**[4]:** if using a port other than the default port for this DBMS. - -**[5]:** If database type is in-process (`"inproc"`), recommended for other database types. +**[4]:** If database type is in-process (`"inproc"`), recommended for other database types. **Additional attribute requirements:** At least one of the following sets of attributes is required: @@ -223,7 +221,7 @@ Separated for clarity. | `db.connection_string` | `"Server=shopdb.example.com;Database=ShopDb;Uid=billing_user;TableCache=true;UseCompression=True;MinimumPoolSize=10;MaximumPoolSize=50;"` | | `db.user` | `"billing_user"` | | `net.peer.name` | `"shopdb.example.com"` | -| `net.sock.peer.addr` | `"192.0.2.12"` | +| `net.sock.peer.addr` | `"192.0.2.12"` | | `net.peer.port` | `3306` | | `net.transport` | `"IP.TCP"` | | `db.name` | `"ShopDb"` | @@ -258,7 +256,7 @@ Furthermore, `db.name` is not specified as there is no database name in Redis an | `db.connection_string` | not set | | `db.user` | `"the_user"` | | `net.peer.name` | `"mongodb0.example.com"` | -| `net.sock.peer.addr` | `"192.0.2.14"` | +| `net.sock.peer.addr` | `"192.0.2.14"` | | `net.peer.port` | `27017` | | `net.transport` | `"IP.TCP"` | | `db.name` | `"shopDb"` | diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 410169a9f16..a6ecdc8bb58 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -76,8 +76,9 @@ Don't set the span status description if the reason can be inferred from `http.s | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. | | [`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` | Conditionally Required: [4] | | [`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)). [5] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [6] | **[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/`. @@ -85,9 +86,11 @@ 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]:** if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set +**[4]:** If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. -**[5]:** 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. +**[5]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. + +**[6]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. `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. @@ -109,7 +112,7 @@ Following attributes MUST be provided **at span creation time** (when provided a * `http.scheme` -It is recommended to also use the general [network attributes][] (`net.sock.peer.addr` and `net.sock.peer.port`) when available. +It is recommended to also use the general [socket-level attributes][] - `net.sock.peer.addr` when available, `net.sock.peer.name` and `net.sock.peer.port` when don't match `net.peer.name` and `net.peer.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected). ### HTTP request and response headers @@ -126,7 +129,7 @@ Users MAY explicitly configure instrumentations to capture them even though it i **[2]:** The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the HTTP library provides access to headers. -[network attributes]: span-general.md#general-network-connection-attributes +[socket-level attributes]: span-general.md#netsock-attributes ### HTTP request retries and redirects @@ -170,6 +173,8 @@ Following attributes MUST be provided **at span creation time** (when provided a * [`net.peer.port`](span-general.md) +It is recommended to also use the general [socket-level attributes][] - `net.sock.host.addr` when available, `net.sock.host.port` when it doesn't match `net.host.port` (if [intermediary](https://www.rfc-editor.org/rfc/rfc9110.html#section-3.7) is detected). + Note that in some cases `http.host` might be different from the `net.peer.name` used to look up the `net.sock.peer.addr` that is actually connected to. @@ -243,7 +248,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | `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` | Recommended | | [`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` | Recommended | +| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | | [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | **[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. @@ -264,8 +269,6 @@ the closest proxy. **[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.html) 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` @@ -290,32 +293,32 @@ As an example, if a browser request for `https://example.com:8080/webshop/articl Span name: `HTTP GET` -| Attribute name | Value | -| :----------------- | :-------------------------------------------------------| -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | +| Attribute name | Value | +| :------------------- | :-------------------------------------------------------| +| `http.method` | `"GET"` | +| `http.flavor` | `"1.1"` | +| `http.url` | `"https://example.com:8080/webshop/articles/4?s=1"` | | `net.sock.peer.addr` | `"192.0.2.5"` | -| `http.status_code` | `200` | +| `http.status_code` | `200` | The corresponding server Span may look like this: Span name: `/webshop/articles/:article_id`. -| Attribute name | Value | -| :----------------- | :---------------------------------------------- | -| `http.method` | `"GET"` | -| `http.flavor` | `"1.1"` | -| `http.target` | `"/webshop/articles/4?s=1"` | -| `http.host` | `"example.com:8080"` | -| `http.server_name` | `"example.com"` | -| `net.host.port` | `8080` | -| `http.scheme` | `"https"` | -| `http.route` | `"/webshop/articles/:article_id"` | -| `http.status_code` | `200` | -| `http.client_ip` | `"192.0.2.4"` | +| Attribute name | Value | +| :------------------- | :---------------------------------------------- | +| `http.method` | `"GET"` | +| `http.flavor` | `"1.1"` | +| `http.target` | `"/webshop/articles/4?s=1"` | +| `http.host` | `"example.com:8080"` | +| `http.server_name` | `"example.com"` | +| `net.host.port` | `8080` | +| `http.scheme` | `"https"` | +| `http.route` | `"/webshop/articles/:article_id"` | +| `http.status_code` | `200` | +| `http.client_ip` | `"192.0.2.4"` | | `net.sock.peer.addr` | `"192.0.2.5"` (the client goes through a proxy) | -| `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | +| `http.user_agent` | `"Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:72.0) Gecko/20100101 Firefox/72.0"` | Note that following the recommendations above, `http.url` is not set in the above example. If set, it would be diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 4d087d22e00..739ff7b65c4 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -140,10 +140,11 @@ The following operations related to messages are defined for these semantic conv | `messaging.message_payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended | | `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended | | [`net.peer.name`](span-general.md) | string | Logical remote hostname, see note below. [3] | `example.com` | Conditionally Required: If available. | -| [`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` | Recommended | +| [`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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Conditionally Required: If available. | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] | **[1]:** If the message destination is either a `queue` or `topic`. @@ -151,7 +152,9 @@ The following operations related to messages are defined for these semantic conv **[3]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[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. +**[4]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. + +**[5]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. `messaging.destination_kind` MUST be one of the following: diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 243a53a548e..3d513a6f5db 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -61,11 +61,12 @@ Examples of span names: | `rpc.service` | string | The full (logical) name of the service being called, including its package name, if applicable. [1] | `myservice.EchoService` | Recommended | | `rpc.method` | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | | [`net.peer.name`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | -| [`net.peer.port`](span-general.md) | int | RPC server [port](https://grpc.github.io/grpc/core/md_doc_naming.html) | `80`; `8080`; `443` | Conditionally Required: 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` | Recommended | +| [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: 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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`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)). [4] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). @@ -74,10 +75,13 @@ Examples of span names: **[3]:** May contain server IP address, DNS name, or local socket name. 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. -**[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. +**[4]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. + +**[5]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. **Additional attribute requirements:** At least one of the following sets of attributes is required: +* [`net.sock.peer.addr`](span-general.md) * [`net.peer.name`](span-general.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. @@ -116,11 +120,13 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | -| [`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` | Recommended | -| [`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` | Recommended | -| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | +| [`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` | Conditionally Required: [1] | +| [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | +| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended: [2] | + +**[1]:** If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. -**[1]:** 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) with format specific to protocol address family. +**[2]:** If different than `net.host.port` and if `net.sock.host.addr` is set. ### Events diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 6282ab8ec51..725d9577c3e 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -12,9 +12,12 @@ Particular operations may refer to or require some of these attributes. - [General network connection attributes](#general-network-connection-attributes) * [Network transport attributes](#network-transport-attributes) - * [`net.*.name` attributes](#netname-attributes) + * [`net.peer.name` and `net.host.name` attributes](#netpeername-and-nethostname-attributes) + [`net.peer.name`](#netpeername) + [`net.host.name`](#nethostname) + * [`net.sock.*` attributes](#netsock-attributes) + + [Peer](#peer) + + [Host](#host) + [Connecting through intermediary](#connecting-through-intermediary) - [General remote service attributes](#general-remote-service-attributes) - [General identity attributes](#general-identity-attributes) @@ -43,15 +46,15 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.peer.ip` | string | Remote address of the logical peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended | | `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended | | `net.sock.peer.addr` | 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)). [2] | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| `net.sock.peer.port` | int | Remote socket peer port (if defined for the address family). | `16456` | Conditionally Required: [3] | -| `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` | Conditionally Required: [4] | -| `net.peer.name` | string | Logical remote hostname, see note below. [5] | `example.com` | Recommended | + [etc](https://man7.org/linux/man-pages/man7/address_families.7.html)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| `net.sock.peer.port` | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | +| `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` | Conditionally Required: [2] | +| `net.peer.name` | string | Logical remote hostname, see note below. [3] | `example.com` | Recommended | | `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | Recommended | | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended | -| `net.sock.host.addr` | string | Like `net.sock.peer.addr` but for the host IP. Useful in case of a multi-IP host. [6] | `192.168.0.1` | Recommended | -| `net.sock.host.port` | int | Local socket peer port (if defined for the address family). | `35555` | Conditionally Required: [7] | +| `net.sock.host.addr` | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | +| `net.sock.host.port` | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | | `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended | | `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` | Recommended | | `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | @@ -61,17 +64,9 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[1]:** `net.app.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`. -**[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. +**[2]:** if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set -**[3]:** if `net.sock.peer.addr` is set and `net.sock.family` has a notion of port - -**[4]:** if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set - -**[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. - -**[6]:** 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) with format specific to protocol address family. - -**[7]:** if `net.sock.host.addr` is set and `net.sock.family` has a notion of port +**[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. `net.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -132,18 +127,19 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties For `Unix` and `pipe`, since the connection goes over the file system instead of being directly to a known peer, `net.peer.name` is the only attribute that usually makes sense (see description of `net.peer.name` below). -### `net.*.name` attributes +### `net.peer.name` and `net.host.name` attributes `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. -Semantic conventions and instrumentations that populate both logical (`net.peer.name`, `net.host.name`) and socket-level (`net.sock.*.name`) attributes SHOULD only set socket-level attributes when they don't match logical ones. For example, when direct connection to the remote destination is established and when `net.peer.name` is populated, `net.sock.peer.name` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information. +Semantic conventions and instrumentations that populate both logical (`net.peer.name`, `net.host.name`) and socket-level (`net.sock.*.name`) 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 `net.peer.name` is populated, `net.sock.peer.name` SHOULD NOT be set. Check out [Connecting through intermediary](#connecting-through-intermediary) for more information. #### `net.peer.name` For IP-based communication, the name should be a DNS host name. -`net.peer.name` should be the name of logical remote destination, e.g., `"example.com"` if connecting to an URL `https://example.com/foo`. +`net.peer.name` should be the name of logical remote destination, e.g., `"example.com"` if connecting to an URL `https://example.com/foo`. Usually, application pass it as configuration to client libraries in form of URL, connection string, host name, etc. + 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. @@ -160,14 +156,51 @@ For Unix domain socket, `net.sock.peer.addr` attribute represents destination na 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 through intermediary +### `net.sock.*` 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. + +`net.sock.family` identifies address family specified when connecting to the socket. For example, it matches `sa_family` field of `sockaddr` structure on [Linux](https://man7.org/linux/man-pages/man0/sys_socket.h.0p.html) and [Windows](https://docs.microsoft.com/windows/win32/api/winsock/ns-winsock-sockaddr). + +_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 runtime or sockets implementations._ -When connecting to the remote destination through an intermediary (e.g. 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 intermediary address and port respectively. `net.sock.peer.name` SHOULD be set to intermediary DNS name if readily available. +#### Peer -Instrumentations SHOULD NOT do DNS lookups to obtain `net.sock.peer.addr` or `net.sock.peer.name`. If intermediary information available to instrumentation can represent DNS name or address, -it SHOULD NOT attempt parsing it and SHOULD set `net.sock.peer.name`. +`net.sock.peer.addr`, `net.sock.peer.port` (when applicable) identify remote peer - the address used to connect to the socket. 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, represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure. +Port SHOULD only be populated for families that have notion of port. + +Address and port can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html), +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername). + +`net.sock.peer.port` SHOULD only be populated for families that have notion of port. + +`net.sock.peer.name` SHOULD be set to the DNS name used to resolve `net.sock.peer.addr` if it's readily available. Instrumentations +SHOULD NOT do DNS lookups to obtain `net.sock.peer.addr` or `net.sock.peer.name`. If peer information available to instrumentation +can represent DNS name or IP address, instrumentation SHOULD NOT attempt to parse it and SHOULD only set `net.sock.peer.name`. + +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 `net.sock.peer.name`. +Instrumentations that have access to socket connection, may be able to populate valid `net.sock.peer.addr` instead of or +in addition to DNS name. + +#### Host + +`net.sock.host.addr`, `net.sock.host.port` (when applicable) identify local socket address - the address used to bind to the socket. 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, `sin_addr` and `sin_port` fields of `sockaddr_in` structure. + +`net.sock.host.port` SHOULD only be populated for families that have notion of port. + +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 -For example, [WebProxy in .NET](https://docs.microsoft.com/dotnet/api/system.net.webproxy.address) does not differentiate IP address and DNS name and HTTP instrumentations that don't have access to socket-level communication can only populate `net.sock.peer.name`. Instrumentations that have access to socket-level information, may be able to populate valid `net.sock.peer.addr` instead of or in addition to DNS name. +When connecting to the remote destination through an intermediary (e.g. 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 socket peer connection is established with - the intermediary. Server instrumentations that use `net.host.name` and `net.host.port` SHOULD set them to logical local host; If `net.sock.peer.addr` and `net.sock.peer.port` are used, they SHOULD be set to the address of intermediary connection is established with. Server semantic conventions SHOULD define additional attribute(s) representing originating peer address for reverse-proxy scenarios when such information is available. From d4abfaf83f35e14ce0e295f28c4153cff74a75ad Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Jun 2022 09:32:24 -0700 Subject: [PATCH 03/11] changelog update --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c5fd31adb6a..1b83af455b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -48,6 +48,8 @@ release. / responses for http servers / clients ([#2588](https://github.com/open-telemetry/opentelemetry-specification/pull/2588)). - BREAKING: rename `net.peer.ip` to `net.sock.peer.addr` and `net.host.ip` to `net.sock.host.addr`. +- BREAKING: rename `net.peer.ip` to `net.sock.peer.addr`, `net.host.ip` to `net.sock.host.addr`, + `net.peer.name` to `net.sock.peer.name` for socket-level instrumentation. Define socket-level attributes and clarify logical peer and host attributes meaning. ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594)) From 653cad4ad2e4acd7d4af2660b6ea99175dc02b4b Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 15 Jun 2022 09:26:58 -0700 Subject: [PATCH 04/11] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- semantic_conventions/trace/general.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index e9cbaa6748f..7b2d18b8d3d 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -64,16 +64,16 @@ groups: allow_custom_values: true members: - id: inet - value: 'AF_INET' + value: 'inet' brief: "IPv4 address" - id: inet6 - value: 'AF_INET6' + value: 'inet6' brief: "IPv6 address" - id: unix - value: 'AF_UNIX' + value: 'unix' brief: "Unix domain socket path/" requirement_level: - conditionally_required: if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set + conditionally_required: if different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set brief: > Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. examples: ['AF_INET', 'AF_BLUETOOTH'] From a56e607ac3624fae5c848dac49e5976990847aa3 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 21 Jun 2022 13:06:59 -0700 Subject: [PATCH 05/11] review feedback --- semantic_conventions/trace/http.yaml | 3 ++- specification/common/attribute-requirement-level.md | 2 +- specification/trace/semantic_conventions/http.md | 1 + specification/trace/semantic_conventions/span-general.md | 8 ++++---- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index 0a0df4fa11c..d873fa1754a 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -152,12 +152,13 @@ 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: - any_of: - [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.sock.peer.port, http.target] - id: http.server prefix: http extends: http diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 181f9415b79..e015ef89eb1 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -48,7 +48,7 @@ All instrumentations MUST add the attribute when given condition is satisfied. S When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute. -For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. +For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.sock.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. ## Recommended diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index a6ecdc8bb58..89ed22a4084 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -166,6 +166,7 @@ before any HTTP-redirects that may happen when executing the request. * `http.url` * `http.scheme`, `http.host`, `http.target` * `http.scheme`, [`net.peer.name`](span-general.md), [`net.peer.port`](span-general.md), `http.target` +* `http.scheme`, [`net.sock.peer.addr`](span-general.md), [`net.sock.peer.port`](span-general.md), `http.target` Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 725d9577c3e..f6cac5727e3 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -64,7 +64,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[1]:** `net.app.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`. -**[2]:** if different than `AF_INET` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set +**[2]:** if different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set **[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. @@ -84,9 +84,9 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | Value | Description | |---|---| -| `AF_INET` | IPv4 address | -| `AF_INET6` | IPv6 address | -| `AF_UNIX` | Unix domain socket path/ | +| `inet` | IPv4 address | +| `inet6` | IPv6 address | +| `unix` | Unix domain socket path/ | `net.host.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. From a038f6ae2a9dd2dc5aa2bba1280a275e6a8cba35 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 21 Jun 2022 13:19:46 -0700 Subject: [PATCH 06/11] nits --- specification/trace/semantic_conventions/span-general.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index f6cac5727e3..50e32476e5b 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -164,11 +164,11 @@ Socket-level attributes identify peer and host that are directly connected to ea `net.sock.family` identifies address family specified when connecting to the socket. For example, it matches `sa_family` field of `sockaddr` structure on [Linux](https://man7.org/linux/man-pages/man0/sys_socket.h.0p.html) and [Windows](https://docs.microsoft.com/windows/win32/api/winsock/ns-winsock-sockaddr). -_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 runtime or sockets implementations._ +_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._ #### Peer -`net.sock.peer.addr`, `net.sock.peer.port` (when applicable) identify remote peer - the address used to connect to the socket. For example, when connecting using `connect(2)` +`net.sock.peer.addr`, `net.sock.peer.port` identify remote peer - the address used to connect to the socket. 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, represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure. Port SHOULD only be populated for families that have notion of port. @@ -189,9 +189,9 @@ in addition to DNS name. #### Host -`net.sock.host.addr`, `net.sock.host.port` (when applicable) identify local socket address - the address used to bind to the socket. For example, when using `bind(2)` +`net.sock.host.addr`, `net.sock.host.port` identify local socket address - the address used to bind to the socket. 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, `sin_addr` and `sin_port` fields of `sockaddr_in` structure. +with `AF_INET` address family, represent `sin_addr` and `sin_port` fields of `sockaddr_in` structure. `net.sock.host.port` SHOULD only be populated for families that have notion of port. From 408aadebe70841576c05baeb18f3d055f3ae9e33 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 27 Jun 2022 18:10:44 -0700 Subject: [PATCH 07/11] review comments --- semantic_conventions/trace/general.yaml | 14 +++++++++++--- semantic_conventions/trace/http.yaml | 6 ------ .../metrics/semantic_conventions/rpc.md | 2 +- .../trace/semantic_conventions/database.md | 2 +- .../trace/semantic_conventions/http.md | 12 +++--------- .../trace/semantic_conventions/messaging.md | 2 +- .../trace/semantic_conventions/rpc.md | 2 +- .../trace/semantic_conventions/span-general.md | 18 +++++++++++------- 8 files changed, 29 insertions(+), 29 deletions(-) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index 7b2d18b8d3d..e2f269a3fcf 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -48,6 +48,8 @@ groups: - id: sock.peer.name type: string brief: Remote socket peer name. + requirement_level: + recommended: If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. examples: proxy.example.com - id: sock.peer.addr type: string @@ -57,7 +59,9 @@ groups: examples: ['127.0.0.1', '/tmp/mysql.sock' ] - id: sock.peer.port type: int - brief: Remote socket peer port (if defined for the address family). + brief: Remote socket peer port. + requirement_level: + recommended: If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. examples: 16456 - id: sock.family type: @@ -71,9 +75,13 @@ groups: brief: "IPv6 address" - id: unix value: 'unix' - brief: "Unix domain socket path/" + brief: "Unix domain socket path" requirement_level: - conditionally_required: if different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set + conditionally_required: > + If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. + Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` + without `net.sock.family` coming from instrumentations that follow previous versions + of this document. brief: > Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. examples: ['AF_INET', 'AF_BLUETOOTH'] diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index d873fa1754a..b06694b6289 100644 --- a/semantic_conventions/trace/http.yaml +++ b/semantic_conventions/trace/http.yaml @@ -116,14 +116,8 @@ groups: examples: 3 - ref: net.sock.peer.addr - ref: net.sock.peer.port - requirement_level: - recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. - ref: net.sock.peer.name - requirement_level: - recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. - ref: net.sock.family - requirement_level: - conditionally_required: If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. constraints: - include: network diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 75253afaa16..fc032b2a889 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -75,7 +75,7 @@ measurements. | [`net.sock.peer.addr`](../../trace/semantic_conventions/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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | -| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] | +| [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index 3a5f4318a32..fd0a6f677b7 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -47,7 +47,7 @@ Some database systems may allow a connection to switch to a different `db.user`, | [`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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`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)). | `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` | Recommended: [3] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [3] | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [4] | **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 89ed22a4084..aaebc20d74b 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -74,11 +74,11 @@ 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` | Recommended | | `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` | Recommended | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. | -| [`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` | Conditionally Required: [4] | +| [`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` | Recommended | | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [6] | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended | **[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,12 +86,6 @@ 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]:** If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. - -**[5]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. - -**[6]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. - `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. | Value | Description | diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 739ff7b65c4..08c4bafa915 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -144,7 +144,7 @@ The following operations related to messages are defined for these semantic conv | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | **[1]:** If the message destination is either a `queue` or `topic`. diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 3d513a6f5db..22c1108f756 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -66,7 +66,7 @@ Examples of span names: | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended: [5] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | **[1]:** This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The `code.namespace` attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side). diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 50e32476e5b..24500d20501 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -44,12 +44,12 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | `net.peer.ip` | string | Remote address of the logical peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended | -| `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended | +| `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended: [2] | | `net.sock.peer.addr` | 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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| `net.sock.peer.port` | int | Remote socket peer port (if defined for the address family). | `16456` | Recommended | -| `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` | Conditionally Required: [2] | -| `net.peer.name` | string | Logical remote hostname, see note below. [3] | `example.com` | Recommended | +| `net.sock.peer.port` | int | Remote socket peer port. | `16456` | Recommended: [3] | +| `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` | Conditionally Required: [4] | +| `net.peer.name` | string | Logical remote hostname, see note below. [5] | `example.com` | Recommended | | `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | Recommended | | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended | @@ -64,9 +64,13 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[1]:** `net.app.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`. -**[2]:** if different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set +**[2]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. -**[3]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[3]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. + +**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. + +**[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. `net.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. @@ -86,7 +90,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties |---|---| | `inet` | IPv4 address | | `inet6` | IPv6 address | -| `unix` | Unix domain socket path/ | +| `unix` | Unix domain socket path | `net.host.connection.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. From 8a392dfa99889fa7b38a3ad597f7a143f1332159 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 6 Jul 2022 14:17:23 -0700 Subject: [PATCH 08/11] Adopt latest buildtools and review comments --- .vscode/settings.json | 2 +- Makefile | 2 +- internal/tools/schema_check.sh | 2 +- semantic_conventions/README.md | 6 +++--- semantic_conventions/trace/database.yaml | 6 +----- semantic_conventions/trace/general.yaml | 8 +------- semantic_conventions/trace/messaging.yaml | 4 ---- .../metrics/semantic_conventions/http-metrics.md | 1 + specification/metrics/semantic_conventions/rpc.md | 2 +- .../trace/semantic_conventions/database.md | 14 ++++++++------ specification/trace/semantic_conventions/http.md | 12 +++++++++--- .../trace/semantic_conventions/messaging.md | 12 +++++++----- specification/trace/semantic_conventions/rpc.md | 4 ++-- .../trace/semantic_conventions/span-general.md | 3 +-- 14 files changed, 37 insertions(+), 41 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index b9c897ec50b..27fbbfb0945 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -10,7 +10,7 @@ "MD040": false, }, "yaml.schemas": { - "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.12.0/semantic-conventions/semconv.schema.json": [ + "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.12.1/semantic-conventions/semconv.schema.json": [ "semantic_conventions/**/*.yaml" ] }, diff --git a/Makefile b/Makefile index 62ed0daa6eb..9b411918f60 100644 --- a/Makefile +++ b/Makefile @@ -8,7 +8,7 @@ MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! -SEMCONVGEN_VERSION=0.12.0 +SEMCONVGEN_VERSION=0.12.1 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all diff --git a/internal/tools/schema_check.sh b/internal/tools/schema_check.sh index 624a1d6d202..f9b1826a629 100755 --- a/internal/tools/schema_check.sh +++ b/internal/tools/schema_check.sh @@ -6,7 +6,7 @@ set -e -BUILD_TOOL_SCHEMAS_VERSION=0.12.0 +BUILD_TOOL_SCHEMAS_VERSION=0.12.1 # List of vesions that do not require or have a schema. declare -a skip_versions=("1.0.0" "1.0.1" "1.1.0" "1.2.0" "1.3.0" "1.6.0") diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index 596e23fce78..758d59ac687 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -17,12 +17,12 @@ i.e.: Semantic conventions for the spec MUST adhere to the [attribute naming](../specification/common/attribute-naming.md) and [requirement level](../specification/common/attribute-requirement-level.md) conventions. -Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions/syntax.md) +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.12.1/semantic-conventions/syntax.md) for how to write the YAML files for semantic conventions and what the YAML properties mean. A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to -[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions/README.md) for what extension you need. +[the generator README](https://github.com/open-telemetry/build-tools/tree/v0.12.1/semantic-conventions/README.md) for what extension you need. ## Generating markdown @@ -33,7 +33,7 @@ formatted Markdown tables for all semantic conventions in the specification. Run make table-generation ``` -For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.12.0/semantic-conventions) +For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.12.1/semantic-conventions) in the OpenTelemetry build tools repository. Using this build tool, it is also possible to generate code for use in OpenTelemetry language projects. diff --git a/semantic_conventions/trace/database.yaml b/semantic_conventions/trace/database.yaml index 307ce16ad8f..8c9bbda10ed 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -222,17 +222,13 @@ groups: - ref: net.peer.port tag: connection-level requirement_level: - conditionally_required: If using a port other than the default port for this DBMS. + conditionally_required: If using a port other than the default port for this DBMS and if `net.peer.name` is set. - ref: net.sock.peer.addr tag: connection-level - ref: net.sock.peer.port - requirement_level: - recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. tag: connection-level - ref: net.sock.family tag: connection-level - requirement_level: - conditionally_required: If and only if `net.sock.peer.addr` is set. - ref: net.sock.peer.name requirement_level: recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index e2f269a3fcf..42ba9e428cf 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -39,12 +39,6 @@ groups: `net.app.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.ip - type: string - brief: > - Remote address of the logical peer (dotted decimal for IPv4 or - [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) - examples: '127.0.0.1' - id: sock.peer.name type: string brief: Remote socket peer name. @@ -84,7 +78,7 @@ groups: of this document. brief: > Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. - examples: ['AF_INET', 'AF_BLUETOOTH'] + examples: ['inet6', 'bluetooth'] - id: peer.name type: string brief: 'Logical remote hostname, see note below.' diff --git a/semantic_conventions/trace/messaging.yaml b/semantic_conventions/trace/messaging.yaml index 7e9411937ca..88d1c8c1432 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -75,13 +75,9 @@ groups: - ref: net.sock.peer.addr tag: connection-level - ref: net.sock.peer.port - requirement_level: - recommended: If different than `net.peer.port` and if `net.sock.peer.addr` is set. tag: connection-level - ref: net.sock.family tag: connection-level - requirement_level: - conditionally_required: If and only if `net.sock.peer.addr` is set. - ref: net.sock.peer.name tag: connection-level requirement_level: diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 5eab40ea73f..e8008e8b971 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -101,6 +101,7 @@ 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.sock.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. diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index fc032b2a889..53d407b3843 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -71,7 +71,7 @@ measurements. | [`rpc.method`](../../trace/semantic_conventions/rpc.md) | string | The name of the (logical) method being called, must be equal to the $method part in the span name. [2] | `exampleMethod` | Recommended | | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: See below | -| [`net.sock.family`](../../trace/semantic_conventions/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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | +| [`net.sock.family`](../../trace/semantic_conventions/span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`net.sock.peer.addr`](../../trace/semantic_conventions/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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index fd0a6f677b7..f73cd6c284f 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -44,19 +44,21 @@ Some database systems may allow a connection to switch to a different `db.user`, | `db.user` | string | Username for accessing the database. | `readonly_user`; `reporting_user` | Recommended | | [`net.peer.name`](span-general.md) | string | Name of the database host. [1] | `example.com` | Conditionally Required: See alternative attributes below. | | [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: [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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | +| [`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. | `inet6`; `bluetooth` | Conditionally Required: [3] | | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [3] | -| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [4] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] | +| [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [5] | **[1]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. -**[2]:** If using a port other than the default port for this DBMS. +**[2]:** If using a port other than the default port for this DBMS and if `net.peer.name` is set. -**[3]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. +**[3]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. -**[4]:** If database type is in-process (`"inproc"`), recommended for other database types. +**[4]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. + +**[5]:** If database type is in-process (`"inproc"`), recommended for other database types. **Additional attribute requirements:** At least one of the following sets of attributes is required: diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index aaebc20d74b..d6d643f1c13 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -74,11 +74,11 @@ 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` | Recommended | | `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` | Recommended | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. | -| [`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` | Recommended | +| [`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. | `inet6`; `bluetooth` | Conditionally Required: [4] | | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] | **[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,6 +86,12 @@ 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]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. + +**[5]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. + +**[6]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. + `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. | Value | Description | diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 08c4bafa915..22c55bed15c 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -140,11 +140,11 @@ The following operations related to messages are defined for these semantic conv | `messaging.message_payload_size_bytes` | int | The (uncompressed) size of the message payload in bytes. Also use this attribute if it is unknown whether the compressed or uncompressed payload size is reported. | `2738` | Recommended | | `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended | | [`net.peer.name`](span-general.md) | string | Logical remote hostname, see note below. [3] | `example.com` | Conditionally Required: If available. | -| [`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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | +| [`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. | `inet6`; `bluetooth` | Conditionally Required: [4] | | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | -| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | -| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | +| [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | +| [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] | **[1]:** If the message destination is either a `queue` or `topic`. @@ -152,9 +152,11 @@ The following operations related to messages are defined for these semantic conv **[3]:** This should be the IP/hostname of the broker (or other network-level peer) this specific message is sent to/received from. -**[4]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. +**[4]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. -**[5]:** If different than `net.peer.port` and if `net.sock.peer.addr` is set. +**[5]:** If different than `net.peer.name` and if `net.sock.peer.addr` is set. + +**[6]:** If defined for the address family and if different than `net.peer.port` and if `net.sock.peer.addr` is set. `messaging.destination_kind` MUST be one of the following: diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 22c1108f756..811e2e8a009 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -62,7 +62,7 @@ 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. [2] | `exampleMethod` | Recommended | | [`net.peer.name`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | | [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: 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` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | +| [`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. | `inet6`; `bluetooth` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | | [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | @@ -120,7 +120,7 @@ Generally, a user SHOULD NOT set `peer.service` to a fully qualified RPC service | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | [`net.host.name`](span-general.md) | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | -| [`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` | Conditionally Required: [1] | +| [`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. | `inet6`; `bluetooth` | Conditionally Required: [1] | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | | [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended: [2] | diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 24500d20501..23e067fc9b8 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -43,12 +43,11 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.transport` | string | Transport protocol used. See note below. | `ip_tcp` | Recommended | | `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | -| `net.peer.ip` | string | Remote address of the logical peer (dotted decimal for IPv4 or [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) | `127.0.0.1` | Recommended | | `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended: [2] | | `net.sock.peer.addr` | 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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | | `net.sock.peer.port` | int | Remote socket peer port. | `16456` | Recommended: [3] | -| `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` | Conditionally Required: [4] | +| `net.sock.family` | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [4] | | `net.peer.name` | string | Logical remote hostname, see note below. [5] | `example.com` | Recommended | | `net.peer.port` | int | Logical remote port number | `80`; `8080`; `443` | Recommended | | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | From 59ddd4119ef392870388634b0cfe68e09cf8eeaf Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 6 Jul 2022 17:40:52 -0700 Subject: [PATCH 09/11] nits and clarify that net.peer.name is client-only, net.host.name is server only --- specification/trace/semantic_conventions/span-general.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index 23e067fc9b8..b9696bb5f66 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -139,7 +139,7 @@ Semantic conventions and instrumentations that populate both logical (`net.peer. #### `net.peer.name` -For IP-based communication, the name should be a DNS host name. +For IP-based communication, the name should be a DNS host name of the remote service. `net.peer.name` should be the name of logical remote destination, e.g., `"example.com"` if connecting to an URL `https://example.com/foo`. Usually, application pass it as configuration to client libraries in form of URL, connection string, host name, etc. @@ -153,12 +153,16 @@ the name should explicitly be set to the empty string to distinguish it from the For Unix domain socket, `net.sock.peer.addr` attribute represents destination name and `net.peer.name` SHOULD NOT be set. +`net.peer.name` and `net.peer.port` apply to client instrumentations only. Server instrumentations SHOULD NOT set these attributes. + #### `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. +`net.host.name` and `net.host.port` apply to server instrumentations only. Client instrumentations SHOULD NOT set these attributes. + ### `net.sock.*` 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._ @@ -174,7 +178,6 @@ _Note: Specific structures and methods to obtain socket-level attributes are men `net.sock.peer.addr`, `net.sock.peer.port` identify remote peer - the address used to connect to the socket. 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, represent `sin_addr` and `sin_port` fields of [`sockaddr_in`](https://man7.org/linux/man-pages/man7/ip.7.html) structure. -Port SHOULD only be populated for families that have notion of port. Address and port can be obtained by calling `getpeername` method on [Linux](https://man7.org/linux/man-pages/man2/getpeername.2.html), [Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getpeername). From 47dffc5c0b09ff46273354da457b56b6b62c6ebe Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 8 Jul 2022 11:58:03 -0700 Subject: [PATCH 10/11] review: req level on net.sock.host.pot and nits --- CHANGELOG.md | 1 - semantic_conventions/trace/general.yaml | 4 +++- semantic_conventions/trace/rpc.yaml | 4 ---- specification/trace/semantic_conventions/http.md | 4 +++- specification/trace/semantic_conventions/rpc.md | 6 +++--- specification/trace/semantic_conventions/span-general.md | 4 +++- 6 files changed, 12 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1b83af455b6..763e6821082 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -47,7 +47,6 @@ release. - Add `http.*.*.size` metric semantic conventions for tracking size of requests / responses for http servers / clients ([#2588](https://github.com/open-telemetry/opentelemetry-specification/pull/2588)). -- BREAKING: rename `net.peer.ip` to `net.sock.peer.addr` and `net.host.ip` to `net.sock.host.addr`. - BREAKING: rename `net.peer.ip` to `net.sock.peer.addr`, `net.host.ip` to `net.sock.host.addr`, `net.peer.name` to `net.sock.peer.name` for socket-level instrumentation. Define socket-level attributes and clarify logical peer and host attributes meaning. diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index 42ba9e428cf..a3eb598e8a4 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -103,7 +103,9 @@ groups: examples: '192.168.0.1' - id: sock.host.port type: int - brief: 'Local socket peer port (if defined for the address family).' + brief: 'Local socket port number.' + requirement_level: + recommended: If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. examples: 35555 - id: host.connection.type type: diff --git a/semantic_conventions/trace/rpc.yaml b/semantic_conventions/trace/rpc.yaml index 9905690ccbc..806a48be04e 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -84,11 +84,7 @@ groups: - ref: net.host.name - ref: net.sock.host.addr - ref: net.sock.host.port - requirement_level: - recommended: If different than `net.host.port` and if `net.sock.host.addr` is set. - ref: net.sock.family - requirement_level: - conditionally_required: If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. - id: rpc.grpc prefix: rpc.grpc diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index d6d643f1c13..858a252bc19 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -250,7 +250,7 @@ If the route cannot be determined, the `name` attribute MUST be set as defined i | [`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 | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | -| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | +| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [5] | **[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. @@ -270,6 +270,8 @@ the closest proxy. **[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]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. + **Additional attribute requirements:** At least one of the following sets of attributes is required: * `http.scheme`, `http.host`, `http.target` diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 811e2e8a009..2fedb8e6dd2 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -122,11 +122,11 @@ 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` | Recommended | | [`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. | `inet6`; `bluetooth` | Conditionally Required: [1] | | [`net.sock.host.addr`](span-general.md) | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | -| [`net.sock.host.port`](span-general.md) | int | Local socket peer port (if defined for the address family). | `35555` | Recommended: [2] | +| [`net.sock.host.port`](span-general.md) | int | Local socket port number. | `35555` | Recommended: [2] | -**[1]:** If and only if `net.sock.peer.addr` or `net.sock.host.addr` are set. +**[1]:** If different than `inet` and if any of `net.sock.peer.addr` or `net.sock.host.addr` are set. Consumers of telemetry SHOULD expect to receive IPv6 address in `net.sock.peer.addr` without `net.sock.family` coming from instrumentations that follow previous versions of this document. -**[2]:** If different than `net.host.port` and if `net.sock.host.addr` is set. +**[2]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. ### Events diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index b9696bb5f66..ca5fd390b12 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -53,7 +53,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.host.name` | string | Logical local hostname or similar, see note below. | `localhost` | Recommended | | `net.host.port` | int | Logical local port number, preferably the one that the peer used to connect | `8080` | Recommended | | `net.sock.host.addr` | string | Local socket address. Useful in case of a multi-IP host.' | `192.168.0.1` | Recommended | -| `net.sock.host.port` | int | Local socket peer port (if defined for the address family). | `35555` | Recommended | +| `net.sock.host.port` | int | Local socket port number. | `35555` | Recommended: [6] | | `net.host.connection.type` | string | The internet connection type currently being used by the host. | `wifi` | Recommended | | `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` | Recommended | | `net.host.carrier.name` | string | The name of the mobile carrier. | `sprint` | Recommended | @@ -71,6 +71,8 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties **[5]:** `net.peer.name` SHOULD NOT be set if capturing it would require an extra DNS lookup. +**[6]:** If defined for the address family and if different than `net.host.port` and if `net.sock.host.addr` is set. + `net.transport` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. | Value | Description | From 18c263136828d10d4e9349e2d511d4215ab4a912 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 12 Jul 2022 13:55:10 -0700 Subject: [PATCH 11/11] Markdown formatting --- semantic_conventions/trace/general.yaml | 4 ++-- specification/metrics/semantic_conventions/rpc.md | 3 +-- specification/trace/semantic_conventions/database.md | 3 +-- specification/trace/semantic_conventions/http.md | 3 +-- specification/trace/semantic_conventions/messaging.md | 3 +-- specification/trace/semantic_conventions/rpc.md | 3 +-- specification/trace/semantic_conventions/span-general.md | 3 +-- 7 files changed, 8 insertions(+), 14 deletions(-) diff --git a/semantic_conventions/trace/general.yaml b/semantic_conventions/trace/general.yaml index a3eb598e8a4..392d06e4519 100644 --- a/semantic_conventions/trace/general.yaml +++ b/semantic_conventions/trace/general.yaml @@ -48,8 +48,8 @@ groups: - id: sock.peer.addr type: string brief: > - 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)). + 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). examples: ['127.0.0.1', '/tmp/mysql.sock' ] - id: sock.peer.port type: int diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md index 53d407b3843..ad5b8b87a73 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -72,8 +72,7 @@ measurements. | [`net.peer.name`](../../trace/semantic_conventions/span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | | [`net.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: See below | | [`net.sock.family`](../../trace/semantic_conventions/span-general.md) | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | -| [`net.sock.peer.addr`](../../trace/semantic_conventions/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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | +| [`net.sock.peer.addr`](../../trace/semantic_conventions/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). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.name`](../../trace/semantic_conventions/span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | | [`net.sock.peer.port`](../../trace/semantic_conventions/span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | | [`net.transport`](../../trace/semantic_conventions/span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | diff --git a/specification/trace/semantic_conventions/database.md b/specification/trace/semantic_conventions/database.md index f73cd6c284f..0ded661e66f 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -45,8 +45,7 @@ Some database systems may allow a connection to switch to a different `db.user`, | [`net.peer.name`](span-general.md) | string | Name of the database host. [1] | `example.com` | Conditionally Required: See alternative attributes below. | | [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: [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. | `inet6`; `bluetooth` | Conditionally Required: [3] | -| [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | +| [`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). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [4] | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: [5] | diff --git a/specification/trace/semantic_conventions/http.md b/specification/trace/semantic_conventions/http.md index 858a252bc19..0466acef3a1 100644 --- a/specification/trace/semantic_conventions/http.md +++ b/specification/trace/semantic_conventions/http.md @@ -75,8 +75,7 @@ Don't set the span status description if the reason can be inferred from `http.s | `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` | Recommended | | `http.retry_count` | int | The ordinal number of request re-sending attempt. | `3` | Recommended: If and only if a request was retried. | | [`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. | `inet6`; `bluetooth` | Conditionally Required: [4] | -| [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`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). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] | diff --git a/specification/trace/semantic_conventions/messaging.md b/specification/trace/semantic_conventions/messaging.md index 22c55bed15c..36d8f2aedf3 100644 --- a/specification/trace/semantic_conventions/messaging.md +++ b/specification/trace/semantic_conventions/messaging.md @@ -141,8 +141,7 @@ The following operations related to messages are defined for these semantic conv | `messaging.message_payload_compressed_size_bytes` | int | The compressed size of the message payload in bytes. | `2048` | Recommended | | [`net.peer.name`](span-general.md) | string | Logical remote hostname, see note below. [3] | `example.com` | Conditionally Required: If available. | | [`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. | `inet6`; `bluetooth` | Conditionally Required: [4] | -| [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| [`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). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [5] | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [6] | diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 2fedb8e6dd2..8a8ead9be1b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -63,8 +63,7 @@ Examples of span names: | [`net.peer.name`](span-general.md) | string | RPC server [host name](https://grpc.github.io/grpc/core/md_doc_naming.html). [3] | `example.com` | Required | | [`net.peer.port`](span-general.md) | int | Logical remote port number | `80`; `8080`; `443` | Conditionally Required: 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. | `inet6`; `bluetooth` | Conditionally Required: If and only if `net.sock.peer.addr` is set. | -| [`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)). | `127.0.0.1`; `/tmp/mysql.sock` | See below | +| [`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). | `127.0.0.1`; `/tmp/mysql.sock` | See below | | [`net.sock.peer.name`](span-general.md) | string | Remote socket peer name. | `proxy.example.com` | Recommended: [4] | | [`net.sock.peer.port`](span-general.md) | int | Remote socket peer port. | `16456` | Recommended: [5] | | [`net.transport`](span-general.md) | string | Transport protocol used. See note below. | `ip_tcp` | Conditionally Required: See below | diff --git a/specification/trace/semantic_conventions/span-general.md b/specification/trace/semantic_conventions/span-general.md index ca5fd390b12..84d561b8c16 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -44,8 +44,7 @@ the `net.peer.*` properties of a client are equal to the `net.host.*` properties | `net.app.protocol.name` | string | Application layer protocol used. The value SHOULD be normalized to lowercase. | `amqp`; `http`; `mqtt` | Recommended | | `net.app.protocol.version` | string | Version of the application layer protocol used. See note below. [1] | `3.1.1` | Recommended | | `net.sock.peer.name` | string | Remote socket peer name. | `proxy.example.com` | Recommended: [2] | -| `net.sock.peer.addr` | 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)). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | +| `net.sock.peer.addr` | 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). | `127.0.0.1`; `/tmp/mysql.sock` | Recommended | | `net.sock.peer.port` | int | Remote socket peer port. | `16456` | Recommended: [3] | | `net.sock.family` | string | Protocol [address family](https://man7.org/linux/man-pages/man7/address_families.7.html) which is used for communication. | `inet6`; `bluetooth` | Conditionally Required: [4] | | `net.peer.name` | string | Logical remote hostname, see note below. [5] | `example.com` | Recommended |