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

[mmanciop]

Fixes #2945

Changes

Please provide a brief description of the changes here.

Important

Pull requests acceptance are subject to the triage process as described in Issue and PR Triage Management.
PRs that do not follow the guidance above, may be automatically rejected and closed.

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.

[thompson-tomo]

Suggested change

	- 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"]
	- id: server.service.name
	type: string
	stability: development
	brief: >
	Logical name of the service running on the server 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: server.service.namespace
	type: string
	stability: development
	brief: >
	A namespace for `server.service.name`.
	examples: ["Shop"]

[jsuereth]

The entire rationale behind this PR is that we want the service related names to be under the same "authority" / maintainership.

moving into server, again, splits the ownership in ways we do not want.

The goal is when we change service.* attributes, we can more easily see the impact on service.peer attributes and maintain them cohesively.

[thompson-tomo]

Should be specified on the attribute definition/registry and not the usage of it.

Suggested change

	deprecated:
	reason: renamed
	renamed_to: service.peer.name

[mmanciop]

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]

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]

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]

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]

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.

[jsuereth]

What has me concerned here is we don't have a specified way for instrumentation (i.e the OTel API) to access the resource attribute and fill out a service.name here, e.g. if using baggage.

@mmanciop I do think we need an overall "Improve the state of service-peer in OTEL Specification" tracking bug, with known examples/demos you've collected.

However, there's enough usage in OTEL now, that I think we this is ok for now. I just believe this requirement is "too hard" to accomplish in practice in OTEL.

[jsuereth]

Nit: "Operations that access some remote service MAY fill out these attributes"