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

mmanciop · 2025-11-17T17:06:04Z

Changes

The goals of this PR are twofold.

Goal 1: Stabilization

Renaming peer.service is necessary for stabilization: the same way the SIG renamed deployment.environment to deployment.environment.name, the lack of extensibility of peer.service prevents its stabilization.

The extensibility of service.peer.* is itself important because of the next goal.

Goal 2: Provide means of fully describing service identity

Today's peer.service is meant to contain the same value of the service.name attribute of the service on the other end of communication. However, service.name by itself does not actually suffice to identify every service, because of the existence and adoption of service.namespace:

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.

(From https://opentelemetry.io/docs/specs/semconv/resource/#service)

That is, in order to allow "references" to a service, we need to be able to also add service.peer.namespace.

The importance of service.peer.namespace is directly related with the adoption of service.namespace. I pulled statistics across the entirety of the use-base of Dash0, and almost exactly 1/3 of organizations (which equate to a "user site") set service.namespace to one or more of their services. (I admit this came to me as a surprise, I had guess-stimated the adoption to be around 10%). This high adoption, in my eyes, justifies making an exception to the rule about existing implementations.

For the record, about implementations: we intend in Dash0 to automatically add service.peer.name and service.peer.namespace to metrics generated for span pairs connecting services. Which means 1/3 of Dash0 users will automatically adopt these attributes.

Merge requirement checklist

CONTRIBUTING.md guidelines followed.
Change log entry added, according to the guidelines in When to add a changelog entry.
- If your PR does not need a change log, start the PR title with [chore]
Links to the prototypes or existing instrumentations (when adding or changing conventions)

thompson-tomo

PR should be Blocked due to old attributes not actually being deprecated but rather only a single usage of the attribute being deprecated. Also there is 2 change logs when there should only be 1.

If we think about the use of the attributes for me it makes more sense to put these new attributes under the server namespace given that they are being set based on the server address/port.
It would also enable the server namespace to be the sole namespace containing attributes describing the server side of a connection and the service namespace to be describing the service being used.

model/service/registry.yaml

model/peer/common.yaml

mmanciop · 2025-11-18T06:43:33Z

PR should be Blocked due to old attributes not actually being deprecated but rather only a single usage of the attribute being deprecated. Also there is 2 change logs when there should only be 1.

I am trying to figure out how to make this work the right way. Pointers appreciated :-)

If we think about the use of the attributes for me it makes more sense to put these new attributes under the server namespace given that they are being set based on the server address/port.

IMO, it is really not a given that these are set on server address/port. It is difficult to generalize on something like this, and it is going to be very implementation-dependent, but more than one implementation of peer.service I have seen happened at a pretty high level, e.g., embedded in client libraries automatically generated from OpenAPI specs.

thompson-tomo · 2025-11-18T07:20:50Z

I am trying to figure out how to make this work the right way. Pointers appreciated

Move the deprecated block from common.yaml into the registry.yaml file and then regenerate the docs. The generation process will propagate the deprecation info onto the attributes on the signals.

IMO, it is really not a given that these are set on server address/port.

This is functionality which is defined via declarative config.

I have seen happened at a pretty high level, e.g., embedded in client libraries automatically generated from OpenAPI specs.

That would also be fine and still fit having it under server as server would be describing the remote side of the connection.

trask · 2025-11-21T16:48:46Z

hi @mmanciop!

thanks for taking this on.

we discussed this in yesterday's Service and Deployment Semconv SIG meeting (https://zoom.us/rec/share/W7L9lhkmwN6GGzh1ykMxcF-dr2B0frjOAaO52BSe-8VP-Zag6n15gQObv_sFtqM.OCG1dIwmHpD2D2rP starting around 34:00 minute marker).

I believe we're onboard with renaming peer.service to service.peer.name.

We'd like a bit more understanding of whether service.peer.namespace is needed, since we haven't had that previously, and so it would need to go through a bit more prototyping / discussion.

For service.peer.name, we want to make sure we have a clear path towards stabilizing, as we have strong preference for "defacto stable" things like peer.service to only break once when going to (true) stable. Similar to what we did for HTTP and database semconv.

We still need to decide whether we want to recommend OTEL_SEMCONV_STABILITY_OPT_IN as part of this migration.

Can you investigate the existing usages of peer.service in OpenTelemetry repositories? We'd like to understand how widespread the usage is (outside of the Java agent where we know it has decent usage).

