RPC

• Remote Procedure Call (RPC) Attributes
• Deprecated RPC Attributes

Remote Procedure Call (RPC) Attributes

This document defines attributes for remote procedure calls.

Attributes:

Key	Stability	Value Type	Description	Example Values
rpc.method		string	The fully-qualified logical name of the method from the RPC interface perspective. [1]	com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER
rpc.method_original		string	The original name of the method used by the client.	com.myservice.EchoService/catchAll; com.myservice.EchoService/unknownMethod; InvalidMethod
rpc.request.header.<key>		string[]	RPC request headers or metadata, <key> being the normalized header name (lowercase), the value being the header values. [2]	["1.2.3.4", "1.2.3.5"]
rpc.response.header.<key>		string[]	RPC response headers or metadata sent before the response payload, <key> being the normalized header name (lowercase), the value being the header values. [3]	["attribute_value"]
rpc.response.trailer.<key>		string[]	RPC response trailers or metadata sent after the response payload, <key> being the normalized trailer name (lowercase), the value being the trailer values. [4]	["attribute_value"]
rpc.status_code		string	Status code of the RPC returned by the RPC server or generated by the client [5]	OK; DEADLINE_EXCEEDED; -32602
rpc.system.name		string	The Remote Procedure Call (RPC) system. [6]	grpc; dubbo; connectrpc (see more)

[1] rpc.method: The method name MAY have unbounded cardinality in edge or error cases.

Some RPC frameworks or libraries provide a fixed set of recognized methods for client stubs and server implementations. Instrumentations for such frameworks MUST set this attribute to the original method name only when the method is recognized by the framework or library.

When the method is not recognized, for example, when the server receives a request for a method that is not predefined on the server, or when instrumentation is not able to reliably detect if the method is predefined, the attribute MUST be set to _OTHER.

If the RPC instrumentation could end up converting valid RPC methods to _OTHER, then it SHOULD provide a way to configure the list of recognized RPC methods.

The rpc.method can be different from the name of any implementing method/function. The code.function.name attribute may be used to record the fully-qualified method actually executing the call on the server side, or the RPC client stub method on the client side.

[2] rpc.request.header.<key>: Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all request headers can be a security risk - explicit configuration helps avoid leaking sensitive information.

For example, a header my-custom-key with value ["1.2.3.4", "1.2.3.5"] SHOULD be recorded as the rpc.request.header.my-custom-key attribute with value ["1.2.3.4", "1.2.3.5"]

The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers.

Values that the RPC system exposes as binary data, or that are otherwise not valid UTF-8 strings, SHOULD be base64-encoded when recorded.

[3] rpc.response.header.<key>: Instrumentations SHOULD require an explicit configuration of which headers are to be captured. Including all response headers can be a security risk - explicit configuration helps avoid leaking sensitive information.

For example, a header my-custom-key with value ["attribute_value"] SHOULD be recorded as the rpc.response.header.my-custom-key attribute with value ["attribute_value"]

The attribute value MUST consist of either multiple header values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to headers.

Values that the RPC system exposes as binary data, or that are otherwise not valid UTF-8 strings, SHOULD be base64-encoded when recorded.

[4] rpc.response.trailer.<key>: Instrumentations SHOULD require an explicit configuration of which trailers are to be captured. Including all response trailers can be a security risk - explicit configuration helps avoid leaking sensitive information.

For example, a trailer my-custom-key with value ["attribute_value"] SHOULD be recorded as the rpc.response.trailer.my-custom-key attribute with value ["attribute_value"]

The attribute value MUST consist of either multiple trailer values as an array of strings or a single-item array containing a possibly comma-concatenated string, depending on the way the RPC library provides access to trailers.

Values that the RPC system exposes as binary data, or that are otherwise not valid UTF-8 strings, SHOULD be base64-encoded when recorded.

[5] rpc.status_code: Usually it represents an error code, but may also represent partial success, warning, or differentiate between various types of successful outcomes. The value MAY use a standardized string representation of a numeric status code, if one exists, instead of the numeric code. The value MAY be a synthetic status provided by the client library rather than returned by the remote service. Semantic conventions for individual RPC frameworks SHOULD document what rpc.status_code means in the context of that system and which values are considered to represent errors.

[6] rpc.system.name: The client and server RPC systems may differ for the same RPC interaction. For example, a client may use Apache Dubbo or Connect RPC to communicate with a server that uses gRPC since both protocols provide compatibility with gRPC.

rpc.system.name 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
connectrpc	Connect RPC
dubbo	Apache Dubbo
grpc	gRPC
jsonrpc	JSON-RPC

Deprecated RPC Attributes

Deprecated rpc message attributes.

Attributes:

