Choosing network address and port attributes

The address you record depends on where you observe the exchange:

An endpoint sees its own socket and the socket it is directly connected to. That peer may be the other party, or an intermediary.
An intermediary (proxy, load balancer, or NAT) rewrites addresses, so the inbound side and the outbound side differ.
A pass-through observer (switch, router, tap, or flow exporter) has no socket. It only sees the addresses on the packets crossing that point.

The logical service a client intended to reach, the address observed at a given point, and the directly connected socket can all be different. OpenTelemetry defines a separate address/port pair for each, and more than one pair MAY apply to the same telemetry. The Attribute reference lists the attributes in each family.

Address and port attributes
Decision guide
How they coexist
- client.* / server.* and the socket
- source.* / destination.* and the socket
Attribute reference

Address and port attributes

Each pair covers one of the three addresses above: the logical service, the address observed at this point, and the directly connected socket.

Attribute pair	Question answered	Layer	Address form	Typical source
`client.` / `server.`	Who initiated vs. accepted the connection? (protocol roles)	Application (L7)	Logical / de-proxied when available (e.g. `X-Forwarded-For`, `Forwarded`, PROXY protocol)	Protocol or instrumentation library
`source.` / `destination.`	Who sent vs. received this exchange? (direction)	Flow / packet (L4), or any exchange with no clear client/server role (L7)	As observed at the point of instrumentation	Packet headers or socket addresses
`network.local.` / `network.peer.`	Which end is mine vs. the directly connected peer? (vantage)	Direct connection / socket	Physical socket endpoints	`getsockname` / `getpeername`

Decision guide

   What are you instrumenting?
   │
   ├─ L7 application / protocol role
   │   ├─ clear initiator and acceptor (HTTP, gRPC, DB protocols, …)
   │   │     → client / server
   │   │         note: logical, de-proxied when that address is available
   │   │     → network.local / network.peer
   │   └─ symmetric peers, no clear client/server (gossip, BitTorrent, blockchain, WebRTC)
   │         → source / destination
   │              note: as observed at this point; do not resolve past intermediaries
   │         → network.local / network.peer
   │
   ├─ L4 flow or packet (NetFlow, IPFIX, eBPF flows, pcap)
   │     → source / destination
   │         note: a host and a mid-path observer both use this pair,
   │               recording the address seen at that point;
   │               do not resolve past intermediaries
   │     → network.local / network.peer
   │         note: only when this observer has a socket;
   │               not a substitute for source / destination
   │
   └─ L2 / L3 adjacency, routing, or neighbor discovery
         → not covered by these semantic conventions

When an area’s semantic convention uses client / server, an operation whose initiator cannot be determined still uses client / server. That convention MAY say how to assign the role.

How they coexist

`client.` / `server.` and the socket

For client.* / server.* and network.peer.*: when instrumenting the client, server.address answers “who did I intend to talk to?” and network.peer.address answers “which host did this connection land on?”. When instrumenting the server, that flips: network.peer.address is the directly connected client or proxy, and client.address is the logical client. Folding the concrete peer into the logical role, in either direction, loses node-level diagnosis under load balancers, connection pools, and replicas. See the network.* registry for socket-level details.

Instrumentation perspective	Remote endpoint (logical vs. concrete)	Local endpoint (logical vs. concrete)
Client	`server.` vs. `network.peer.`	`client.` vs. `network.local.`
Server	`client.` vs. `network.peer.`	`server.` vs. `network.local.`

Logical service and concrete node

server.address is the service the client intended to reach. network.peer.address is the node that accepted this connection.

  ┌─────────────────────┐       ┌─────────────────────┐
  │ app                 │       │ replica B           │
  │ ip: 10.0.0.20       │ ────> │ ip: 10.0.0.8        │
  └─────────────────────┘       │ db.example.com:5432 │
                                └─────────────────────┘

  Reported on the app's DB client span:
    server.address       = db.example.com
    server.port          = 5432
    network.peer.address = 10.0.0.8
    network.peer.port    = 5432