Once we decide on the migration and stabilization plan, we want to communicate it via a short blog post, to hopefully avoid the surprises that folks had with the deployment.environment -> deployment.environment.name change.

mmanciop · 2025-12-01T08:47:06Z

hi @mmanciop!

thanks for taking this on.

we discussed this in yesterday's Service and Deployment Semconv SIG meeting (https://zoom.us/rec/share/W7L9lhkmwN6GGzh1ykMxcF-dr2B0frjOAaO52BSe-8VP-Zag6n15gQObv_sFtqM.OCG1dIwmHpD2D2rP starting around 34:00 minute marker).

I believe we're onboard with renaming peer.service to service.peer.name.

Very nice!

We'd like a bit more understanding of whether service.peer.namespace is needed, since we haven't had that previously, and so it would need to go through a bit more prototyping / discussion.

The identity of a service is the combination of its service.name and, if set, its service.namespace. From https://opentelemetry.io/docs/specs/semconv/resource/:

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).

The canonical example in my head is the frontend service: most complex systems have one, and this is where the service.namespace kicks in. If the service on the other side cannot say which application is talking to, but just that it is "some frontend", that nuance is lost.

For service.peer.name, we want to make sure we have a clear path towards stabilizing, as we have strong preference for "defacto stable" things like peer.service to only break once when going to (true) stable. Similar to what we did for HTTP and database semconv.

We still need to decide whether we want to recommend OTEL_SEMCONV_STABILITY_OPT_IN as part of this migration.

Can you investigate the existing usages of peer.service in OpenTelemetry repositories? We'd like to understand how widespread the usage is (outside of the Java agent where we know it has decent usage).

Sure, I had already done the research before coming up with the proposal, and I just spent some more time with GitHuib search to make sure I did not miss anything. To my knowledge, the list is as follow, going through SDKs and contribs in alphabetical order:

C++: Found nothing relevant
Erlang: Found nothing relevant
Go: There's some examples in contrib, but I do not see any automation built into the SDK or instrumentations
Java: Various Java instrumentations can automatically add peer.service based on configurable mappings of peer services (see e.g. PeerServiceResolverImpl). These functionalities are in incubation.
JS: Found nothing relevant
.NET: Found nothing relevant, besides the Zipkin exporter mentioned below
PHP: Found nothing relevant, besides the Zipkin exporter mentioned below
Python: Found nothing relevant
Ruby: Some instrumentations allow to configure peer.service
Rust: Found nothing relevant
Collector:
- Datadog exporter in the collector, which is used to generate metrics about how services interact, and peer.service is one of the dimensions. It is opt-in.
- Service Graph Connector (in alpha) uses peer.service as a way to look up connections. From the code, it seems to me it is the default way it uses, but I am not quite sure.
- The AWS XRay Exporter uses peer.service as a fallback for naming segments.

Others:

