Introduce service.peer.name and service.peer.namespace; deprecate peer.service

mmanciop · mmanciop · commit 7a07a6e5e03e · 2025-12-11T10:51:40.000+01:00
diff --git a/.chloggen/peer-service-deprecation.yaml b/.chloggen/peer-service-deprecation.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: peer
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: The `peer.service` attribute has been deprecated in favor of `service.peer.name`.
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [2945]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: The `peer.service` attribute has been renamed to `service.peer.name` to align with the `service.{name|namespace}` resource attributes.
diff --git a/.chloggen/service-peer.yaml b/.chloggen/service-peer.yaml
@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: service
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "`service.peer.name` and `service.peer.namespace` have been introduced as the replacement for `peer.service` to describe remote services that use both a name and a namespace."
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [2945]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: The `peer.service` attribute could not fully represent the `service.{name|namespace}` resource attributes; `service.peer.name` and `service.peer.namespace` provide a more complete representation.
diff --git a/docs/general/attributes.md b/docs/general/attributes.md
@@ -29,6 +29,8 @@ Particular operations may refer to or require some of these attributes.
         - [Client/server example with forward proxy](#clientserver-example-with-forward-proxy)
     - [Network connection and carrier attributes](#network-connection-and-carrier-attributes)
 - [General remote service attributes](#general-remote-service-attributes)
+  - [Service Peer](#service-peer)
+  - [Peer namespace](#peer-namespace)
 - [General thread attributes](#general-thread-attributes)
 - [Source code attributes](#source-code-attributes)
 
@@ -349,7 +351,32 @@ For `Unix` and `pipe`, since the connection goes over the file system instead of
 
 ## General remote service attributes
 
-This attribute may be used for any operation that accesses some remote service.
+### Service Peer
+
+Attributes of the `service.peer.*` namespace may also be used for any operation that accesses some remote service.
+Users can define what the name of a service is based on their particular semantics in their distributed system.
+Instrumentations SHOULD provide a way for users to configure this name.
+
+<!-- semconv service.peer -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+
+**Attributes:**
+
+| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- | --- |
+| [`service.peer.name`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | Logical name of the service on the other side of the connection. SHOULD be equal to the actual [`service.name`](/docs/resource/README.md#service) resource attribute of the remote service if any. | `shoppingcart` |
+| [`service.peer.namespace`](/docs/registry/attributes/service.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A namespace for `service.peer.name`. | `Shop` |
+
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Peer namespace
+
+Attributes of the `peer.*` namespace are deprecated, and they used to provide a way to describe any operation that accesses some remote service.
+The `peer.service` attribute harkens back from OpenTracing, and has not been updated to match the `service.name` and `service.namespace` resource attributes to describe a service.
 Users can define what the name of a service is based on their particular semantics in their distributed system.
 Instrumentations SHOULD provide a way for users to configure this name.
 
@@ -362,7 +389,7 @@ Instrumentations SHOULD provide a way for users to configure this name.
 
 | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
 | --- | --- | --- | --- | --- | --- |
-| [`peer.service`](/docs/registry/attributes/peer.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. [1] | `AuthTokenCache` |
+| [`peer.service`](/docs/registry/attributes/peer.md) | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by `service.peer.name`. | `Recommended` | string | The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` resource attribute of the remote service if any. [1] | `AuthTokenCache` |
 
 **[1] `peer.service`:** Examples of `peer.service` that users may specify:
 
diff --git a/docs/registry/attributes/service.md b/docs/registry/attributes/service.md
@@ -3,6 +3,9 @@
 
 # Service
 
+- [Service Attributes](#service-attributes)
+- [Service Attributes for Peer Services](#service-attributes-for-peer-services)
+
 ## Service Attributes
 
 A service instance.
@@ -46,3 +49,14 @@ port.
 **[2] `service.name`:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`.
 
 **[3] `service.namespace`:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
+
+## Service Attributes for Peer Services
+
+How to describe the service on the other side of a request.
+
+**Attributes:**
+
+| Key | Stability | Value Type | Description | Example Values |
+| --- | --- | --- | --- | --- |
+| <a id="service-peer-name" href="#service-peer-name">`service.peer.name`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | Logical name of the service on the other side of the connection. SHOULD be equal to the actual [`service.name`](/docs/resource/README.md#service) resource attribute of the remote service if any. | `shoppingcart` |
+| <a id="service-peer-namespace" href="#service-peer-namespace">`service.peer.namespace`</a> | ![Development](https://img.shields.io/badge/-development-blue) | string | A namespace for `service.peer.name`. | `Shop` |
diff --git a/model/peer/common.yaml b/model/peer/common.yaml
@@ -4,4 +4,6 @@ groups:
     brief: "Operations that access some remote service."
     attributes:
       - ref: peer.service
-        requirement_level: recommended
+        deprecated:
+          reason: renamed
+          renamed_to: service.peer.name
diff --git a/model/peer/deprecated/registry-deprecated.yaml b/model/peer/deprecated/registry-deprecated.yaml
diff --git a/model/service/common.yaml b/model/service/common.yaml
@@ -0,0 +1,9 @@
+groups:
+  - id: service.peer
+    type: attribute_group
+    brief: "Operations that access some remote service MAY fill out these attributes to describe that remote service."
+    attributes:
+      - ref: service.peer.name
+        requirement_level: recommended
+      - ref: service.peer.namespace
+        requirement_level: recommended
diff --git a/model/service/registry.yaml b/model/service/registry.yaml
@@ -69,3 +69,22 @@ groups:
           for that telemetry. This is typically the case for scraping receivers, as they know the target address and
           port.
         examples: ["627cc493-f310-47de-96bd-71410b7dec09"]
+  - id: registry.service.peer
+    type: attribute_group
+    display_name: Service Attributes for Peer Services
+    brief: >
+      How to describe the service on the other side of a request.
+    attributes:
+      - id: service.peer.name
+        type: string
+        stability: development
+        brief: >
+          Logical name of the service on the other side of the connection.
+          SHOULD be equal to the actual [`service.name`](/docs/resource/README.md#service) resource attribute of the remote service if any.
+        examples: ["shoppingcart"]
+      - id: service.peer.namespace
+        type: string
+        stability: development
+        brief: >
+          A namespace for `service.peer.name`.
+        examples: ["Shop"]
