# Semantic conventions for JSON-RPC LLMS index: [llms.txt](/llms.txt) --- **Status**: [Development][DocumentStatus] The Semantic Conventions for [JSON-RPC](https://www.jsonrpc.org/) extend and override the [RPC Semantic Conventions](README.md). ## Spans ### Client **Status:** ![Development](https://img.shields.io/badge/-development-blue) 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](/docs/specs/semconv/rpc/rpc-spans.md#name) section. **Span kind** MUST be `CLIENT`. **Span status**: refer to the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document for details on how to record span status. Responses that include an [`error` object](https://www.jsonrpc.org/specification#error_object) are considered errors. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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`](/docs/specs/semconv/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `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`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `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`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response if it is an error response recorded as a string. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if applicable and if `server.address` is set. | int | Server port number. [3] | `80`; `8080`; `443` | | [`jsonrpc.request.id`](/docs/specs/semconv/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [4] | `10`; `request-7` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. [5] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` [6] | 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`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Opt-In` | string | JSON-RPC method name provided in the request. [7] | `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.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] `jsonrpc.request.id`:** Under the [JSON-RPC specification](https://www.jsonrpc.org/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. **[5] `network.peer.address`:** If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. **[6] `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. **[7] `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): * [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) --- `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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ### Server **Status:** ![Development](https://img.shields.io/badge/-development-blue) 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](/docs/specs/semconv/rpc/rpc-spans.md#name) section. **Span kind** MUST be `SERVER`. **Span status**: refer to the [Recording Errors](/docs/specs/semconv/general/recording-errors.md) document for details on how to record span status. Responses that include an [`error` object](https://www.jsonrpc.org/specification#error_object) are considered errors. **Attributes:** | Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`error.type`](/docs/specs/semconv/registry/attributes/error.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `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`](/docs/specs/semconv/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `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`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `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`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Conditionally Required` when available | string | The [`error.code`](https://www.jsonrpc.org/specification#error_object) property of response recorded as a string. [2] | `OK`; `DEADLINE_EXCEEDED`; `-32602` | | [`server.address`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` If available. | string | A string identifying a group of RPC server instances request is sent to. [3] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`server.port`](/docs/specs/semconv/registry/attributes/server.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Conditionally Required` if applicable and if `server.address` is set. | int | Server port number. [4] | `80`; `8080`; `443` | | [`client.address`](/docs/specs/semconv/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Client address - domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. [5] | `client.example.com`; `10.1.2.80`; `/tmp/my.sock` | | [`client.port`](/docs/specs/semconv/registry/attributes/client.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | int | Client port number. [6] | `65123` | | [`jsonrpc.request.id`](/docs/specs/semconv/registry/attributes/jsonrpc.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | A string representation of the `id` property of the request and its corresponding response. [7] | `10`; `request-7` | | [`network.peer.address`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` | string | Peer address of the network connection - IP address or Unix domain socket name. [8] | `10.1.2.80`; `/tmp/my.sock` | | [`network.peer.port`](/docs/specs/semconv/registry/attributes/network.md) | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | `Recommended` If `network.peer.address` is set. | int | Peer port number of the network connection. | `65123` | | [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) | ![Release Candidate](https://img.shields.io/badge/-rc-mediumorchid) | `Opt-In` | string | JSON-RPC method name provided in the request. [9] | `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 a DNS name, an endpoint and path in the service registry, local socket name or an IP address. Semantic conventions for individual RPC systems SHOULD document how to populate this attribute. When address is an IP address, instrumentations SHOULD NOT do a reverse DNS lookup to obtain a DNS name and SHOULD set `server.address` to the provided IP address. **[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] `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. **[6] `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. **[7] `jsonrpc.request.id`:** Under the [JSON-RPC specification](https://www.jsonrpc.org/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. **[8] `network.peer.address`:** If a RPC involved multiple network calls (for example retries), the last contacted address SHOULD be used. **[9] `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): * [`rpc.method`](/docs/specs/semconv/registry/attributes/rpc.md) * [`server.address`](/docs/specs/semconv/registry/attributes/server.md) * [`server.port`](/docs/specs/semconv/registry/attributes/server.md) --- `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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | ## Metrics JSON-RPC instrumentations SHOULD collect metrics according to the general [Semantic Conventions for RPC Metrics](/docs/specs/semconv/rpc/rpc-metrics.md). `rpc.system.name` MUST be set to `"jsonrpc"`. [DocumentStatus]: /docs/specs/otel/document-status