Key	Stability	Value Type	Description	Example Values
message.compressed_size	Deprecated, no replacement at this time.	int	Deprecated, no replacement at this time.
message.id	Deprecated, no replacement at this time.	int	Deprecated, no replacement at this time.
message.type	Deprecated, no replacement at this time.	string	Deprecated, no replacement at this time.	SENT; RECEIVED (see more)
message.uncompressed_size	Deprecated, no replacement at this time.	int	Deprecated, no replacement at this time.
rpc.connect_rpc.error_code	Replaced by rpc.status_code.	string	Deprecated, use rpc.status_code attribute instead.	cancelled; unknown; invalid_argument (see more)
rpc.connect_rpc.request.metadata.<key>	Replaced by rpc.request.header.	string[]	Deprecated, use rpc.request.header instead.	["1.2.3.4", "1.2.3.5"]
rpc.connect_rpc.response.metadata.<key>	Split to rpc.response.header for metadata sent before the response payload and rpc.response.trailer for metadata sent after it.	string[]	Deprecated, use rpc.response.header and rpc.response.trailer.	["attribute_value"]
rpc.grpc.request.metadata.<key>	Replaced by rpc.request.header.	string[]	Deprecated, use rpc.request.header instead.	["1.2.3.4", "1.2.3.5"]
rpc.grpc.response.metadata.<key>	Split to rpc.response.header for metadata sent before the response payload and rpc.response.trailer for metadata sent after it.	string[]	Deprecated, use rpc.response.header and rpc.response.trailer.	["attribute_value"]
rpc.grpc.status_code	Use string representation of the gRPC status code on the rpc.status_code attribute.	int	Deprecated, use string representation on the rpc.status_code attribute instead.	0; 1; 2 (see more)
rpc.jsonrpc.error_code	Use string representation of the error code on the rpc.status_code attribute.	int	Deprecated, use string representation on the rpc.status_code attribute instead.	-32700; 100
rpc.jsonrpc.error_message	Use the span status description when reporting JSON-RPC spans.	string	Deprecated, use the span status description when reporting JSON-RPC spans.	Parse error; User already exists
rpc.jsonrpc.request_id	Replaced by jsonrpc.request.id.	string	Deprecated, use jsonrpc.request.id instead.	10; request-7; ``
rpc.jsonrpc.version	Replaced by jsonrpc.protocol.version.	string	Deprecated, use jsonrpc.protocol.version instead.	2.0; 1.0
rpc.message.compressed_size	Deprecated, no replacement at this time.	int	Compressed size of the message in bytes.
rpc.message.id	Deprecated, no replacement at this time.	int	MUST be calculated as two different counters starting from 1 one for sent messages and one for received message. [7]
rpc.message.type	Deprecated, no replacement at this time.	string	Whether this is a received or sent message.	SENT; RECEIVED (see more)
rpc.message.uncompressed_size	Deprecated, no replacement at this time.	int	Uncompressed size of the message in bytes.
rpc.request.metadata.<key>	Replaced by rpc.request.header.	string[]	Deprecated, use rpc.request.header instead.	["1.2.3.4", "1.2.3.5"]
rpc.response.metadata.<key>	Split to rpc.response.header for metadata sent before the response payload and rpc.response.trailer for metadata sent after it.	string[]	Deprecated, use rpc.response.header and rpc.response.trailer.	["attribute_value"]
rpc.response.status_code	Replaced by rpc.status_code.	string	Deprecated, use rpc.status_code instead.	OK; DEADLINE_EXCEEDED; -32602
rpc.service	Value should be included in rpc.method which is expected to be a fully-qualified name.	string	Deprecated, use fully-qualified rpc.method instead.	myservice.EchoService
rpc.system	Replaced by rpc.system.name.	string	Deprecated, use rpc.system.name attribute instead.	grpc; java_rmi; dotnet_wcf (see more)

[7] rpc.message.id: This way we guarantee that the values will be consistent between different implementations.

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

rpc.connect_rpc.error_code 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
aborted	aborted
already_exists	already_exists
cancelled	cancelled
data_loss	data_loss
deadline_exceeded	deadline_exceeded
failed_precondition	failed_precondition
internal	internal
invalid_argument	invalid_argument
not_found	not_found
out_of_range	out_of_range
permission_denied	permission_denied
resource_exhausted	resource_exhausted
unauthenticated	unauthenticated
unavailable	unavailable
unimplemented	unimplemented
unknown	unknown

rpc.grpc.status_code 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
0	OK
1	CANCELLED
2	UNKNOWN
3	INVALID_ARGUMENT
4	DEADLINE_EXCEEDED
5	NOT_FOUND
6	ALREADY_EXISTS
7	PERMISSION_DENIED
8	RESOURCE_EXHAUSTED
9	FAILED_PRECONDITION
10	ABORTED
11	OUT_OF_RANGE
12	UNIMPLEMENTED
13	INTERNAL
14	UNAVAILABLE
15	DATA_LOSS
16	UNAUTHENTICATED

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

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)