Zipkin exporters, e.g., the .NET one of the [PHP one] (https://github.com/open-telemetry/opentelemetry-php/blob/569eac08ce735a945fee5719c010580f1c90d304/src/Contrib/Zipkin/SpanConverter.php#L31), use peer.service (and other fallbacks based on server.* and other semconvs) to determine the remote endpoint, which in turn, AFAICT, is used by Zipkin's dependency graph. However, Zipkin exporters are deprecated.

Once we decide on the migration and stabilization plan, we want to communicate it via a short blog post, to hopefully avoid the surprises that folks had with the deployment.environment -> deployment.environment.name change.

Sounds good to me.

I also think that adding one more fallback case for service.peer.name to most of the projects above is not difficult. There is, however, the fact that their semantics of service identity is going to be incomplete anyhow if the logic is not extended to also support service.peer.namespace. But I suspect most stakeholders will answer with "service.namespace, what's that?".

github-actions · 2025-12-01T14:32:51Z

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

peer
peer

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

model/service/registry.yaml

model/service/common.yaml

…r.service

lmolkova · 2025-12-15T16:21:41Z

.chloggen/peer-service-deprecation.yaml

+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`.


SemConv SIG discussion:

Please update PR description to make a case for service.peer.namespace and some data points on usage (outside of otel org). It does not have to be the same attribute, just the scenario.

For stabilization, we might want to see more real-life usage (of service.peer.namespace in otel or outside of otel org).

trask · 2025-12-16T01:54:45Z

For the record, about implementations: we intend in Dash0 to automatically add service.peer.name and service.peer.namespace to metrics generated for span pairs connecting services.

oh, span-to-metrics is a great use case for capturing these attributes 👍

Service Graph Connector (in alpha) uses peer.service as a way to look up connections. From the code, it seems to me it is the default way it uses, but I am not quite sure.

@mapno, @JaredTan95, @open-telemetry/collector-contrib-approvers we're trying to make a case for service.peer.name (renamed from peer.service) and service.peer.namespace, and it would be great to understand if the Service Graph Connector is using peer.service already and if it would benefit from the rename and addition of service.peer.namespace. Thanks!

axw · 2025-12-16T05:40:17Z

@mapno, @JaredTan95, @open-telemetry/collector-contrib-approvers we're trying to make a case for service.peer.name (renamed from peer.service) and service.peer.namespace, and it would be great to understand if the Service Graph Connector is using peer.service already and if it would benefit from the rename and addition of service.peer.namespace.

It would be good to get confirmation from @mapno and/or @JaredTan95, but from my read:

By default, the connector will create a virtual node in the service graph representing a peer service, based on the presence of one or more of these attributes in a client or server span: peer.service, db.name, db.system. I'm not particularly familiar with this component, but based on my experience working on similar things, this would be for representing an uninstrumented source/destination service.

It should be easy enough to add service.peer.name and service.peer.namespace to the default list, and phase out peer.service.

(FWIW I like the name change. Besides making room for service.peer.namespace, it fits well with network.peer.*)

github-actions · 2025-12-31T03:43:36Z

This PR has been labeled as stale due to lack of activity. It will be automatically closed if there is no further activity over the next 7 days.

mapno · 2026-01-08T17:17:14Z

It should be easy enough to add service.peer.name and service.peer.namespace to the default list, and phase out peer.service.

Sorry for the delay (🎄). Agree, that should be the way forward for the servicegraph processor. No concerns from my side 👍

Copilot

Pull request overview

This PR introduces service.peer.name and service.peer.namespace attributes to replace the deprecated peer.service attribute, enabling full service identity representation that includes both name and namespace.

Key changes:

Introduces service.peer.name and service.peer.namespace as development-stability attributes
Deprecates peer.service with a rename to service.peer.name
Removes area:peer from GitHub issue templates as the peer namespace is being phased out

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
model/service/registry.yaml	Adds registry definitions for `service.peer.name` and `service.peer.namespace` attributes
model/service/common.yaml	Creates new attribute group for service peer attributes with recommended requirement level
model/peer/registry.yaml	Marks `peer.service` as deprecated with rename to `service.peer.name`
model/peer/common.yaml	Removes requirement_level from deprecated `peer.service` attribute reference
docs/registry/attributes/service.md	Auto-generated documentation for new service peer attributes
docs/registry/attributes/peer.md	Updates documentation to show deprecation status of `peer.service`
docs/general/attributes.md	Adds new "Service Peer" section and reorganizes to include deprecated "Peer namespace" section
.github/ISSUE_TEMPLATE/new-conventions.yaml	Removes `area:peer` label option
.github/ISSUE_TEMPLATE/change_proposal.yaml	Removes `area:peer` label option
.github/ISSUE_TEMPLATE/bug_report.yaml	Removes `area:peer` label option
.chloggen/service-peer.yaml	Changelog entry documenting the enhancement
.chloggen/peer-service-deprecation.yaml	Changelog entry documenting the deprecation

docs/general/attributes.md

model/service/registry.yaml

docs/general/attributes.md

model/service/registry.yaml

Co-authored-by: Trask Stalnaker <[email protected]>

trask

@mmanciop thanks for staying with this!

trask · 2026-01-09T16:24:33Z

model/peer/common.yaml

I think this file can be deleted now, I think it was only used by docs/general/attributes.md

trask · 2026-01-09T16:28:00Z

model/peer/registry.yaml

rename to deprecated.yaml (just convention)

trask · 2026-01-09T16:29:14Z

model/service/registry.yaml

+        type: string
+        stability: development
+        brief: >
+          A namespace for `service.peer.name`.


(just to align with service.peer.name definition above)

Suggested change

A namespace for `service.peer.name`.

Logical namespace of the service on the other side of the connection.

trask · 2026-01-09T16:32:02Z

model/service/common.yaml

+      - ref: service.peer.name
+        requirement_level: recommended
+      - ref: service.peer.namespace
+        requirement_level: recommended


I'm not sure it makes a difference here, but I think this would be more accurate (@lmolkova?)

Suggested change

- ref: service.peer.name

requirement_level: recommended

- ref: service.peer.namespace

requirement_level: recommended

- ref: service.peer.name

requirement_level: opt_in

- ref: service.peer.namespace

requirement_level: opt_in

mmanciop requested review from a team as code owners November 17, 2025 17:06

github-project-automation bot added this to Semantic Conventions Triage Nov 17, 2025

github-project-automation bot moved this to Untriaged in Semantic Conventions Triage Nov 17, 2025

mmanciop force-pushed the service_peer branch from 14b1a2b to 6b843a7 Compare November 17, 2025 17:06

thompson-tomo reviewed Nov 18, 2025

View reviewed changes

model/service/registry.yaml Show resolved Hide resolved

model/peer/common.yaml Outdated Show resolved Hide resolved

mmanciop force-pushed the service_peer branch from 6b843a7 to 985629b Compare December 1, 2025 14:32

mmanciop requested a review from a team as a code owner December 1, 2025 14:32

github-actions bot added the triage:rejected:declined label Dec 1, 2025

github-actions bot closed this Dec 1, 2025

trask added triage:accepted:ready and removed triage:rejected:declined labels Dec 1, 2025

trask reopened this Dec 1, 2025

lmolkova moved this from Untriaged to Awaiting codeowners approval in Semantic Conventions Triage Dec 1, 2025

jsuereth reviewed Dec 2, 2025

View reviewed changes

model/service/registry.yaml Show resolved Hide resolved

jsuereth reviewed Dec 2, 2025

View reviewed changes

model/service/common.yaml Outdated Show resolved Hide resolved

mmanciop mentioned this pull request Dec 8, 2025

Improve ease of implementation of service.peer.* #3190

Open

mmanciop force-pushed the service_peer branch 3 times, most recently from 7a07a6e to 4964e08 Compare December 11, 2025 10:01

mmanciop added 2 commits December 15, 2025 17:04

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

b1d09d0

…r.service

Fix templates

51b0ef2

mmanciop force-pushed the service_peer branch from 96f0954 to 51b0ef2 Compare December 15, 2025 16:04

fix yamllint

cd24e25

lmolkova reviewed Dec 15, 2025

View reviewed changes

github-actions bot added the Stale label Dec 31, 2025

github-actions bot closed this Jan 7, 2026

trask removed the Stale label Jan 7, 2026

trask reopened this Jan 7, 2026

trask requested a review from Copilot January 8, 2026 19:13

Copilot started reviewing on behalf of trask January 8, 2026 19:14 View session

Copilot AI reviewed Jan 8, 2026

View reviewed changes

docs/general/attributes.md Outdated Show resolved Hide resolved

model/service/registry.yaml Show resolved Hide resolved

trask reviewed Jan 8, 2026

View reviewed changes

docs/general/attributes.md Outdated Show resolved Hide resolved

docs/general/attributes.md Outdated Show resolved Hide resolved

docs/general/attributes.md Outdated Show resolved Hide resolved

model/service/registry.yaml Show resolved Hide resolved

mmanciop and others added 3 commits January 9, 2026 09:23

Update docs/general/attributes.md

dffdeb8

Co-authored-by: Trask Stalnaker <[email protected]>

Update docs/general/attributes.md

2b0dd06

Co-authored-by: Trask Stalnaker <[email protected]>

Address trask's feedback

42991e5

mmanciop requested a review from trask January 9, 2026 09:42

trask approved these changes Jan 9, 2026

View reviewed changes

Drop dangling link in TOC

b3f0afe

	A namespace for `service.peer.name`.
	Logical namespace of the service on the other side of the connection.

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

mmanciop commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Goal 1: Stabilization

Goal 2: Provide means of fully describing service identity

Merge requirement checklist

Uh oh!

thompson-tomo left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mmanciop commented Nov 18, 2025

Uh oh!

thompson-tomo commented Nov 18, 2025

Uh oh!

trask commented Nov 21, 2025

Uh oh!

mmanciop commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Dec 1, 2025

Uh oh!

Uh oh!

Uh oh!

lmolkova Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

trask commented Dec 16, 2025

Uh oh!

axw commented Dec 16, 2025

Uh oh!

github-actions bot commented Dec 31, 2025

Uh oh!

mapno commented Jan 8, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

trask left a comment

Choose a reason for hiding this comment

Uh oh!

trask Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

trask Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

trask Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

trask Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

mmanciop commented Nov 17, 2025 •

edited

Loading

mmanciop commented Dec 1, 2025 •

edited

Loading

lmolkova Dec 15, 2025 •

edited

Loading