General Attributes

Status: Experimental

The attributes described in this section are not specific to a particular operation but rather generic. They may be used in any Span they apply to. Particular operations may refer to or require some of these attributes.

Server, client and shared network attributes

These attributes may be used to describe the client and 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 does not 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.

In an ideal situation, not accounting for proxies, multiple IP addresses or host names, the server.* attributes are the same on the client and server.

Address and port attributes

For all IP-based protocols, the “address” should be just the IP-level address. Protocol-specific parts of an address are split into other attributes (when applicable) such as “port” attributes for TCP and UDP. If such transport-specific information is collected and the attribute name does not already uniquely identify the transport, then setting network.transport is especially encouraged.

Server attributes

Warning Attributes in this section are in use by the HTTP semantic conventions. Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed if they do not cause breaking changes to HTTP semantic conventions.

AttributeTypeDescriptionExamplesRequirement LevelStability
server.addressstringServer 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.sockRecommendedStable
server.portintServer port number. [2]80; 8080; 443RecommendedStable

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

[2]: 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.

server.address and server.port represent logical server name and port. Semantic conventions that refer to these attributes SHOULD specify what these attributes mean in their context.

server.address

For IP-based communication, the name should be a DNS host name of the service. On client side it matches remote service name, on server side, it represents local service name as seen externally on clients.

When connecting to an URL https://example.com/foo, server.address matches "example.com" on both client and server side.

On client side, it’s usually passed in form of URL, connection string, host name, etc. Sometimes host name is only available to instrumentation as a string which may contain DNS name or IP address. server.address SHOULD be set to the available known hostname (e.g., "127.0.0.1" if connecting to an URL https://127.0.0.1/foo).

If only IP address is available, it should be populated on server.address. Reverse DNS lookup SHOULD NOT be used to obtain DNS name.

If network.transport is "pipe", the absolute path to the file representing it should be used as server.address. If there is no such file (e.g., anonymous pipe), the name should explicitly be set to the empty string to distinguish it from the case where the name is just unknown or not covered by the instrumentation.

For Unix domain socket, server.address attribute represents remote endpoint address on the client side and local endpoint address on the server side.

Client attributes

Warning Attributes in this section are in use by the HTTP semantic conventions. Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed if they do not cause breaking changes to HTTP semantic conventions.

AttributeTypeDescriptionExamplesRequirement LevelStability
client.addressstringClient 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.sockRecommendedStable
client.portintClient port number. [2]65123RecommendedStable

[1]: 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]: 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.

Source and destination attributes

These attributes may be used to describe the sender and receiver of a network exchange/packet. 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 does not expose a clear notion of client and server.

Source

AttributeTypeDescriptionExamplesRequirement LevelStability
source.addressstringSource address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1]source.example.com; 10.1.2.80; /tmp/my.sockRecommendedExperimental
source.portintSource port number3389; 2888RecommendedExperimental

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

Destination

Destination fields capture details about the receiver of a network exchange/packet.

AttributeTypeDescriptionExamplesRequirement LevelStability
destination.addressstringDestination address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [1]destination.example.com; 10.1.2.80; /tmp/my.sockRecommendedExperimental
destination.portintDestination port number3389; 2888RecommendedExperimental

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

Other network attributes

Warning Attributes in this section are in use by the HTTP semantic conventions. Once the HTTP semantic conventions are declared stable, changes to the attributes in this section will only be allowed if they do not cause breaking changes to HTTP semantic conventions.

AttributeTypeDescriptionExamplesRequirement LevelStability
network.local.addressstringLocal address of the network connection - IP address or Unix domain socket name.10.1.2.80; /tmp/my.sockRecommendedStable
network.local.portintLocal port number of the network connection.65123RecommendedStable
network.peer.addressstringPeer address of the network connection - IP address or Unix domain socket name.10.1.2.80; /tmp/my.sockRecommendedStable
network.peer.portintPeer port number of the network connection.65123RecommendedStable
network.protocol.namestringOSI application layer or non-OSI equivalent. [1]amqp; http; mqttRecommendedStable
network.protocol.versionstringThe actual version of the protocol used for network communication. [2]1.1; 2RecommendedStable
network.transportstringOSI transport layer or inter-process communication method. [3]tcp; udpRecommendedStable
network.typestringOSI network layer or non-OSI equivalent. [4]ipv4; ipv6RecommendedStable

