Semantic conventions for RPC spans
Status: Development
This document defines how to describe remote procedure calls (also called “remote method invocations” / “RMI”) with spans.
Warning Existing RPC instrumentations that are using v1.37.0 of this document (or prior):
- SHOULD NOT change the version of the RPC conventions that they emit by default in their existing major version. Conventions include (but are not limited to) attributes, metric and span names, and unit of measure.
- SHOULD introduce an environment variable
OTEL_SEMCONV_STABILITY_OPT_INin their existing major version as a comma-separated list of category-specific values (e.g., http, databases, rpc). The list of values includes:
rpc- emit the stable RPC conventions, and stop emitting the experimental RPC conventions that the instrumentation emitted previously.rpc/dup- emit both the experimental and stable RPC conventions, allowing for a phased rollout of the stable semantic conventions.- The default behavior (in the absence of one of these values) is to continue emitting whatever version of the old experimental RPC conventions the instrumentation was emitting previously.
- Note:
rpc/duphas higher precedence thanrpcin case both values are present- SHOULD maintain (security patching at a minimum) their existing major version for at least six months after it starts emitting both sets of conventions.
- MAY drop the environment variable in their next major version and emit only the stable RPC conventions.
Common remote procedure call conventions
Span name
The span name MUST be the full RPC method name formatted as:
$package.$service/$method
(where $service MUST NOT contain dots and $method MUST NOT contain slashes)
If there is no package name or if it is unknown, the $package. part (including the period) is omitted.
Examples of span names:
grpc.test.EchoService/Echocom.example.ExampleRmiService/exampleMethodMyCalcService.Calculator/Addreported by the server andMyServiceReference.ICalculator/Addreported by the client for .NET WCF callsMyServiceWithNoPackage/theMethod
Service name
On the server process receiving and handling the remote procedure call, the service name provided in rpc.service does not necessarily have to match the service.name resource attribute.
One process can expose multiple RPC endpoints and thus have multiple RPC service names. From a deployment perspective, as expressed by the service.* resource attributes, it will be treated as one deployed service with one service.name.
Likewise, on clients sending RPC requests to a server, the service name provided in rpc.service does not have to match the peer.service span attribute.
As an example, given a process deployed as QuoteService, this would be the name that goes into the service.name resource attribute which applies to the entire process.
This process could expose two RPC endpoints, one called CurrencyQuotes (= rpc.service) with a method called getMeanRate (= rpc.method) and the other endpoint called StockQuotes (= rpc.service) with two methods getCurrentBid and getLastClose (= rpc.method).
In this example, spans representing client request should have their peer.service attribute set to QuoteService as well to match the server’s service.name resource attribute.
Generally, a user SHOULD NOT set peer.service to a fully qualified RPC service name.
RPC client span
Status:
This span represents an outgoing Remote Procedure Call (RPC).
Span name: refer to the Span Name section.
Span kind MUST be CLIENT.
Span status SHOULD follow the Recording Errors document.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.system |  | Required | string | A string identifying the remoting system. See below for a list of well-known identifiers. | grpc; java_rmi; dotnet_wcf |
server.address |  | Required | string | RPC server host name. [1] | example.com; 10.1.2.80; /tmp/my.sock |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | timeout; java.net.UnknownHostException; server_certificate_invalid; 500 |
server.port | | Conditionally Required [3] | int | Server port number. [4] | 80; 8080; 443 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or Unix domain socket name. | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended If network.peer.address is set. | int | Peer port number of the network connection. | 65123 |
network.protocol.name | | Recommended | string | OSI application layer or non-OSI equivalent. [5] | http |
network.protocol.version | | Recommended | string | The actual version of the protocol used for network communication. [6] | 1.1; 2 |
network.transport | | Recommended | string | OSI transport layer or inter-process communication method. [7] | tcp; udp |
rpc.method | | Recommended | string | This is the logical name of the method from the RPC interface perspective. [8] | exampleMethod |
rpc.service | | Recommended | string | The full (logical) name of the service being called, including its package name, if applicable. [9] | myservice.EchoService |
[1] server.address: May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set server.address to the IP address provided in the host component.
[2] error.type: The error.type SHOULD be predictable, and SHOULD have low cardinality.
When error.type is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
Instrumentations SHOULD document the list of errors they report.
The cardinality of error.type within one instrumentation library SHOULD be low.
Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for error.type to have high cardinality at query time when no
additional filters are applied.
If the operation has completed successfully, instrumentations SHOULD NOT set error.type.
If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it’s RECOMMENDED to:
- Use a domain-specific attribute
- Set
error.typeto capture all errors, regardless of whether they are defined within the domain-specific set or not.
[3] server.port: if the port is supported by the network transport used for communication.
[4] 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.
[5] network.protocol.name: The value SHOULD be normalized to lowercase.
[6] network.protocol.version: 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.
[7] network.transport: 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.
[8] rpc.method: This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The code.function.name attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
[9] rpc.service: This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The code.namespace attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
error.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.
| Value | Description | Stability |
|---|---|---|
_OTHER | A fallback error value to be used when the instrumentation doesn’t define a custom value. | |
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.
| Value | Description | Stability |
|---|---|---|
pipe | Named or anonymous pipe. | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix domain socket | |
rpc.system 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.
| Value | Description | Stability |
|---|---|---|
apache_dubbo | Apache Dubbo | |
connect_rpc | Connect RPC | |
dotnet_wcf | .NET WCF | |
grpc | gRPC | |
java_rmi | Java RMI | |
jsonrpc | JSON-RPC | |
onc_rpc | ONC RPC (Sun RPC) | |
RPC server span
Status:
This span represents an incoming Remote Procedure Call (RPC).
Span name: refer to the Span Name section.
Span kind MUST be SERVER.
Span status SHOULD follow the Recording Errors document.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.system | | Required | string | A string identifying the remoting system. See below for a list of well-known identifiers. | grpc; java_rmi; dotnet_wcf |
server.address | | Required | string | RPC server host name. [1] | example.com; 10.1.2.80; /tmp/my.sock |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | timeout; java.net.UnknownHostException; server_certificate_invalid; 500 |
server.port | | Conditionally Required [3] | int | Server port number. [4] | 80; 8080; 443 |
client.address | | Recommended | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | client.example.com; 10.1.2.80; /tmp/my.sock |
client.port | | Recommended | int | Client port number. [6] | 65123 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or Unix domain socket name. | 10.1.2.80; /tmp/my.sock |
network.peer.port | | Recommended If network.peer.address is set. | int | Peer port number of the network connection. | 65123 |
network.protocol.name | | Recommended | string | OSI application layer or non-OSI equivalent. [7] | http |
network.protocol.version | | Recommended | string | The actual version of the protocol used for network communication. [8] | 1.1; 2 |
network.transport | | Recommended | string | OSI transport layer or inter-process communication method. [9] | tcp; udp |
rpc.method | | Recommended | string | This is the logical name of the method from the RPC interface perspective. [10] | exampleMethod |
rpc.service | | Recommended | string | The full (logical) name of the service being called, including its package name, if applicable. [11] | myservice.EchoService |
[1] server.address: May contain server IP address, DNS name, or local socket name. When host component is an IP address, instrumentations SHOULD NOT do a reverse proxy lookup to obtain DNS name and SHOULD set server.address to the IP address provided in the host component.
[2] error.type: The error.type SHOULD be predictable, and SHOULD have low cardinality.
When error.type is set to a type (e.g., an exception type), its
canonical class name identifying the type within the artifact SHOULD be used.
Instrumentations SHOULD document the list of errors they report.
The cardinality of error.type within one instrumentation library SHOULD be low.
Telemetry consumers that aggregate data from multiple instrumentation libraries and applications
should be prepared for error.type to have high cardinality at query time when no
additional filters are applied.
If the operation has completed successfully, instrumentations SHOULD NOT set error.type.
If a specific domain defines its own set of error identifiers (such as HTTP or gRPC status codes), it’s RECOMMENDED to:
- Use a domain-specific attribute
- Set
error.typeto capture all errors, regardless of whether they are defined within the domain-specific set or not.
[3] server.port: if the port is supported by the network transport used for communication.
[4] 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.
[5] 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.
[6] 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.
[7] network.protocol.name: The value SHOULD be normalized to lowercase.
[8] network.protocol.version: 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.
[9] network.transport: 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.
[10] rpc.method: This is the logical name of the method from the RPC interface perspective, which can be different from the name of any implementing method/function. The code.function.name attribute may be used to store the latter (e.g., method actually executing the call on the server side, RPC client stub method on the client side).
[11] rpc.service: This is the logical name of the service from the RPC interface perspective, which can be different from the name of any implementing class. The code.namespace attribute may be used to store the latter (despite the attribute name, it may include a class name; e.g., class with method actually executing the call on the server side, RPC client stub class on the client side).
error.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.
| Value | Description | Stability |
|---|---|---|
_OTHER | A fallback error value to be used when the instrumentation doesn’t define a custom value. | |
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.
| Value | Description | Stability |
|---|---|---|
pipe | Named or anonymous pipe. | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix domain socket | |
rpc.system 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.
| Value | Description | Stability |
|---|---|---|
apache_dubbo | Apache Dubbo | |
connect_rpc | Connect RPC | |
dotnet_wcf | .NET WCF | |
grpc | gRPC | |
java_rmi | Java RMI | |
jsonrpc | JSON-RPC | |
onc_rpc | ONC RPC (Sun RPC) | |
Events
Message event
Status:
The event name MUST be rpc.message.
Describes a message sent or received within the context of an RPC call.
In the lifetime of an RPC stream, an event for each message sent/received on client and server spans SHOULD be created. In case of unary calls only one sent and one received message will be recorded for both client and server spans.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
rpc.message.compressed_size | | Recommended | int | Compressed size of the message in bytes. | |
rpc.message.id | | Recommended | int | MUST be calculated as two different counters starting from 1 one for sent messages and one for received message. [1] | |
rpc.message.type | | Recommended | string | Whether this is a received or sent message. | SENT; RECEIVED |
rpc.message.uncompressed_size | | Recommended | int | Uncompressed size of the message in bytes. |
[1] rpc.message.id: This way we guarantee that the values will be consistent between different implementations.
rpc.message.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.
| Value | Description | Stability |
|---|---|---|
RECEIVED | received | |
SENT | sent | |
Distinction from HTTP spans
HTTP calls can generally be represented using just HTTP spans.
If they address a particular remote service and method known to the caller, i.e., when it is a remote procedure call transported over HTTP, the rpc.* attributes might be added additionally on that span, or in a separate RPC span that is a parent of the transporting HTTP call.
Note that method in this context is about the called remote procedure and not the HTTP verb (GET, POST, etc.).
Semantic conventions for specific RPC technologies
More specific Semantic Conventions are defined for the following RPC technologies:
- Connect: Semantic Conventions for Connect RPC.
- gRPC: Semantic Conventions for gRPC.
- JSON-RPC: Semantic Conventions for JSON-RPC.
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!