JSON-RPC 的语义约定
状态: 开发中
JSON-RPC 的语义约定扩展并覆盖了 RPC Span 和 RPC Metrics 的语义约定，后者描述了通用的 RPC 操作属性，此外还包括本页面描述的语义约定。
客户端 Span
状态:
此 Span 代表一个出站的远程过程调用 (RPC)。
rpc.system 必须设置为 "jsonrpc"，并且应在创建 Span 时提供。
Span 名称：请参考 Span 名称 部分。
Span 类型必须为 CLIENT。
**Span 状态**应遵循 记录错误文档。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
rpc.method |  | 必需 | 字符串 | 从 RPC 接口的角度来看，这是方法的逻辑名称。[1] | exampleMethod |
server.address |  | 必需 | 字符串 | RPC 服务器主机名。[2] | example.com；10.1.2.80；/tmp/my.sock |
error.type | | 有条件必需 仅在操作失败时。 | 字符串 | 描述操作结束的错误类别。[3] | timeout；java.net.UnknownHostException；server_certificate_invalid；500 |
rpc.jsonrpc.error_code | | 如果可用，则条件必需 | int | 如果响应是错误响应，则为响应的 error.code 属性。 | -32700; 100 |
rpc.jsonrpc.version | | 条件必需 如果与默认版本 (1.0) 不同 | 字符串 | 请求/响应的 jsonrpc 属性中的协议版本。由于 JSON-RPC 1.0 未指定此项，因此可以省略该值。 | 2.0; 1.0 |
server.port | | 有条件地必需 [4] | int | 服务器端口号。[5] | 80; 8080; 443 |
network.peer.address | | 推荐 | 字符串 | 网络连接的对端地址 - IP 地址或 Unix 域套接字名称。 | 10.1.2.80；/tmp/my.sock |
network.peer.port | | 如果设置了 network.peer.address，则推荐。 | int | 网络连接的对等端口号。 | 65123 |
network.protocol.name | | 推荐 | 字符串 | OSI 应用层或非 OSI 等效层。[6] | http |
network.protocol.version | | 推荐 | 字符串 | 用于网络通信的实际协议版本。[7] | 1.1; 2 |
network.transport | | 推荐 | 字符串 | OSI 传输层或进程间通信方法。[8] | tcp；udp |
rpc.jsonrpc.error_message | | 推荐 | 字符串 | 如果响应是错误响应，则为响应的 error.message 属性。 | Parse error; User already exists |
rpc.jsonrpc.request_id | | 推荐 | 字符串 | 请求或响应的 id 属性。由于协议允许 id 是整数、字符串、null 或缺失（对于通知），因此为简单起见，预期值会被转换为字符串。在 null 值的情况下使用空字符串。如果这是通知，则完全省略。 | 10; request-7; `` |
[1] rpc.method: 从 RPC 接口的角度来看，这是方法的逻辑名称，可能与任何实现的方法/函数的名称不同。code.function.name 属性可用于存储后者（例如，在服务器端实际执行调用的方法，在客户端的 RPC 客户端存根方法）。
[2] server.address: 可能包含服务器 IP 地址、DNS 名称或本地套接字名称。当主机组件是 IP 地址时，仪器不应执行反向 DNS 查找来获取 DNS 名称，并且应将 server.address 设置为主机组件中提供的 IP 地址。
[3] error.type: error.type 应是可预测的，并且应具有低基数。
当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。
Instrumentations 应该记录它们报告的错误列表。
一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。
如果操作已成功完成，Instrumentations 不应设置 error.type。
如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议
- 使用特定于域的属性
- 设置
error.type以捕获所有错误，无论它们是否包含在特定于域的集合中。
[4] server.port: 如果用于通信的网络传输支持该端口。
[5] server.port: 从客户端观察并与中介通信时，server.port 应表示任何中介（例如代理）之后的服务器端口，如果可用。
[6] network.protocol.name: 该值应规范化为小写。
[7] network.protocol.version: 如果协议版本需要协商（例如使用ALPN），则此属性应设置为协商版本。如果实际协议版本未知，则不应设置此属性。
[8] network.transport: 该值应规范化为小写。
在设置端口号时，应始终考虑设置传输协议，因为没有传输协议的端口号是模糊的。例如，不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。
error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 当检测不到自定义值时使用的回退错误值。 | |
network.transport 具有以下已知值列表。如果其中一个适用，则必须使用相应的_值_；否则，可以_使用_自定义值。
| 值 | 描述 | Stability |
|---|---|---|
pipe | 命名或匿名管道。 | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix 域套接字 | |
服务器 Span
状态:
此 Span 代表一个入站的远程过程调用 (RPC)。
rpc.system 必须设置为 "jsonrpc"，并且应在创建 Span 时提供。
Span 名称：请参考 Span 名称 部分。
Span 类型必须为 SERVER。
**Span 状态**应遵循 记录错误文档。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
rpc.method | | 必需 | 字符串 | 从 RPC 接口的角度来看，这是方法的逻辑名称。[1] | exampleMethod |
server.address | | 必需 | 字符串 | RPC 服务器主机名。[2] | example.com；10.1.2.80；/tmp/my.sock |
error.type | | 有条件必需 仅在操作失败时。 | 字符串 | 描述操作结束的错误类别。[3] | timeout；java.net.UnknownHostException；server_certificate_invalid；500 |
rpc.jsonrpc.error_code | | 如果可用，则条件必需 | int | 如果响应是错误响应，则为响应的 error.code 属性。 | -32700; 100 |
rpc.jsonrpc.version | | 条件必需 如果与默认版本 (1.0) 不同 | 字符串 | 请求/响应的 jsonrpc 属性中的协议版本。由于 JSON-RPC 1.0 未指定此项，因此可以省略该值。 | 2.0; 1.0 |
server.port | | 有条件地必需 [4] | int | 服务器端口号。[5] | 80; 8080; 443 |
client.address | | 推荐 | 字符串 | 客户端地址 - 如果在不进行反向 DNS 查找的情况下可用，则为域名；否则，为 IP 地址或 Unix 域套接字名称。[6] | client.example.com; 10.1.2.80; /tmp/my.sock |
client.port | | 推荐 | int | 客户端端口号。[7] | 65123 |
network.peer.address | | 推荐 | 字符串 | 网络连接的对端地址 - IP 地址或 Unix 域套接字名称。 | 10.1.2.80；/tmp/my.sock |
network.peer.port | | 如果设置了 network.peer.address，则推荐。 | int | 网络连接的对等端口号。 | 65123 |
network.protocol.name | | 推荐 | 字符串 | OSI 应用层或非 OSI 等效层。[8] | http |
network.protocol.version | | 推荐 | 字符串 | 用于网络通信的实际协议版本。[9] | 1.1; 2 |
network.transport | | 推荐 | 字符串 | OSI 传输层或进程间通信方法。[10] | tcp；udp |
rpc.jsonrpc.error_message | | 推荐 | 字符串 | 如果响应是错误响应，则为响应的 error.message 属性。 | Parse error; User already exists |
rpc.jsonrpc.request_id | | 推荐 | 字符串 | 请求或响应的 id 属性。由于协议允许 id 是整数、字符串、null 或缺失（对于通知），因此为简单起见，预期值会被转换为字符串。在 null 值的情况下使用空字符串。如果这是通知，则完全省略。 | 10; request-7; `` |
[1] rpc.method: 从 RPC 接口的角度来看，这是方法的逻辑名称，可能与任何实现的方法/函数的名称不同。code.function.name 属性可用于存储后者（例如，在服务器端实际执行调用的方法，在客户端的 RPC 客户端存根方法）。
[2] server.address: 可能包含服务器 IP 地址、DNS 名称或本地套接字名称。当主机组件是 IP 地址时，仪器不应执行反向 DNS 查找来获取 DNS 名称，并且应将 server.address 设置为主机组件中提供的 IP 地址。
[3] error.type: error.type 应是可预测的，并且应具有低基数。
当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。
Instrumentations 应该记录它们报告的错误列表。
一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。
如果操作已成功完成，Instrumentations 不应设置 error.type。
如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议
- 使用特定于域的属性
- 设置
error.type以捕获所有错误，无论它们是否包含在特定于域的集合中。
[4] server.port: 如果用于通信的网络传输支持该端口。
[5] server.port: 从客户端观察并与中介通信时，server.port 应表示任何中介（例如代理）之后的服务器端口，如果可用。
[6] client.address: 当从服务器端观察到时，并且在通过中介通信时，client.address 应代表中介（例如代理）之后的客户端地址，如果可用。
[7] client.port: 当从服务器端观察到时，并且在通过中介通信时，client.port 应代表中介（例如代理）之后的客户端端口，如果可用。
[8] network.protocol.name: 该值应规范化为小写。
[9] network.protocol.version: 如果协议版本需要协商（例如使用ALPN），则此属性应设置为协商版本。如果实际协议版本未知，则不应设置此属性。
[10] network.transport: 该值应规范化为小写。
在设置端口号时，应始终考虑设置传输协议，因为没有传输协议的端口号是模糊的。例如，不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。
error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 当检测不到自定义值时使用的回退错误值。 | |
network.transport 具有以下已知值列表。如果其中一个适用，则必须使用相应的_值_；否则，可以_使用_自定义值。
| 值 | 描述 | Stability |
|---|---|---|
pipe | 命名或匿名管道。 | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix 域套接字 | |