Consider impact of ECS attribute alignment on the messaging semantic convention stability effort

[pyohannes]

What are you trying to achieve?

Make sure we are considering the impact of open-telemetry/oteps#222 prior to marking the HTTP semantic conventions stable.

The messaging semantic conventions currently specifies attributes in the messaging namespace, and references attributes from the net namespace.

Arguments from the net namespace are currently re-evaluated by the HTTP semantic convention workgroup, and decisions made there should be consistently applied for messaging too. Also, in line with decisions taken there, attributes in the messaging namespace should be re-evaluated regarding alignment with ECS.

Additional context.

See the similar issue for HTTP: #3163

[lmolkova]

Here're the changes that would come with ECS alignment:

• Network attribute renames as outlined for HTTP client spans Consider impact of ECS attribute alignment on the HTTP semantic convention stability effort #3163 (comment)

• Source and destination.
  ECS does not have messaging-specific attributes, but it defines source and destination namespaces which describe low-level networking.
  Also, ECS supports namespace reuse where namespace can be used as a root one, or under another namespace, such as process.entry_meta.source. So in scope of ECS, messaging.source should contain low-level network information.

Options:

1. keep messaging.destination and messaging.source.
   • The destination is a very common term used in messaging (starting with JMS). OTel does not support namespace reuse and messaging.destination and foobar.destination are different namespaces at the moment.
   • During ECS/OTel alignment we'd have to resolve the collision and use less generic terms than source and destination for low-level network attributes
2. Introduce new terminology for messaging (e.g. entity) to prevent future collisions.

[trask]

does proposal (2) move to a common attribute for both source/destination, e.g.

• messaging.(source|destination).name -> messaging.entity.name

is having a common attribute for both beneficial or problematic?

(and to throw another word into the salad, if I understand, maybe messaging.channel.name ...)

[pyohannes]

is having a common attribute for both beneficial or problematic?

I remember we discussed cases where having separate names for source and destination are benefical. E. g., there are cases where messages are published to queue "A", but are then routed and consumed from queue "B". So having two attributes messaging.destination.name="A" and messaging.source.name="B" might be useful for those scenarios.

Before going too deep into this discussion, we need to clarify whether we apply the ECS design principles of field reuse to OTel semantic conventions too. We also could say messaging.destination and destination are different things (that was the approach taken up to now, if I understand correctly). Otherwise we should make design principles for field reuse explicit for OTel semantic conventions.

[joaopgrassi]

I agree with @pyohannes , source and destination are well known terms for messaging and using a common (say entity) would be a downgrade in the experience I'd say. Have we discussed if OTel will also adopt this "field reuse" from ECS? This may cause a lot of problems 🤔 .

Also, given ECS does not specify messaging fields, should they be looking into adapting and using what OTel has?

[Oberon00]

I agree with pyohannes , source and destination are well known terms for messaging

From a gut feeling I would agree, but is "source" actually commonly used?

Actually I like the word "channel" that @trask coined here.

[lmolkova]

Based on experience adopting source/destination in Azure SDK messaging SDKs and in Python contrib repos (open-telemetry/opentelemetry-python-contrib#1746) having two different names for the same attribute is hardish to implement:

• code that populates attributes has to be aware of span kind or operation name
• it's error prone since it's harder to write helper methods and reuse them in instrumentation
• it's an extra logic to add conditions that takes additional resources (however small the overhead is)
• it makes attributes not suitable for logs. I.e. on logs I want to use messaging.destination.name, then logs need to be aware on which side of the communication they are
• it's not clear what to set on non-receive calls. E.g. on settlement or renewing message lock or updating visibility status - is it a destination or source?

I don't see a benefit in having two separate namespaces to describe the same thing, but see a lot of minor problems and complications.

The only problem it solves is a (presumably) quite rare case when original destination and source are both available on the consumer (and different). Can we solve this case in a different way without making the general-case experience worse? E.g. we can add messaging.destination.original_name or something like this.

Back to ECS alignment:

When we discussed source/destination asymmetry we did it partially because there was the same one for net/host on HTTP/gRPC, but with ECS alignment it would go away - #3402.

server.* attributes would always describe the server side. Source/destination would be used for lower-level(ish) communication or to describe communication where client/server are not quite applicable.

So combined with arguments against using different terms for messaging queue/topic names, it would be great to pick a different name that would not be confusing or conflicting with ECS.

Consulting with bing chat we came to the following list of terms:

• destination - broad and widely used (as @Oberon00 mentioned, source is rarely used in messaging scenarios). We might tolerate the conflict with ECS
• entity - maybe too broad, but we use it for Azure messaging systems
• channel or subject (used by NATS)
• somewhat controversial: route, address

I'd like to bring it up and discuss at tomorrow's messaging SIG meeting.

[joaopgrassi]

@lmolkova So, if I got it right, the idea with aligning with ECS would be that we drop the distinction between "destination" and "source" and group everything into the same thing? With your points above about being hard to identify in instrumentation what is a "source" vs what is a "destination" is having one help with anything? How users visualizing things will be able to distinguish them?

[Oberon00]

How users visualizing things will be able to distinguish them?

Not sure what you mean here, can you expand on this?

In general, I think combining the span kind, the messaging.operation (if set) will usually tell you if something is put into or taken from a destination.

Note that the old OTel conventions also only used "destination".

[pyohannes]

Discussed in today's workgroup meeting:

• We agreed to use the same term for both "source" and "destination", as in the initial conventions when only "destination" existed. If one wants to capture information about both "source" and "destination" on a single span, this can be done by prefixing the term by _original or .original.
• We settled on using the term "destination", as it's the least ambiguous, is well established, and should not conflict the destination in ECS, as field re-use in ECS must be explicitly defined.

[joaopgrassi]

I seem to remember during our sig meetings that we discovered a use for source, but as we saw yesterday during the call, nobody could remember what the use case was.. so I guess if the need comes we have the original route anyway 👍