Semantic conventions for RPC metrics

Status: Development

The conventions described in this section are RPC specific. When RPC operations occur, measurements about those operations are recorded to instruments. The measurements are aggregated and exported as metrics, which provide insight into those operations. By including RPC properties as attributes on measurements, the metrics can be filtered for finer grain analysis.

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_IN in 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/dup has higher precedence than rpc in 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.

Metric instruments

The following metric instruments MUST be used to describe RPC operations. They MUST be of the specified type and units.

Note: RPC server and client metrics are split to allow correlation across client/server boundaries, e.g. Lining up an RPC method latency to determine if the server is responsible for latency the client is seeing.

RPC server

Below is a list of RPC server metric instruments.

Metric: rpc.server.duration

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
rpc.server.duration	Histogram	ms	Measures the duration of inbound RPC. [1]

[1]: While streaming RPCs may record this metric as start-of-batch to end-of-batch, it’s hard to interpret in practice.

Streaming: N/A.

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
error.type		Conditionally Required If and only if the operation failed.	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
network.protocol.name		Recommended	string	OSI application layer or non-OSI equivalent. [2]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [3]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [4]	tcp; udp
rpc.method		Recommended	string	This is the logical name of the method from the RPC interface perspective.	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable.	myservice.EchoService
server.address		Opt-In	string	Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.	example.com; 10.1.2.80; /tmp/my.sock
server.port		Opt-In	int	Server port number.	80; 8080; 443

[1] 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.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[2] network.protocol.name: The value SHOULD be normalized to lowercase.

[3] 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.

[4] 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.

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)

Metric: rpc.server.request.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
rpc.server.request.size	Histogram	By	Measures the size of RPC request messages (uncompressed). [1]

[1]: Streaming: Recorded per message in a streaming batch

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
error.type		Conditionally Required If and only if the operation failed.	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
network.protocol.name		Recommended	string	OSI application layer or non-OSI equivalent. [2]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [3]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [4]	tcp; udp
rpc.method		Recommended	string	This is the logical name of the method from the RPC interface perspective.	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable.	myservice.EchoService
server.address		Opt-In	string	Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.	example.com; 10.1.2.80; /tmp/my.sock
server.port		Opt-In	int	Server port number.	80; 8080; 443

[1] 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.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[2] network.protocol.name: The value SHOULD be normalized to lowercase.

[3] 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.

[4] 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.

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)

Metric: rpc.server.response.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
rpc.server.response.size	Histogram	By	Measures the size of RPC response messages (uncompressed). [1]

[1]: Streaming: Recorded per response in a streaming batch

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
error.type		Conditionally Required If and only if the operation failed.	string	Describes a class of error the operation ended with. [1]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
network.protocol.name		Recommended	string	OSI application layer or non-OSI equivalent. [2]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [3]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [4]	tcp; udp
rpc.method		Recommended	string	This is the logical name of the method from the RPC interface perspective.	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable.	myservice.EchoService
server.address		Opt-In	string	Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name.	example.com; 10.1.2.80; /tmp/my.sock
server.port		Opt-In	int	Server port number.	80; 8080; 443

[1] 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.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[2] network.protocol.name: The value SHOULD be normalized to lowercase.

[3] 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.

[4] 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.

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 client

Below is a list of RPC client metric instruments. These apply to traditional RPC usage, not streaming RPCs.

Metric: rpc.client.duration

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
rpc.client.duration	Histogram	ms	Measures the duration of outbound RPC. [1]

[1]: While streaming RPCs may record this metric as start-of-batch to end-of-batch, it’s hard to interpret in practice.

Streaming: N/A.

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	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
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 If applicable.	int	Server port number. [3]	80; 8080; 443
network.protocol.name		Recommended	string	OSI application layer or non-OSI equivalent. [4]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [5]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [6]	tcp; udp
rpc.method		Recommended	string	This is the logical name of the method from the RPC interface perspective.	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable.	myservice.EchoService

[1] server.address: 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] 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.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[3] 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.

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

[5] 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.

[6] 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.

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)

Metric: rpc.client.request.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
rpc.client.request.size	Histogram	By	Measures the size of RPC request messages (uncompressed). [1]

[1]: Streaming: Recorded per message in a streaming batch

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	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
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 If applicable.	int	Server port number. [3]	80; 8080; 443
network.protocol.name		Recommended	string	OSI application layer or non-OSI equivalent. [4]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [5]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [6]	tcp; udp
rpc.method		Recommended	string	This is the logical name of the method from the RPC interface perspective.	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable.	myservice.EchoService

[1] server.address: 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] 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.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[3] 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.

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

[5] 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.

[6] 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.

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)

Metric: rpc.client.response.size

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
rpc.client.response.size	Histogram	By	Measures the size of RPC response messages (uncompressed). [1]

[1]: Streaming: Recorded per response in a streaming batch

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	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
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 If applicable.	int	Server port number. [3]	80; 8080; 443
network.protocol.name		Recommended	string	OSI application layer or non-OSI equivalent. [4]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [5]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [6]	tcp; udp
rpc.method		Recommended	string	This is the logical name of the method from the RPC interface perspective.	exampleMethod
rpc.service		Recommended	string	The full (logical) name of the service being called, including its package name, if applicable.	myservice.EchoService

[1] server.address: 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] 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.type to capture all errors, regardless of whether they are defined within the domain-specific set or not.

[3] 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.

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

[5] 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.

[6] 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.

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)

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.

Specifications defined by maintainers of RPC systems:

• gRPC: Semantic Conventions for gRPC.