The following examples show how the logical role (server.* / client.*) and the concrete socket (network.peer.*) differ across proxy topologies. network.local.* is usually omitted; area-specific conventions mark it Opt-In. The reverse-proxy server example includes it so the listen socket is visible next to the external server.*.

Simple client/server example

  ────> public connection (the client-server connection)

  ┌┄ logical client ┄┄┄┄┄┄┄┄┐       ┌┄ logical server ┄┄┄┄┄┄┄┄┐
  ┆                         ┆       ┆                         ┆
  ┆ ┌─────────────────────┐ ┆       ┆ ┌─────────────────────┐ ┆
  ┆ │ client              │ ┆       ┆ │ server              │ ┆
  ┆ │ ip: 101.102.103.104 │ ┆ ────> ┆ │ ip: 201.202.203.204 │ ┆
  ┆ │ port: 50101         │ ┆       ┆ │ port: 9876          │ ┆
  ┆ │ hostname: client.io │ ┆       ┆ │ hostname: server.io │ ┆
  ┆ └─────────────────────┘ ┆       ┆ └─────────────────────┘ ┆
  ┆                         ┆       ┆                         ┆
  └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘       └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘

  Reported by the client:                         Reported by the server:
    client.address       = 101.102.103.104          client.address       = 101.102.103.104
    client.port          = 50101                    client.port          = 50101
    server.address       = server.io                server.address       = server.io
    server.port          = 9876                     server.port          = 9876
    network.peer.address = 201.202.203.204          network.peer.address = 101.102.103.104
    network.peer.port    = 9876                     network.peer.port    = 50101

Client/server example with reverse proxy

server.* is the external host (server.io:9876), from Host or X-Forwarded-Host, not the listen socket the-server:5678. That socket is network.local.* on the server report. This picture gives the proxy one address. client.port is set only when the intermediary forwarded that port. X-Forwarded-For carries the address and not the port, so the server report omits client.port. network.peer.port is the proxy’s port on the accepted connection (52323).

  ────> public connection (the client-server connection)
  ····> local connection (the connection behind the proxy)

  ┌┄ logical client ┄┄┄┄┄┄┄┄┐       ┌┄ logical server ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
  ┆                         ┆       ┆                                                       ┆
  ┆ ┌─────────────────────┐ ┆       ┆ ┌─────────────────────┐       ┌─────────────────────┐ ┆
  ┆ │ client              │ ┆       ┆ │ reverse proxy       │       │ server              │ ┆
  ┆ │ ip: 101.102.103.104 │ ┆ ────> ┆ │ ip: 201.202.203.204 │ ····> │ ip: 10.11.12.13     │ ┆
  ┆ │ port: 50101         │ ┆       ┆ │ port: 9876          │       │ port: 5678          │ ┆
  ┆ │ hostname: client.io │ ┆       ┆ │ hostname: server.io │       │ hostname: the-server│ ┆
  ┆ └─────────────────────┘ ┆       ┆ └─────────────────────┘       └─────────────────────┘ ┆
  ┆                         ┆       ┆                                                       ┆
  └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘       └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘

  Reported by the client:                         Reported by the server:
    client.address       = 101.102.103.104          client.address        = 101.102.103.104
    client.port          = 50101
    server.address       = server.io                server.address        = server.io
    server.port          = 9876                     server.port           = 9876
    network.peer.address = 201.202.203.204          network.peer.address  = 201.202.203.204
    network.peer.port    = 9876                     network.peer.port     = 52323
                                                    network.local.address = 10.11.12.13
                                                    network.local.port    = 5678

Client/server example with forward proxy