[1]: The value SHOULD be normalized to lowercase.

[2]: If protocol version is subject to negotiation (for example using ALPN), this attribute SHOULD be set to the negotiated version. If the actual protocol version is not known, this attribute SHOULD NOT be set.

[3]: The value SHOULD be normalized to lowercase.

Consider always setting the transport when setting a port number, since a port number is ambiguous without knowing the transport. For example different processes could be listening on TCP port 12345 and UDP port 12345.

[4]: The value SHOULD be normalized to lowercase.

network.transport has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
pipeNamed or anonymous pipe.Stable
quicQUICExperimental
tcpTCPStable
udpUDPStable
unixUnix domain socketStable

network.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
ipv4IPv4Stable
ipv6IPv6Stable

network.peer.* and network.local.* attributes

These attributes identify network peers that are directly connected to each other.

network.peer.address and network.local.address should be IP addresses, Unix domain socket names, or other addresses specific to network type.

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

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

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

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

Client/server examples using network.peer.*

Note that network.local.* attributes are not included in these examples since they are typically Opt-In.

Simple client/server example
simple.png
Client/server example with reverse proxy
reverse-proxy.png
Client/server example with forward proxy
forward-proxy.png

Network connection and carrier attributes

AttributeTypeDescriptionExamplesRequirement LevelStability
network.carrier.iccstringThe ISO 3166-1 alpha-2 2-character country code associated with the mobile carrier network.DERecommendedExperimental
network.carrier.mccstringThe mobile carrier country code.310RecommendedExperimental
network.carrier.mncstringThe mobile carrier network code.001RecommendedExperimental
network.carrier.namestringThe name of the mobile carrier.sprintRecommendedExperimental
network.connection.subtypestringThis describes more details regarding the connection.type. It may be the type of cell technology connection, but it could be used for describing details about a wifi connection.LTERecommendedExperimental
network.connection.typestringThe internet connection type.wifiRecommendedExperimental

network.connection.subtype has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
cdmaCDMAExperimental
cdma2000_1xrttCDMA2000 1XRTTExperimental
edgeEDGEExperimental
ehrpdEHRPDExperimental
evdo_0EVDO Rel. 0Experimental
evdo_aEVDO Rev. AExperimental
evdo_bEVDO Rev. BExperimental
gprsGPRSExperimental
gsmGSMExperimental
hsdpaHSDPAExperimental
hspaHSPAExperimental
hspapHSPAPExperimental
hsupaHSUPAExperimental
idenIDENExperimental
iwlanIWLANExperimental
lteLTEExperimental
lte_caLTE CAExperimental
nr5G NR (New Radio)Experimental
nrnsa5G NRNSA (New Radio Non-Standalone)Experimental
td_scdmaTD-SCDMAExperimental
umtsUMTSExperimental

network.connection.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

ValueDescriptionStability
cellcellExperimental
unavailableunavailableExperimental
unknownunknownExperimental
wifiwifiExperimental
wiredwiredExperimental

For Unix and pipe, since the connection goes over the file system instead of being directly to a known peer, server.address is the only attribute that usually makes sense (see description of server.address below).

General remote service attributes

This attribute may be used for any operation that accesses some remote service. Users can define what the name of a service is based on their particular semantics in their distributed system. Instrumentations SHOULD provide a way for users to configure this name.

AttributeTypeDescriptionExamplesRequirement LevelStability
peer.servicestringThe service.name of the remote service. SHOULD be equal to the actual service.name resource attribute of the remote service if any.AuthTokenCacheRecommendedExperimental

Examples of peer.service that users may specify:

  • A Redis cache of auth tokens as peer.service="AuthTokenCache".
  • A gRPC service rpc.service="io.opentelemetry.AuthService" may be hosted in both a gateway, peer.service="ExternalApiService" and a backend, peer.service="AuthService".

