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"]

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