From 0b45213858e23aedb6f6de5fab17d2843a9f24c5 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 13 Jul 2022 10:01:44 -0700 Subject: [PATCH] Define net.sock attributes and clarify logical net.peer|host.name attributes (#2614) --- .vscode/settings.json | 2 +- CHANGELOG.md | 4 + Makefile | 2 +- internal/tools/schema_check.sh | 2 +- schemas/1.12.0 | 6 + semantic_conventions/README.md | 6 +- semantic_conventions/trace/database.yaml | 17 ++- semantic_conventions/trace/general.yaml | 80 ++++++++--- semantic_conventions/trace/http.yaml | 57 ++++++-- semantic_conventions/trace/messaging.yaml | 11 +- semantic_conventions/trace/rpc.yaml | 24 +++- .../common/attribute-requirement-level.md | 2 +- .../semantic_conventions/http-metrics.md | 4 +- .../metrics/semantic_conventions/rpc.md | 19 ++- .../trace/semantic_conventions/database.md | 26 ++-- .../trace/semantic_conventions/http.md | 99 ++++++++----- .../trace/semantic_conventions/messaging.md | 13 +- .../trace/semantic_conventions/rpc.md | 27 +++- .../semantic_conventions/span-general.md | 133 +++++++++++++++--- 19 files changed, 398 insertions(+), 136 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/CHANGELOG.md b/CHANGELOG.md index 4f1c9dc0846..73f4b7e39c5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,6 +49,10 @@ 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`, `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)) ### Compatibility 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/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/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 31bb41fa28e..8c9bbda10ed 100644 --- a/semantic_conventions/trace/database.yaml +++ b/semantic_conventions/trace/database.yaml @@ -217,14 +217,21 @@ groups: tag: connection-level requirement_level: conditionally_required: See alternative attributes below. - - ref: net.peer.ip + brief: > + Name of the database host. + - ref: net.peer.port tag: connection-level requirement_level: - conditionally_required: See alternative attributes below. - - ref: net.peer.port + 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 + tag: connection-level + - ref: net.sock.family tag: connection-level + - ref: net.sock.peer.name requirement_level: - conditionally_required: If using a port other than the default port for this DBMS. + recommended: If different than `net.peer.name` and if `net.sock.peer.addr` is set. - ref: net.transport tag: connection-level requirement_level: @@ -232,7 +239,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..392d06e4519 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.' @@ -45,34 +39,74 @@ 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 + - 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 brief: > - Remote address of the peer (dotted decimal for IPv4 or - [RFC5952](https://tools.ietf.org/html/rfc5952) for IPv6) - examples: '127.0.0.1' - - id: peer.port + 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 - brief: 'Remote port number.' - examples: [80, 8080, 443] + 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: + allow_custom_values: true + members: + - id: inet + value: 'inet' + brief: "IPv4 address" + - id: inet6 + value: 'inet6' + brief: "IPv6 address" + - id: unix + value: 'unix' + 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. + 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: ['inet6', '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: Local socket address. Useful in case of a multi-IP host.' + examples: '192.168.0.1' + - id: sock.host.port + type: int + 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: allow_custom_values: true diff --git a/semantic_conventions/trace/http.yaml b/semantic_conventions/trace/http.yaml index e4c4c4adb10..b06694b6289 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.peer.name + - ref: net.sock.family + constraints: - include: network @@ -129,13 +130,29 @@ 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] - + - [http.scheme, net.sock.peer.addr, net.sock.peer.port, http.target] - id: http.server prefix: http extends: http @@ -163,18 +180,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..88d1c8c1432 100644 --- a/semantic_conventions/trace/messaging.yaml +++ b/semantic_conventions/trace/messaging.yaml @@ -72,10 +72,17 @@ 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 + - ref: net.sock.peer.port + tag: connection-level + - ref: net.sock.family + tag: connection-level + - ref: net.sock.peer.name tag: connection-level requirement_level: - conditionally_required: If available. + 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 6ca4a990461..806a48be04e 100644 --- a/semantic_conventions/trace/rpc.yaml +++ b/semantic_conventions/trace/rpc.yaml @@ -45,8 +45,24 @@ 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 + 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: > + 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 @@ -55,7 +71,7 @@ groups: conditionally_required: See below constraints: - any_of: - - net.peer.ip + - net.sock.peer.addr - net.peer.name - include: network @@ -66,7 +82,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..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.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.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/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index adfa821c9de..e8008e8b971 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,7 @@ 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` +* `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 06b75ab252c..ad5b8b87a73 100644 --- a/specification/metrics/semantic_conventions/rpc.md +++ b/specification/metrics/semantic_conventions/rpc.md @@ -69,20 +69,27 @@ 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 | 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.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 | **[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]:** 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.peer.ip`](../../trace/semantic_conventions/span-general.md) +* [`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. @@ -96,7 +103,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..0ded661e66f 100644 --- a/specification/trace/semantic_conventions/database.md +++ b/specification/trace/semantic_conventions/database.md @@ -42,21 +42,27 @@ 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 | 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.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 database type is in-process (`"inproc"`), recommended for other database types. +**[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 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: * [`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 +222,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 +232,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 +257,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..0466acef3a1 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. | `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: [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/`. @@ -83,6 +85,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 | @@ -101,11 +109,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 [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 @@ -122,7 +128,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 @@ -147,25 +153,31 @@ 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` +* `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: * [`net.peer.name`](span-general.md) +* [`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.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 +246,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 | 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 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. -**[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]:** 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` * `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. @@ -268,32 +295,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"` | -| `net.peer.ip` | `"192.0.2.5"` | -| `http.status_code` | `200` | +| 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` | 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"` | -| `net.peer.ip` | `"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"` | +| 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"` | 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 d08fc0fed0c..36d8f2aedf3 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. | `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: [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`. @@ -148,6 +151,12 @@ 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 `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.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: | Value | Description | diff --git a/specification/trace/semantic_conventions/rpc.md b/specification/trace/semantic_conventions/rpc.md index 6cbee348d7b..8a8ead9be1b 100644 --- a/specification/trace/semantic_conventions/rpc.md +++ b/specification/trace/semantic_conventions/rpc.md @@ -60,20 +60,27 @@ 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 | 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.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 | **[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]:** 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.peer.ip`](span-general.md) +* [`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. @@ -111,8 +118,14 @@ 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. | `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 port number. | `35555` | Recommended: [2] | + +**[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 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 fc0e07185dc..84d561b8c16 100644 --- a/specification/trace/semantic_conventions/span-general.md +++ b/specification/trace/semantic_conventions/span-general.md @@ -12,7 +12,13 @@ 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) - [General thread attributes](#general-thread-attributes) @@ -37,12 +43,16 @@ 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.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. | `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 | +| `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 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 | @@ -52,22 +62,36 @@ 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]:** If available and different than `net.peer.name` and if `net.sock.peer.addr` is set. -`net.transport` MUST be one of the following: +**[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. + +**[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 | |---|---| | `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 | +|---|---| +| `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. | Value | Description | @@ -107,22 +131,87 @@ 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 -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. +`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 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. -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` + +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. + +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.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._ + +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 environment or sockets implementations._ + +#### Peer + +`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. + +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` 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, 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. + +Address and port can be obtained by calling `getsockname` method on [Linux](https://man7.org/linux/man-pages/man2/getsockname.2.html), +[Windows](https://docs.microsoft.com/windows/win32/api/winsock2/nf-winsock2-getsockname). + +#### Connecting through intermediary + +When connecting to the remote destination through an intermediary (e.g. proxy), client instrumentations SHOULD set `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. + ## General remote service attributes This attribute may be used for any operation that accesses some remote service.