The server knows the original client, so client.address is 101.102.103.104 and network.peer.address is the proxy 1.2.3.4. client.port is omitted, as in the reverse proxy. When the original client was not forwarded, client.address is the immediate peer and matches network.peer.address.

  ────> public connection (the client-server connection)
  ····> local connection (the connection behind the proxy)

  ┌┄ logical client ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐       ┌┄ logical server ┄┄┄┄┄┄┄┄┐
  ┆                                                       ┆       ┆                         ┆
  ┆ ┌─────────────────────┐       ┌─────────────────────┐ ┆       ┆ ┌─────────────────────┐ ┆
  ┆ │ client              │       │ forward proxy       │ ┆       ┆ │ server              │ ┆
  ┆ │ ip: 101.102.103.104 │ ····> │ ip: 1.2.3.4         │ ┆ ────> ┆ │ ip: 201.202.203.204 │ ┆
  ┆ │ port: 50101         │       │ port: 4321          │ ┆       ┆ │ port: 5678          │ ┆
  ┆ │ hostname: client.io │       │ hostname: proxy.io  │ ┆       ┆ │ hostname: server.io │ ┆
  ┆ └─────────────────────┘       └─────────────────────┘ ┆       ┆ └─────────────────────┘ ┆
  ┆                                                       ┆       ┆                         ┆
  └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘       └┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┘

  Reported by the client:                         Reported by the server:
    client.address       = 101.102.103.104          client.address        = 101.102.103.104
    client.port          = 50101
    server.address       = server.io                server.address        = server.io
    server.port          = 5678                     server.port           = 5678
    network.peer.address = 1.2.3.4                  network.peer.address  = 1.2.3.4
    network.peer.port    = 4321                     network.peer.port     = 52323

`source.` / `destination.` and the socket

network.peer is not source or destination. On an endpoint the vantage is fixed while the direction of each exchange flips:

   transmit :  local → source        peer  → destination
   receive  :  peer  → source        local → destination

A mid-path observer such as a router often has no local socket, so network.local / network.peer do not apply. source / destination remain well-defined from the packet headers.

One endpoint, both directions

  ────> transmit    <──── receive

  ┌─────────────────────┐       ┌─────────────────────┐
  │ host A              │       │ host B              │
  │ ip: 101.102.103.104 │ ────> │ ip: 201.202.203.204 │
  │ port: 50101         │ <──── │ port: 9876          │
  └─────────────────────┘       └─────────────────────┘

  Reported by A, transmit:                          Reported by A, receive:
    source.address         = 101.102.103.104          source.address         = 201.202.203.204
    source.port            = 50101                    source.port            = 9876
    destination.address    = 201.202.203.204          destination.address    = 101.102.103.104
    destination.port       = 9876                     destination.port       = 50101
    network.local.address  = 101.102.103.104          network.local.address  = 101.102.103.104
    network.local.port     = 50101                    network.local.port     = 50101
    network.peer.address   = 201.202.203.204          network.peer.address   = 201.202.203.204
    network.peer.port      = 9876                     network.peer.port      = 9876

