Trace payload/message size in semantic convention is inconsistent

[alexvanboxel]

What are you trying to achieve?

Consistency should exist between the naming of payload/message size attribute names. Currently, we have a mix of how the name is constructed over 3 different protocols. HTTP has measure-name(length)(compressed) convention, gRPC has message.un/compressedmeasure_name(size) and message systems have message.measure-name(size)_unit(bytes). Here you have the complete list:

HTTP (attribute on a span):

• http.request_content_length
• http.request_content_length_uncompressed
• http.response_content_length
• http.response_content_length_uncompressed

gRPC (attribute on link in a stream)

• message.compressed_size
• message.uncompressed_size

Messaging system (attribute on a span):

• messaging.message_payload_size_bytes
• messaging.message_payload_compressed_size_bytes

What did you expect to see?

Although this doesn't strictly violates the spec (although message in gRPC is borderline), we should seek consistency in the naming of measures. I would have expected something more like this:

HTTP (keeping this as this is the most established)

• http.request_content_length
• http.request_content_length_uncompressed
• http.response_content_length
• http.response_content_length_uncompressed

gRPC and messaging:

• messaging.payload_size
• messaging.payload_size_uncompressed

changes for message: joined RPC and messaging and:

• Removed unit (bytes)
• Changed compressed to uncompressed to align with HTTP
• Removed message from message_payload_size

I think it would be wise too add a note in the attributes naming convention some guidelines for messages, like:

• not adding the unit (bytes, mm, ...) in the attribute name

[arminru]

Hi @alexvanboxel, thanks for pointing this out!

gRPC and messaging do not share the same namespace on purpose since the messaging semantic conventions are a new concept added in OpenTelemetry whereas the gRPC message.* event attributes were taken over from OpenCensus for compatibility reasons IIRC. @bogdandrutu please confirm.

The messaging attributes were added first and afterwards the HTTP ones were added with a different naming to keep aligned with established terminology from HTTP headers, thus the divergence here.
We have some instrumentations using both already, so I'm not sure if it makes sense to modify the conventions this late in the game just for the sake of consistent naming.

I understand that it is desired for attribute names to be aligned, however. With the YAML definitions we added in #571, we would expect most OTel implementations to either ship with constants for all semantic convention attribute keys or provide them in a separate package. This would allow for easy discoverability in IDEs for both developers writing instrumentations as well as consumers. Do you think this is sufficient or would you still expect an overhaul here?

[alexvanboxel]

I understand that it is desired for attribute names to be aligned, however. With the YAML definitions we added in #571, we would expect most OTel implementations to either ship with constants for all semantic convention attribute keys or provide them in a separate package. This would allow for easy discoverability in IDEs for both developers writing instrumentations as well as consumers. Do you think this is sufficient or would you still expect an overhaul here?

I understand that compatibility issues will not fix the current attributes. But would you think that an addendum to the attribute guideline would be a good idea?

I came to the issue as I'm building our internal semantic conventions on-top of OTel. If yes, I can create another issue or something else? And if yes: I would keep this ticket open to add the addendum you just explained to the files as a note. WDYT?

[arminru]

Adding guidelines for the future would be a good idea, yes, and so could be an addendum explaining why the attributes you mentioned initially don't follow these. Would you like to create a PR for that?

[alexvanboxel]

Adding guidelines for the future would be a good idea, yes, and so could be an addendum explaining why the attributes you mentioned initially don't follow these. Would you like to create a PR for that?

I will, I will create first a PR for the attributes and use the issue to reference the addendum.

[alexvanboxel]

Adding guidelines for the future would be a good idea, yes, and so could be an addendum explaining why the attributes you mentioned initially don't follow these. Would you like to create a PR for that?

@arminru sorry it took so long, I've added an extra paragraph about units in names. Maybe after this is resolved this issue could be closed: #1307

[pyohannes]

messaging.message_payload_size_bytes
messaging.message_payload_compressed_size_bytes

Discussed in today's messaging workgroup:

• Clarify that the term "payload" refers to what goes over the wire (can either be a single message or a batch, including metdata), both in the initial definitions and in the namespace description.
• To be consistent with HTTP, skip the messaging.message_payload_compressed_size_bytes.
• To be consistent with HTTP, rename messaging.message_payload_size_bytes to messaging.payload.size.

[Oberon00]

"payload" refers to what goes over the wire (can either be a single message or a batch, including metdata)

That's the opposite of what the meaning of the word "payload" usually is https://en.wikipedia.org/wiki/Payload_(computing). Payload is usually used to distinguish metadata from the actual payload, so in the messaging context I would expect payload to be just the body. Maybe you should avoid the term "payload" entirely and use "body" and "complete_message" for more clarity.