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

[mmanciop]

Fixes #2945

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.

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

[mmanciop]

@jsuereth #3190

[lmolkova]

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]

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]

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

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.