Semantic conventions for JSON-RPC
Status: Development
The Semantic Conventions for JSON-RPC extend and override the RPC Semantic Conventions.
Spans
Client
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: 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 |
|---|---|---|---|---|---|
rpc.system.name |  | Required | string | The Remote Procedure Call (RPC) system. [1] | jsonrpc |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | 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.status_code | | Conditionally Required when available | string | The error.code property of response if it is an error response recorded as a string. [3] | OK; DEADLINE_EXCEEDED; -32602 |
server.port | | Conditionally Required if applicable and if server.address is set. | int | Server port number. [4] | 80; 8080; 443 |
jsonrpc.request.id | | Recommended | string | A string representation of the id property of the request and its corresponding response. [5] | 10; request-7 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or UNIX domain socket name. [6] | 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 |
server.address | | Recommended [7] | string | A string identifying a group of RPC server instances request is sent to. | example.com; 10.1.2.80; /tmp/my.sock |
rpc.method | | Opt-In | string | JSON-RPC method name provided in the request. [8] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
rpc.request.header.<key> |  | Opt-In | string[] | RPC request headers or metadata, <key> being the normalized header name (lowercase), the value being the header values. [9] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.header.<key> | | Opt-In | string[] | RPC response headers or metadata sent before the response payload, <key> being the normalized header name (lowercase), the value being the header values. [10] | ["attribute_value"] |
rpc.response.trailer.<key> | | Opt-In | string[] | RPC response trailers or metadata sent after the response payload, <key> being the normalized trailer name (lowercase), the value being the trailer values. [11] | ["attribute_value"] |
[1] rpc.system.name: MUST be set to jsonrpc.
[2] 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 status code is returned and it indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.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.
[3] rpc.status_code: All JSON RPC error codes SHOULD be considered errors.
Instrumentations MAY use additional context or provide configuration options to customize which error codes are considered errors.
[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] 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.
[6] network.peer.address: If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used.
[7] server.address: Instrumentations that have access to the transport-level information and can reliably extract domain name or another low-cardinality server address from it SHOULD set this attribute.
[8] 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.
[9] 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.
[10] 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.
[11] 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.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
Server
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: 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 |
|---|---|---|---|---|---|
rpc.system.name | | Required | string | The Remote Procedure Call (RPC) system. [1] | jsonrpc |
error.type | | Conditionally Required If and only if the operation failed. | string | Describes a class of error the operation ended with. [2] | 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.status_code | | Conditionally Required when available | string | The error.code property of response recorded as a string. [3] | OK; DEADLINE_EXCEEDED; -32602 |
server.port | | Conditionally Required if applicable and if server.address is set. | int | Server port number. [4] | 80; 8080; 443 |
jsonrpc.request.id | | Recommended | string | A string representation of the id property of the request and its corresponding response. [5] | 10; request-7 |
network.peer.address | | Recommended | string | Peer address of the network connection - IP address or UNIX domain socket name. [6] | 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 |
server.address | | Recommended when available. | string | A string identifying a group of RPC server instances request is sent to. [7] | example.com; 10.1.2.80; /tmp/my.sock |
rpc.method | | Opt-In | string | JSON-RPC method name provided in the request. [8] | com.example.ExampleService/exampleMethod; EchoService/Echo; _OTHER |
rpc.request.header.<key> | | Opt-In | string[] | RPC request headers or metadata, <key> being the normalized header name (lowercase), the value being the header values. [9] | ["1.2.3.4", "1.2.3.5"] |
rpc.response.header.<key> | | Opt-In | string[] | RPC response headers or metadata sent before the response payload, <key> being the normalized header name (lowercase), the value being the header values. [10] | ["attribute_value"] |
rpc.response.trailer.<key> | | Opt-In | string[] | RPC response trailers or metadata sent after the response payload, <key> being the normalized trailer name (lowercase), the value being the trailer values. [11] | ["attribute_value"] |
[1] rpc.system.name: MUST be set to jsonrpc.
[2] 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 status code is returned and it indicates an error,
error.type SHOULD be set to that status code. Check system-specific conventions
for the details on which values of rpc.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.
[3] rpc.status_code: All JSON RPC error codes SHOULD be considered errors.
Instrumentations MAY use additional context or provide configuration options to customize which error codes are considered errors.
[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] 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.
[6] network.peer.address: If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used.
[7] server.address: server.address and server.port describe the address the client used to reach this server, as reported by the transport or RPC framework. Instrumentations SHOULD NOT use actual network-level connection information to populate these attributes. If the address used by the client is unavailable, instrumentations SHOULD NOT set these attributes.
[8] 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.
[9] 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.
[10] 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.
[11] 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.
The following attributes can be important for making sampling decisions and SHOULD be provided at span creation time (if provided at all):
Metrics
JSON-RPC instrumentations SHOULD collect metrics according to the general Semantic Conventions for RPC Metrics.
rpc.system.name MUST be set to "jsonrpc".
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!