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/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 72dd7fbd48..fa45a654b7 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -79,7 +79,6 @@ body: - area:opentracing - area:os - area:otel - - area:peer - area:pprof - area:process - area:profile diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 9920af2bc9..46649ec48b 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -71,7 +71,6 @@ body: - area:opentracing - area:os - area:otel - - area:peer - area:pprof - area:process - area:profile diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 007cbe2ddd..736e8d6453 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -82,7 +82,6 @@ body: - area:opentracing - area:os - area:otel - - area:peer - area:pprof - area:process - area:profile diff --git a/docs/general/attributes.md b/docs/general/attributes.md index 98cc6e7741..02a9885c52 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) @@ -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. + + + + + + +**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` | + + + + + +### 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)
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/peer.md b/docs/registry/attributes/peer.md index 85825c22d1..414bdc0bb8 100644 --- a/docs/registry/attributes/peer.md +++ b/docs/registry/attributes/peer.md @@ -11,7 +11,7 @@ These attribute may be used for any operation that accesses some remote service. | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | -| `peer.service` | ![Development](https://img.shields.io/badge/-development-blue) | 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` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by `service.peer.name`. | 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 index 06a779a981..f5e94ad619 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. @@ -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 | +| --- | --- | --- | --- | --- | +| `service.peer.name` | ![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` | +| `service.peer.namespace` | ![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 index 53807af234..45a5311df0 100644 --- a/model/peer/common.yaml +++ b/model/peer/common.yaml @@ -4,4 +4,3 @@ groups: brief: "Operations that access some remote service." attributes: - ref: peer.service - requirement_level: recommended diff --git a/model/peer/registry.yaml b/model/peer/registry.yaml index 444a8ea5f1..05444a3840 100644 --- a/model/peer/registry.yaml +++ b/model/peer/registry.yaml @@ -11,6 +11,9 @@ groups: - id: peer.service type: string stability: development + deprecated: + reason: renamed + renamed_to: service.peer.name brief: > The [`service.name`](/docs/resource/README.md#service) of the remote service. SHOULD be equal to the actual `service.name` diff --git a/model/service/common.yaml b/model/service/common.yaml new file mode 100644 index 0000000000..9066de9441 --- /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 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 index 9eeb1972d5..85f2a96533 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"]