General identity attributes

These attributes may be used for any operation with an authenticated and/or authorized enduser.

AttributeTypeDescriptionExamplesRequirement LevelStability
enduser.idstringDeprecated, use user.id instead.usernameRecommendedDeprecated
Replaced by user.id attribute.
enduser.rolestringDeprecated, use user.roles instead.adminRecommendedDeprecated
Replaced by user.roles attribute.
enduser.scopestringDeprecated, no replacement at this time.read:message, write:filesRecommendedDeprecated
Removed.

These attributes describe the authenticated user driving the user agent making requests to the instrumented system. It is expected this information would be propagated unchanged from node-to-node within the system using the Baggage mechanism. These attributes should not be used to record system-to-system authentication attributes.

Examples of where the enduser.id value is extracted from:

Authentication protocolField or description
HTTP Basic/Digest Authenticationusername
OAuth 2.0 Bearer TokenOAuth 2.0 Client Identifier value from client_id for the OAuth 2.0 Client Credentials Grant flow and subject or username from get token info response for other flows using opaque tokens.
OpenID Connect 1.0 IDTokensub
SAML 2.0 Assertionurn:oasis:names:tc:SAML:2.0:assertion:Subject
KerberosPrincipalName
FrameworkField or description
JavaEE/JakartaEE Servletjavax.servlet.http.HttpServletRequest.getUserPrincipal()
Windows Communication FoundationServiceSecurityContext.Current.PrimaryIdentity

Given the sensitive nature of this information, SDKs and exporters SHOULD drop these attributes by default and then provide a configuration parameter to turn on retention for use cases where the information is required and would not violate any policies or regulations.

General thread attributes

These attributes may be used for any operation to store information about a thread that started a span.

AttributeTypeDescriptionExamplesRequirement LevelStability
thread.idintCurrent “managed” thread ID (as opposed to OS thread ID).42RecommendedExperimental
thread.namestringCurrent thread name.mainRecommendedExperimental

Examples of where thread.id and thread.name can be extracted from:

Language or platformthread.idthread.name
JVMThread.currentThread().getId()Thread.currentThread().getName()
.NETThread.CurrentThread.ManagedThreadIdThread.CurrentThread.Name
Pythonthreading.current_thread().identthreading.current_thread().name
RubyThread.current.object_idThread.current.name
C++std::this_thread::get_id()
Erlangerlang:self()erlang:process_info(self(), registered_name)

Source Code Attributes

Often a span is closely tied to a certain unit of code that is logically responsible for handling the operation that the span describes (usually the method that starts the span). For an HTTP server span, this would be the function that handles the incoming request, for example. The attributes listed below allow to report this unit of code and therefore to provide more context about the span.

AttributeTypeDescriptionExamplesRequirement LevelStability
code.columnintThe column number in code.filepath best representing the operation. It SHOULD point within the code unit named in code.function.16RecommendedExperimental
code.filepathstringThe source code file name that identifies the code unit as uniquely as possible (preferably an absolute file path)./usr/local/MyApplication/content_root/app/index.phpRecommendedExperimental
code.functionstringThe method or function name, or equivalent (usually rightmost part of the code unit’s name).serveRequestRecommendedExperimental
code.linenointThe line number in code.filepath best representing the operation. It SHOULD point within the code unit named in code.function.42RecommendedExperimental
code.namespacestringThe “namespace” within which code.function is defined. Usually the qualified class or module name, such that code.namespace + some separator + code.function form a unique identifier for the code unit.com.example.MyHttpServiceRecommendedExperimental
code.stacktracestringA stacktrace as a string in the natural representation for the language runtime. The representation is to be determined and documented by each language SIG.at com.example.GenerateTrace.methodB(GenerateTrace.java:13)\n at com.example.GenerateTrace.methodA(GenerateTrace.java:9)\n at com.example.GenerateTrace.main(GenerateTrace.java:5)Opt-InExperimental