Add `network.peer.address_ipv4` and `network.peer.address_ipv6` attributes for dual-stack peers

[ajimenez1503]

Area(s)

area:network

Propose new conventions

What's missing?

The current network semantic conventions define
network.peer.address
as a string containing the peer address of a network connection, such as an IP
address or Unix domain socket name.

This works when telemetry describes one concrete network connection with one peer
address. It does not cover peer-scoped network telemetry in which a single logical
peer is dual-stack and its IPv4 and IPv6 addresses are known simultaneously.

This occurs in connected-device monitoring, topology and discovery telemetry,
network inventory or state events, and peer-level metrics produced by SNMP,
vendor API, or other network receivers. In these cases, one metric data point may
describe one peer and one measurement while needing both addresses as attributes
on the same time series.

With only network.peer.address, a producer must either:

• choose one address and discard the other; or
• emit the same measurement once for IPv4 and once for IPv6.

These attributes are not intended to describe every address assigned to a host.
They apply when the surrounding network telemetry already identifies a peer and
provides one relevant address for each IP family.

This proposal addresses one completeness gap in the current network.*
attributes and aligns with the scope being discussed in the
Networking Working Group issue
and the proposed
Network Observability project.

Describe the solution you'd like

Add two new network attributes:

Name	Type	Stability	Brief	Examples
network.peer.address_ipv4	string	development	IPv4 address associated with the network peer.	192.0.2.10, 198.51.100.25
network.peer.address_ipv6	string	development	IPv6 address associated with the network peer.	2001:db8::10, 2001:db8:1::25

Suggested note:

These attributes represent family-specific IP addresses associated with the peer
described by the surrounding network telemetry.

network.peer.address_ipv4 and network.peer.address_ipv6 MAY be set
independently and MAY both be present on the same telemetry record or metric data
point. When both are present, they describe one dual-stack peer and do not imply
two separate measurements.

network.peer.address_ipv4 MUST contain an IPv4 address in dotted-quad notation.

network.peer.address_ipv6 MUST contain an IPv6 address using the canonical text
representation described by
RFC 5952.

The values MUST NOT contain a port, CIDR prefix, hostname, or Unix domain socket
name.

These attributes do not replace network.peer.address.
network.peer.address SHOULD continue to identify the actual remote address when
telemetry represents a concrete network connection. If it is recorded together
with a family-specific attribute for that connection, its value SHOULD equal the
family-specific attribute corresponding to the address family used by the
connection.

Possible alternatives considered

• Continue using network.peer.address: this can represent only one address and
  would require the producer to discard either the IPv4 or IPv6 address.

• Change network.peer.address to string[]: rejected because changing the type
  of an existing stable attribute would be a breaking change.

• Add network.peer.addresses as string[]: this could represent a complete
  address set, but consumers would need to inspect and classify every value by
  address family. It would not provide stable, family-specific scalar dimensions
  for metric queries and correlation.

• Emit one metric data point per address and use network.type to distinguish
  them: this creates separate time series and duplicates a measurement that
  describes one logical peer.

• Use network.peer.address.ipv4 and network.peer.address.ipv6: rejected
  because network.peer.address is already an attribute and should not also be
  used as a namespace. This can conflict when attributes are represented in
  hierarchical formats.

Implementation

I would be more than happy to work on it. Please assign it to me if possible.

Thanks.

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}