Clarify difference between network.local.*/network.peer.* and source.*/destination.* attributes

[evan-bradley]

Area(s)

area:destination, area:network, area:source

Is your change request related to a problem? Please describe.

The docs for the network semantic conventions, source attributes, and destination attributes don't make it clear how network.local.*/network.peer.* and source.*/destination.* relate to each other.

The sense I get from the docs is that the network semconv attributes should be used in things like traces where a service is reporting on its own network communications, versus the source/destination attributes, which should be used by third-party services recording network transmissions between other applications.

Describe the solution you'd like

Clearly define the relationship between the two sets of attributes and advise in the docs when one or the other should be used.

Describe alternatives you've considered

No response

Additional context

I'm assisting the development of a Collector receiver that consumes NetFlow messages, and it isn't entirely clear to me how to translate the fields in NetFlow payloads to attributes in our semantic conventions given these two sets of attributes.

[trask]

hey @evan-bradley!

here's the key difference:

source.* and destination.*:

These should be used when there is no client/server relationship between the two sides, or when that relationship is unknown. This covers low-level network interactions (e.g. packet tracing) where you don’t know if there was a connection or which side initiated it. This also covers unidirectional UDP flows and peer-to-peer communication where the “user-facing” surface of the protocol / API doesn’t expose a clear notion of client and server.

client.* and server.*

These attributes may be used to describe the client (or server) in a connection-based network interaction where there is one side that initiates the connection (the client is the side that initiates the connection). This covers all TCP network interactions since TCP is connection-based and one side initiates the connection (an exception is made for peer-to-peer communication over TCP where the “user-facing” surface of the protocol / API doesn’t expose a clear notion of client and server). This also covers UDP network interactions where one side initiates the interaction, e.g. QUIC (HTTP/3) and DNS.

[evan-bradley]

Thank you for taking a look at this!

My confusion is more around network.local and network.peer vs. source and destination. I believe neither of these define a client/server relationship between the two sides.

[trask]

oh sorry! (need to read better)

IIRC network.* is physical layer, while client.*/server.*/source.*/destination.* are all logical layer