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.name 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 Refer to the Recording Errors
document for details on how to record span status. Responses that include
an error object
are considered errors.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
error.type | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [1] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 | |
jsonrpc.protocol.version | Conditionally Required If other than the default version (1.0) | string | Protocol version, as specified in the jsonrpc property of the request and its corresponding response. | 2.0; 1.0 | |
rpc.method_original | Conditionally Required If and only if it’s different than rpc.method. | string | The original name of the method used by the client. | com.myservice.EchoService/catchAll; com.myservice.EchoService/unknownMethod; InvalidMethod | |
rpc.response.status_code | Conditionally Required when available | string | The error.code property of response if it is an error response recorded as a string. [2] | OK; DEADLINE_EXCEEDED; -32602 | |
server.address | Conditionally Required If available. | string | RPC server host name. [3] | example.com; 10.1.2.80; /tmp/my.sock | |
server.port | Conditionally Required [4] | int | Server port number. [5] | 80; 8080; 443 | |
jsonrpc.request.id | Recommended | string | A string representation of the id property of the request and its corresponding response. [6] | 10; request-7 | |
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 | Opt-In | string | JSON-RPC method name provided in the request. [10] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
[1] error.type: If the RPC fails with an error before status code is returned,
error.type SHOULD be set to the exception type (its fully-qualified class name, if applicable)
or a component-specific, low cardinality error identifier.
If a response status code is returned and status indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.response.status_code are considered errors.
The error.type value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
If the request has completed successfully, instrumentations SHOULD NOT set
error.type.
[2] rpc.response.status_code: All JSON RPC error codes SHOULD be considered errors.
[3] 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.
[4] server.port: if server.address is set and 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] jsonrpc.request.id: Under the JSON-RPC specification, the id property may be a string, number, null, or omitted entirely. When omitted, the request is treated as a notification. Using null is not equivalent to omitting the id, but it is discouraged.
Instrumentations SHOULD NOT capture this attribute when the id is null or omitted.
[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: JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases.
General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to _OTHER, it MUST also set rpc.method_original span attribute to the original value.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
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.name 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 Refer to the Recording Errors
document for details on how to record span status. Responses that include
an error object
are considered errors.
Attributes:
| Key | Stability | Requirement Level | Value Type | Description | Example Values |
|---|---|---|---|---|---|
error.type | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [1] | DEADLINE_EXCEEDED; java.net.UnknownHostException; -32602 | |
jsonrpc.protocol.version | Conditionally Required If other than the default version (1.0) | string | Protocol version, as specified in the jsonrpc property of the request and its corresponding response. | 2.0; 1.0 | |
rpc.method_original | Conditionally Required If and only if it’s different than rpc.method. | string | The original name of the method used by the client. | com.myservice.EchoService/catchAll; com.myservice.EchoService/unknownMethod; InvalidMethod | |
rpc.response.status_code | Conditionally Required when available | string | The error.code property of response recorded as a string. [2] | OK; DEADLINE_EXCEEDED; -32602 | |
server.address | Conditionally Required If available. | string | RPC server host name. [3] | example.com; 10.1.2.80; /tmp/my.sock | |
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 | |
jsonrpc.request.id | Recommended | string | A string representation of the id property of the request and its corresponding response. [8] | 10; request-7 | |
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. [9] | http | |
network.protocol.version | Recommended | string | The actual version of the protocol used for network communication. [10] | 1.1; 2 | |
network.transport | Recommended | string | OSI transport layer or inter-process communication method. [11] | tcp; udp | |
rpc.method | Opt-In | string | JSON-RPC method name provided in the request. [12] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
[1] error.type: If the RPC fails with an error before status code is returned,
error.type SHOULD be set to the exception type (its fully-qualified class name, if applicable)
or a component-specific, low cardinality error identifier.
If a response status code is returned and status indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.response.status_code are considered errors.
The error.type value SHOULD be predictable and SHOULD have low cardinality.
Instrumentations SHOULD document the list of errors they report.
If the request has completed successfully, instrumentations SHOULD NOT set
error.type.
[2] rpc.response.status_code: All JSON RPC error codes SHOULD be considered errors.
[3] 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.
[4] server.port: if server.address is set and 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] jsonrpc.request.id: Under the JSON-RPC specification, the id property may be a string, number, null, or omitted entirely. When omitted, the request is treated as a notification. Using null is not equivalent to omitting the id, but it is discouraged.
Instrumentations SHOULD NOT capture this attribute when the id is null or omitted.
[9] network.protocol.name: The value SHOULD be normalized to lowercase.
[10] 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.
[11] 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.
[12] rpc.method: JSON-RPC supports sending and receiving arbitrary method names without prior registration or definition. As a result, the method name MAY have unbounded cardinality in edge or error cases.
General-purpose JSON-RPC instrumentations therefore SHOULD NOT set this attribute by default and SHOULD provide a way to configure the list of recognized RPC methods. When tracing instrumentation converts RPC method to _OTHER, it MUST also set rpc.method_original span attribute to the original value.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
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 |
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!