Semantic conventions for JSON-RPC

Status: Development

The Semantic Conventions for JSON-RPC extend and override the RPC spans and RPC metrics Semantic Conventions that describe common RPC operations attributes in addition to the Semantic Conventions described on this page.

Client Span

Status:

This span represents an outgoing Remote Procedure Call (RPC).

rpc.system MUST be set to "jsonrpc" and SHOULD be provided at span creation time.

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.method		Required	string	This is the logical name of the method from the RPC interface perspective. [1]	exampleMethod
server.address		Required	string	RPC server host name. [2]	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. [3]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
rpc.jsonrpc.error_code		Conditionally Required when available	int	error.code property of response if it is an error response.	-32700; 100
rpc.jsonrpc.version		Conditionally Required If other than the default version (1.0)	string	Protocol version as in jsonrpc property of request/response. Since JSON-RPC 1.0 doesn’t specify this, the value can be omitted.	2.0; 1.0
server.port		Conditionally Required [4]	int	Server port number. [5]	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. [6]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [7]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [8]	tcp; udp
rpc.jsonrpc.error_message		Recommended	string	error.message property of response if it is an error response.	Parse error; User already exists
rpc.jsonrpc.request_id		Recommended	string	id property of request or response. Since protocol allows id to be int, string, null or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of null value. Omit entirely if this is a notification.	10; request-7; ``

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

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

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

[4] server.port: if the port is supported by the network transport used for communication.

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

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

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

[8] 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

Server Span

Status:

This span represents an incoming Remote Procedure Call (RPC).

rpc.system MUST be set to "jsonrpc" and SHOULD be provided at span creation time.

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.method		Required	string	This is the logical name of the method from the RPC interface perspective. [1]	exampleMethod
server.address		Required	string	RPC server host name. [2]	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. [3]	timeout; java.net.UnknownHostException; server_certificate_invalid; 500
rpc.jsonrpc.error_code		Conditionally Required when available	int	error.code property of response if it is an error response.	-32700; 100
rpc.jsonrpc.version		Conditionally Required If other than the default version (1.0)	string	Protocol version as in jsonrpc property of request/response. Since JSON-RPC 1.0 doesn’t specify this, the value can be omitted.	2.0; 1.0
server.port		Conditionally Required [4]	int	Server port number. [5]	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. [6]	client.example.com; 10.1.2.80; /tmp/my.sock
client.port		Recommended	int	Client port number. [7]	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. [8]	http
network.protocol.version		Recommended	string	The actual version of the protocol used for network communication. [9]	1.1; 2
network.transport		Recommended	string	OSI transport layer or inter-process communication method. [10]	tcp; udp
rpc.jsonrpc.error_message		Recommended	string	error.message property of response if it is an error response.	Parse error; User already exists
rpc.jsonrpc.request_id		Recommended	string	id property of request or response. Since protocol allows id to be int, string, null or missing (for notifications), value is expected to be cast to string for simplicity. Use empty string in case of null value. Omit entirely if this is a notification.	10; request-7; ``

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

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

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

[4] server.port: if the port is supported by the network transport used for communication.

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

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

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

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

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

[10] 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