source / destination name one sender and one receiver. A single packet, a one-way flow, or one peer-to-peer message fits. A record that sums both directions does not. Split that record by direction, or pick a stable orientation, such as source = the initiator. There is no standard orientation yet (opentelemetry-ebpf-instrumentation#1659, #3828).

Router before NAT

A NAT between the router and host B rewrites host A’s source to 101.102.103.104:40000. The router is before that translation and has no socket for this flow.

  ────> packet

  ┌─────────────────────┐       ┌─────────────────────┐       ┌─────────────────────┐       ┌─────────────────────┐
  │ host A              │       │ router              │       │ NAT                 │       │ host B              │
  │ ip: 10.1.2.80       │ ────> │ no socket           │ ────> │ src 101.102.103.104 │ ────> │ ip: 201.202.203.204 │
  │ port: 50101         │       │                     │       │ port: 40000         │       │ port: 9876          │
  └─────────────────────┘       └─────────────────────┘       └─────────────────────┘       └─────────────────────┘

  Reported by the router, before NAT:            Reported by host B, after NAT:
    source.address      = 10.1.2.80                source.address         = 101.102.103.104
    source.port         = 50101                    source.port            = 40000
    destination.address = 201.202.203.204          destination.address    = 201.202.203.204
    destination.port    = 9876                     destination.port       = 9876
                                                   network.local.address  = 201.202.203.204
                                                   network.local.port     = 9876
                                                   network.peer.address   = 101.102.103.104
                                                   network.peer.port      = 40000

Two observers of the same flow can disagree, and both can be right. Each records the address it sees. This guide does not say how to name which point a record came from.

Broadcast, multicast, and anycast

For broadcast and multicast, destination.* is the group address on the packet, not each host that received a copy. Host B below receives a copy of host A’s packet. A group is not a connected peer, so network.peer does not apply. network.local.* is the socket on the host that sends or receives.

  ────> packet addressed to 239.1.1.1:9876

  ┌─────────────────────┐       ┌─────────────────────┐
  │ host A              │       │ host B              │
  │ ip: 101.102.103.104 │ ────> │ ip: 201.202.203.204 │
  │ port: 50101         │       │ port: 9876          │
  └─────────────────────┘       └─────────────────────┘

  Reported by host A:                           Reported by host B:
    source.address         = 101.102.103.104      source.address         = 101.102.103.104
    source.port            = 50101                source.port            = 50101
    destination.address    = 239.1.1.1            destination.address    = 239.1.1.1
    destination.port       = 9876                 destination.port       = 9876
    network.local.address  = 101.102.103.104      network.local.address  = 201.202.203.204
    network.local.port     = 50101                network.local.port     = 9876

For anycast, destination.* is the VIP on the packet, not the replica’s own address. network.local.* is the replica’s socket. network.peer is host A, the peer connected to that socket.

  ────> packet addressed to the VIP 201.202.203.204:9876

  ┌─────────────────────┐       ┌─────────────────────┐
  │ host A              │       │ replica             │
  │ ip: 101.102.103.104 │ ────> │ ip: 10.11.12.13     │
  │ port: 50101         │       │ port: 9876          │
  └─────────────────────┘       └─────────────────────┘

  Reported by the replica:
    source.address         = 101.102.103.104
    source.port            = 50101
    destination.address    = 201.202.203.204
    destination.port       = 9876
    network.local.address  = 10.11.12.13
    network.local.port     = 9876
    network.peer.address   = 101.102.103.104
    network.peer.port      = 50101

Naming each host that receives a copy is out of scope (#4121).

Attribute reference

The address and port attribute families are summarized below. Full definitions live in the registry: client, server, source, destination, and network.

Server

Status:

server.* attributes describe the server in a connection-based network interaction: the side that accepts the connection (the client is the side that initiates it). They identify the logical server the client intended to reach, which - behind proxies or load balancers - can differ from the concrete socket endpoint.

Use them for interactions with a clear initiator and acceptor. This covers common TCP interactions, connection-oriented UDP such as QUIC (HTTP/3), and request/response protocols such as DNS and SNMP polling. It does not cover peer-to-peer communication where the protocol or API exposes no clear notion of client and server (even over TCP).

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`server.address`	`Recommended`	string	Server domain name if available without reverse DNS lookup; otherwise, IP address or UNIX domain socket name. [1]	`example.com`; `10.1.2.80`; `/tmp/my.sock`
`server.port`	`Recommended`	int	Server port number. [2]	`80`; `8080`; `443`
`server.as.number`	`Opt-In`	int	The Autonomous System Number (ASN) associated with the server IP address. [3]	`64496`; `15169`
`server.as.organization`	`Opt-In`	string	The name of the organization associated with the autonomous system of the server IP address. [4]	`Example Networks Inc.`; `Google LLC`
`server.mac.address`	`Opt-In`	string	Server Media Access Control (MAC) address. [5]	`00-00-5E-00-53-23`
`server.prefix`	`Opt-In`	string	The IP prefix associated with the server IP address, in CIDR notation. [6]	`192.0.2.0/24`; `2001:db8::/32`
`server.service.name`	`Opt-In`	string	Logical name of the service acting as the server in a connection-based network interaction. [7]	`payments`
`server.service.namespace`	`Opt-In`	string	Logical namespace of the service acting as the server in a connection-based network interaction. [8]	`Shop`

[1] server.address: On the client side, server.address is the remote service name; on the server side, it is the local service name as seen externally by clients. These normally match - for example, for the URL https://example.com/foo it is "example.com" on both sides. When a client reaches the server through an intermediary such as a proxy, server.address SHOULD represent the server behind the intermediary, if available.

For IP-based communication, prefer a DNS hostname of the service. Instrumentation is often given the address as a URL, connection string, or hostname, so server.address SHOULD be set to the known hostname available to it, which may be a DNS name or an IP address (for example "127.0.0.1" for https://127.0.0.1/foo). If only an IP address is available, populate server.address with it; a reverse DNS lookup SHOULD NOT be used to obtain a name.

If network.transport is "pipe", use the absolute path to the file representing it; for an anonymous pipe with no such file, set server.address to an empty string to distinguish it from an unknown or uninstrumented value.

For a UNIX domain socket, server.address is the remote endpoint address on the client side and the local endpoint address on the server side.

[2] server.port: When observed from the client side, and when communicating through an intermediary, server.port SHOULD represent the server port behind any intermediaries, for example proxies, if it’s available.

[3] server.as.number: This attribute SHOULD only be set when the server address is an IP address and the ASN is available from routing, enrichment, or lookup data. The value SHOULD be represented as an integer without the AS prefix.

[4] server.as.organization: This attribute SHOULD only be set when server.as.number is set and the organization name is available. The value SHOULD be the organization name as provided by the lookup or enrichment source, not the AS name or short code.

[5] server.mac.address: This attribute MUST identify a MAC address associated with the logical server endpoint, including when that endpoint is behind intermediaries. If the server’s MAC address is unknown, this attribute MUST NOT be set. The MAC address of a proxy, gateway, or next-hop router MUST NOT be used as a substitute.

MAC addresses MUST be represented in IEEE RA hexadecimal form: as hyphen-separated octets in uppercase hexadecimal form from most to least significant.

Warning

This attribute may contain sensitive (PII) information.

[6] server.prefix:

Warning

This attribute may contain sensitive (PII) information. A /32 IPv4 prefix or /128 IPv6 prefix preserves the complete endpoint IP address. Using CIDR notation does not guarantee that the data is anonymous.

The value MUST be an IPv4 or IPv6 network prefix in CIDR notation, as defined in RFC 4632 for IPv4 and RFC 4291 for IPv6. IPv4 prefixes MUST use a dotted-decimal address followed by / and a decimal prefix length from 0 to 32. IPv6 prefixes MUST use the canonical address text representation defined in RFC 5952, followed by / and a decimal prefix length from 0 to 128. All host bits in the address MUST be set to zero. The value MUST NOT contain a domain name, UNIX domain socket name, or IPv6 zone identifier.

Instrumentation or Collector receivers that populate this attribute MUST convert native representations, such as an address and subnet mask or an address and prefix length, to equivalent CIDR notation before emitting it.

This attribute MUST NOT be set unless server.address is set to an IPv4 or IPv6 address. The address MUST use the same IP version as this prefix and be contained in it.

[7] server.service.name: SHOULD be equal to the actual service.name resource attribute of the logical server, if any. This identifies the server service whether the telemetry is recorded by the client, the server, or another observer.

[8] server.service.namespace: SHOULD be equal to the actual service.namespace resource attribute of the logical server, if any. This identifies the server service’s namespace whether the telemetry is recorded by the client, the server, or another observer. Together with server.service.name, this identifies the server service. An empty namespace is equivalent to an unspecified namespace.

Client

Status:

client.* attributes describe the client in a connection-based network interaction: the side that initiates the connection (the server is the side that accepts it). They identify the logical client, which - behind proxies or load balancers - can differ from the concrete socket endpoint and is typically recovered from headers such as X-Forwarded-For.

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`client.address`	`Recommended`	string	Client address - domain name if available without reverse DNS lookup; otherwise, IP address or UNIX domain socket name. [1]	`client.example.com`; `10.1.2.80`; `/tmp/my.sock`
`client.port`	`Recommended`	int	Client port number. [2]	`65123`
`client.as.number`	`Opt-In`	int	The Autonomous System Number (ASN) associated with the client IP address. [3]	`64496`; `15169`
`client.as.organization`	`Opt-In`	string	The name of the organization associated with the autonomous system of the client IP address. [4]	`Example Networks Inc.`; `Google LLC`
`client.mac.address`	`Opt-In`	string	Client Media Access Control (MAC) address. [5]	`00-00-5E-00-53-23`
`client.prefix`	`Opt-In`	string	The IP prefix associated with the client IP address, in CIDR notation. [6]	`192.0.2.0/24`; `2001:db8::/32`
`client.service.name`	`Opt-In`	string	Logical name of the service acting as the client in a connection-based network interaction. [7]	`shoppingcart`
`client.service.namespace`	`Opt-In`	string	Logical namespace of the service acting as the client in a connection-based network interaction. [8]	`Shop`

[1] client.address: When observed from the server side, and when communicating through an intermediary, client.address SHOULD represent the client address behind any intermediaries, for example proxies, if it’s available.

[2] client.port: When observed from the server side, and when communicating through an intermediary, client.port SHOULD represent the client port behind any intermediaries, for example proxies, if it’s available.

[3] client.as.number: This attribute SHOULD only be set when the client address is an IP address and the ASN is available from routing, enrichment, or lookup data. The value SHOULD be represented as an integer without the AS prefix.

[4] client.as.organization: This attribute SHOULD only be set when client.as.number is set and the organization name is available. The value SHOULD be the organization name as provided by the lookup or enrichment source, not the AS name or short code.

[5] client.mac.address: This attribute MUST identify a MAC address associated with the logical client endpoint, including when that endpoint is behind intermediaries. If the client’s MAC address is unknown, this attribute MUST NOT be set. The MAC address of a proxy, gateway, or next-hop router MUST NOT be used as a substitute.

MAC addresses MUST be represented in IEEE RA hexadecimal form: as hyphen-separated octets in uppercase hexadecimal form from most to least significant.

Warning

This attribute may contain sensitive (PII) information.

[6] client.prefix:

Warning

This attribute MUST NOT be set unless client.address is set to an IPv4 or IPv6 address. The address MUST use the same IP version as this prefix and be contained in it.

[7] client.service.name: SHOULD be equal to the actual service.name resource attribute of the logical client, if any. This identifies the client service whether the telemetry is recorded by the client, the server, or another observer.

[8] client.service.namespace: SHOULD be equal to the actual service.namespace resource attribute of the logical client, if any. This identifies the client service’s namespace whether the telemetry is recorded by the client, the server, or another observer. Together with client.service.name, this identifies the client service. An empty namespace is equivalent to an unspecified namespace.

Source

Status:

source.* attributes describe the sender of a network exchange or packet. They capture the address available at the point of instrumentation and do not try to resolve the address behind intermediaries such as proxies.

Use them when there is no client/server relationship between the two sides, or when that relationship is unknown - for example, packet-level telemetry and peer-to-peer protocols.

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`source.address`	`Recommended`	string	Source address as observed at the point of instrumentation - typically an IP address, or a UNIX domain socket name; a domain name only when the sender was addressed by name (for example a peer-to-peer node dialed by hostname), never obtained via reverse DNS lookup. [1]	`10.1.2.80`; `source.example.com`; `/tmp/my.sock`
`source.port`	`Recommended`	int	Source port number	`3389`; `2888`
`source.as.number`	`Opt-In`	int	The Autonomous System Number (ASN) associated with the source IP address. [2]	`64496`; `15169`
`source.as.organization`	`Opt-In`	string	The name of the organization associated with the autonomous system of the source IP address. [3]	`Example Networks Inc.`; `Google LLC`
`source.mac.address`	`Opt-In`	string	Source Media Access Control (MAC) address. [4]	`00-00-5E-00-53-23`
`source.prefix`	`Opt-In`	string	The IP prefix associated with the source IP address, in CIDR notation. [5]	`192.0.2.0/24`; `2001:db8::/32`

[1] source.address: source.address SHOULD be the sender address as observed at the point of instrumentation, for example the source of the packet, flow, or exchange seen on the wire or socket. Instrumentation SHOULD capture the available address and SHOULD NOT try to resolve the address behind intermediaries such as proxies or load balancers, or perform a reverse DNS lookup to obtain a domain name.

[2] source.as.number: This attribute SHOULD only be set when the source address is an IP address and the ASN is available from routing, enrichment, or lookup data. The value SHOULD be represented as an integer without the AS prefix.

[3] source.as.organization: This attribute SHOULD only be set when source.as.number is set and the organization name is available. The value SHOULD be the organization name as provided by the lookup or enrichment source, not the AS name or short code.

[4] source.mac.address: MAC addresses MUST be represented in IEEE RA hexadecimal form: as hyphen-separated octets in uppercase hexadecimal form from most to least significant.

Warning

This attribute may contain sensitive (PII) information.

[5] source.prefix:

Warning

This attribute MAY be set whether or not source.address is set. If source.address is also set to an IP address, it MUST use the same IP version and be contained in this prefix.

Destination

Status:

destination.* attributes describe the receiver of a network exchange or packet. They capture the address available at the point of instrumentation and do not try to resolve the address behind intermediaries such as proxies.

Use them when there is no client/server relationship between the two sides, or when that relationship is unknown - for example, packet-level telemetry and peer-to-peer protocols.

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`destination.address`	`Recommended`	string	Destination address as observed at the point of instrumentation - typically an IP address, or a UNIX domain socket name; a domain name only when the receiver was addressed by name (for example a peer-to-peer node dialed by hostname), never obtained via reverse DNS lookup. [1]	`10.1.2.80`; `destination.example.com`; `/tmp/my.sock`
`destination.port`	`Recommended`	int	Destination port number	`3389`; `2888`
`destination.as.number`	`Opt-In`	int	The Autonomous System Number (ASN) associated with the destination IP address. [2]	`64496`; `15169`
`destination.as.organization`	`Opt-In`	string	The name of the organization associated with the autonomous system of the destination IP address. [3]	`Example Networks Inc.`; `Google LLC`
`destination.mac.address`	`Opt-In`	string	Destination Media Access Control (MAC) address. [4]	`00-00-5E-00-53-23`
`destination.prefix`	`Opt-In`	string	The IP prefix associated with the destination IP address, in CIDR notation. [5]	`192.0.2.0/24`; `2001:db8::/32`

[1] destination.address: destination.address SHOULD be the receiver address as observed at the point of instrumentation, for example the destination of the packet, flow, or exchange seen on the wire or socket. Instrumentation SHOULD capture the available address and SHOULD NOT try to resolve the address behind intermediaries such as proxies or load balancers, or perform a reverse DNS lookup to obtain a domain name.

[2] destination.as.number: This attribute SHOULD only be set when the destination address is an IP address and the ASN is available from routing, enrichment, or lookup data. The value SHOULD be represented as an integer without the AS prefix.

[3] destination.as.organization: This attribute SHOULD only be set when destination.as.number is set and the organization name is available. The value SHOULD be the organization name as provided by the lookup or enrichment source, not the AS name or short code.

[4] destination.mac.address: MAC addresses MUST be represented in IEEE RA hexadecimal form: as hyphen-separated octets in uppercase hexadecimal form from most to least significant.

Warning

This attribute may contain sensitive (PII) information.

[5] destination.prefix:

Warning

This attribute MAY be set whether or not destination.address is set. If destination.address is also set to an IP address, it MUST use the same IP version and be contained in this prefix.

Network peer

Status:

These attributes identify the network peer that is directly connected to the local endpoint.

Note

Specific structures and methods to obtain socket-level attributes are mentioned here only as examples. Instrumentations would usually use the socket API provided by their environment or socket implementations.

When connecting using connect(2) (Linux or other POSIX systems / Windows) with the AF_INET address family, network.peer.address and network.peer.port represent the sin_addr and sin_port fields of the sockaddr_in structure.

network.peer.address and network.peer.port can be obtained by calling getpeername (Linux or other POSIX systems / Windows).

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`network.peer.address`	`Recommended`	string	Peer address of the network connection - IP address or UNIX domain socket name. [1]	`10.1.2.80`; `/tmp/my.sock`
`network.peer.port`	`Recommended`	int	Peer port number of the network connection.	`65123`
`network.peer.as.number`	`Opt-In`	int	The Autonomous System Number (ASN) associated with the peer IP address. [2]	`64496`; `15169`
`network.peer.as.organization`	`Opt-In`	string	The name of the organization associated with the autonomous system of the peer IP address. [3]	`Example Networks Inc.`; `Google LLC`
`network.peer.mac.address`	`Opt-In`	string	Peer Media Access Control (MAC) address of the network connection. [4]	`00-00-5E-00-53-23`
`network.peer.prefix`	`Opt-In`	string	The IP prefix associated with the peer IP address, in CIDR notation. [5]	`192.0.2.0/24`; `2001:db8::/32`

[1] network.peer.address: This SHOULD be an IP address, UNIX domain socket name, or other address specific to the network type.

[2] network.peer.as.number: This attribute SHOULD only be set when the peer address is an IP address and the ASN is available from routing, enrichment, or lookup data. The value SHOULD be represented as an integer without the AS prefix.

[3] network.peer.as.organization: This attribute SHOULD only be set when network.peer.as.number is set and the organization name is available. The value SHOULD be the organization name as provided by the lookup or enrichment source, not the AS name or short code.

[4] network.peer.mac.address: MAC addresses MUST be represented in IEEE RA hexadecimal form: as hyphen-separated octets in uppercase hexadecimal form from most to least significant.

Warning

This attribute may contain sensitive (PII) information.

[5] network.peer.prefix:

Warning

This attribute MAY be set whether or not network.peer.address is set. If network.peer.address is also set to an IP address, it MUST use the same IP version and be contained in this prefix.

Network local

Status:

These attributes identify the local endpoint of a network connection.

Note

When binding using bind(2) (Linux or other POSIX systems / Windows) with the AF_INET address family, network.local.address and network.local.port represent the sin_addr and sin_port fields of the sockaddr_in structure.

network.local.address and network.local.port can be obtained by calling getsockname (Linux or other POSIX systems / Windows).

Attributes:

Key	Requirement Level	Value Type	Description	Example Values
`network.local.address`	`Recommended`	string	Local address of the network connection - IP address or UNIX domain socket name. [1]	`10.1.2.80`; `/tmp/my.sock`
`network.local.port`	`Recommended`	int	Local port number of the network connection.	`65123`
`network.local.as.number`	`Opt-In`	int	The Autonomous System Number (ASN) associated with the local IP address. [2]	`64496`; `15169`
`network.local.as.organization`	`Opt-In`	string	The name of the organization associated with the autonomous system of the local IP address. [3]	`Example Networks Inc.`; `Google LLC`
`network.local.mac.address`	`Opt-In`	string	Local Media Access Control (MAC) address of the network connection. [4]	`00-00-5E-00-53-23`
`network.local.prefix`	`Opt-In`	string	The IP prefix associated with the local IP address, in CIDR notation. [5]	`192.0.2.0/24`; `2001:db8::/32`

[1] network.local.address: This SHOULD be an IP address, UNIX domain socket name, or other address specific to the network type.

[2] network.local.as.number: This attribute SHOULD only be set when the local address is an IP address and the ASN is available from routing, enrichment, or lookup data. The value SHOULD be represented as an integer without the AS prefix.

[3] network.local.as.organization: This attribute SHOULD only be set when network.local.as.number is set and the organization name is available. The value SHOULD be the organization name as provided by the lookup or enrichment source, not the AS name or short code.

[4] network.local.mac.address: MAC addresses MUST be represented in IEEE RA hexadecimal form: as hyphen-separated octets in uppercase hexadecimal form from most to least significant.

Warning

This attribute may contain sensitive (PII) information.

[5] network.local.prefix:

Warning

This attribute MAY be set whether or not network.local.address is set. If network.local.address is also set to an IP address, it MUST use the same IP version and be contained in this prefix.

Feedback

Was this page helpful?

Thank you. Your feedback is appreciated!

Please let us know how we can improve this page. Your feedback is appreciated!

Choosing network address and port attributes

Address and port attributes

Decision guide

How they coexist

client.* / server.* and the socket

Logical service and concrete node

Simple client/server example

Client/server example with reverse proxy

Client/server example with forward proxy

source.* / destination.* and the socket

One endpoint, both directions

Router before NAT

Broadcast, multicast, and anycast

Attribute reference

Server

Client

Source

Destination

Network peer

Network local

Feedback

`client.` / `server.` and the socket

`source.` / `destination.` and the socket