diff --git a/.chloggen/peer-service-deprecation.yaml b/.chloggen/peer-service-deprecation.yaml new file mode 100644 index 0000000000..4ce6a78ec2 --- /dev/null +++ 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 new file mode 100644 index 0000000000..3c0f41c2c6 --- /dev/null +++ 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 index 47ce21231a..3c20552389 100644 --- 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) @@ -355,7 +357,33 @@ 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. + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`service.peer.name`](/docs/registry/attributes/service.md) | 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` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`service.peer.namespace`](/docs/registry/attributes/service.md) | string | A namespace for `service.peer.name`. | `Shop` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +### 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. @@ -368,7 +396,7 @@ Instrumentations SHOULD provide a way for users to configure this name. | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`peer.service`](/docs/registry/attributes/peer.md) | 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. | `AuthTokenCache` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`peer.service`](/docs/registry/attributes/peer.md) | 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. | `AuthTokenCache` | `Recommended` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `service.peer.name`. | diff --git a/docs/registry/attributes/service.md b/docs/registry/attributes/service.md index c8e427eb5d..b6d02bc276 100644 --- 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. @@ -44,3 +47,12 @@ 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. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `service.peer.name` | 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` | ![Development](https://img.shields.io/badge/-development-blue) | +| `service.peer.namespace` | string | A namespace for `service.peer.name`. | `Shop` | ![Development](https://img.shields.io/badge/-development-blue) | diff --git a/model/peer/common.yaml b/model/peer/common.yaml index 53807af234..d0881453b9 100644 --- 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/registry.yaml b/model/peer/deprecated/registry-deprecated.yaml similarity index 100% rename from model/peer/registry.yaml rename to model/peer/deprecated/registry-deprecated.yaml diff --git a/model/service/common.yaml b/model/service/common.yaml new file mode 100644 index 0000000000..5764d53251 --- /dev/null +++ b/model/service/common.yaml @@ -0,0 +1,9 @@ +groups: + - id: service.peer + type: attribute_group + brief: "Operations that access some 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 index 9715378b19..e671a2d679 100644 --- 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"]