From 082207b76839e81b13e111588c4b2279c41af1a9 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 23 Oct 2023 08:19:08 -0700 Subject: [PATCH] Rename/replace `(client|server).socket.(address|port)` attributes with `network.(peer|local).(address|port)`. (#3713) Co-authored-by: Armin Ruech --- CHANGELOG.md | 3 +++ .../common/attribute-requirement-level.md | 2 +- specification/logs/data-model-appendix.md | 4 ++-- specification/trace/sdk_exporters/zipkin.md | 15 +++++++-------- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3eab33d9b87..517e63ac1f1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -35,6 +35,9 @@ release. ### Common +- Rename/replace `(client|server).socket.(address|port)` attributes with `network.(peer|local).(address|port)`. + ([#3713](https://github.com/open-telemetry/opentelemetry-specification/pull/3713)) + ### Supplementary Guidelines ## v1.26.0 (2023-10-10) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 1866c413cab..7f510fe7313 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -52,7 +52,7 @@ All instrumentations MUST populate the attribute when the given condition is sat When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the 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 `Opt-In` requirement level on the attribute. -For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. +For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `network.peer.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. ## Recommended diff --git a/specification/logs/data-model-appendix.md b/specification/logs/data-model-appendix.md index 3b5d20ae51d..8d5df355cda 100644 --- a/specification/logs/data-model-appendix.md +++ b/specification/logs/data-model-appendix.md @@ -387,13 +387,13 @@ When mapping from the unified model to HEC, we apply this additional mapping: %a string Client address - Attributes["client.socket.address"] + Attributes["network.peer.address"] %A string Server address - Attributes["server.socket.address"] + Attributes["network.local.address"] %h diff --git a/specification/trace/sdk_exporters/zipkin.md b/specification/trace/sdk_exporters/zipkin.md index f434be08ad2..013dec94510 100644 --- a/specification/trace/sdk_exporters/zipkin.md +++ b/specification/trace/sdk_exporters/zipkin.md @@ -99,16 +99,15 @@ always available. The following table lists the possible attributes for |---|---|---| |1|peer.service|[OpenTelemetry adopted attribute for remote service.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| |2|server.address|[OpenTelemetry adopted attribute for remote hostname, or similar.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| -|3|server.socket.domain|[OpenTelemetry adopted attribute for remote socket hostname of the peer.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| -|4|server.socket.address & server.socket.port|[OpenTelemetry adopted attribute for remote socket address of the peer.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| -|5|peer.hostname|Remote hostname defined in OpenTracing specification.| -|6|peer.address|Remote address defined in OpenTracing specification.| -|7|db.name|Commonly used database name attribute for DB Spans.| +|3|network.peer.address & network.peer.port|[OpenTelemetry adopted attribute for remote socket address of the peer.](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attributes.md#server-client-and-shared-network-attributes)| +|4|peer.hostname|Remote hostname defined in OpenTracing specification.| +|5|peer.address|Remote address defined in OpenTracing specification.| +|6|db.name|Commonly used database name attribute for DB Spans.| * Ranking should control the selection order. For example, `server.address` (Rank - 2) should be selected before `peer.address` (Rank 6). -* `server.socket.domain` and `server.socket.address` can be used by themselves as `remoteEndpoint` but should be combined - with `server.socket.port` if it is also present. + 2) should be selected before `peer.address` (Rank 5). +* `network.peer.address` can be used by itself as `remoteEndpoint` but should be combined + with `network.peer.port` if it is also present. #### Zipkin -> OTLP