Connect RPC 的语义约定

状态: 开发中

Connect 的语义约定扩展并覆盖了 Connect 的 RPC spans 和 RPC metrics 语义约定，它们描述了常见的 RPC 操作属性，并补充了本页面的语义约定。

客户端 Span

状态:

此 Span 代表一个出站的远程过程调用 (RPC)。

rpc.system 必须设置为 "connect_rpc"，并且应在创建 Span 时提供。

Span 名称：请参考 Span 名称部分。

Span 类型必须为 CLIENT。

**Span 状态**应遵循记录错误文档。

Attributes

键	需求级别	Value Type	描述	Example Values
`server.address`	`必需`	字符串	RPC 服务器主机名。[1]	`example.com`；`10.1.2.80`；`/tmp/my.sock`
`error.type`	`有条件必需` 仅在操作失败时。	字符串	描述操作结束时发生的错误类型。[2]	`timeout`；`java.net.UnknownHostException`；`server_certificate_invalid`；`500`
`rpc.connect_rpc.error_code`	如果可用，则为`条件必需`。	字符串	Connect 请求的错误代码。错误代码始终是字符串值。	`cancelled`; `unknown`; `invalid_argument`
`server.port`	`有条件地必需` [3]	int	服务器端口号。[4]	`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 等效层。[5]	`http`
`network.protocol.version`	`推荐`	字符串	用于网络通信的协议的实际版本。[6]	`1.1`; `2`
`network.transport`	`推荐`	字符串	OSI 传输层或进程间通信方法。[7]	`tcp`；`udp`
`rpc.method`	`推荐`	字符串	这是从 RPC 接口角度看的方法的逻辑名称。[8]	`exampleMethod`
`rpc.service`	`推荐`	字符串	正在调用的服务的完整（逻辑）名称，包括其包名称（如果适用）。[9]	`myservice.EchoService`
`rpc.connect_rpc.request.metadata.<key>`	`选择加入`	string[]	Connect 请求元数据，`<key>` 是规范化的 Connect 元数据键（小写），值为元数据值。[10]	`["1.2.3.4", "1.2.3.5"]`
`rpc.connect_rpc.response.metadata.<key>`	`选择加入`	string[]	Connect 响应元数据，`<key>` 是规范化的 Connect 元数据键（小写），值为元数据值。[11]	`["attribute_value"]`

[1] server.address: 可能包含服务器 IP 地址、DNS 名称或本地套接字名称。当主机组件是 IP 地址时，仪器化不应进行反向 DNS 查找以获取 DNS 名称，而应将 server.address 设置为主机组件中提供的 IP 地址。

[2] error.type: error.type 应可预测且具有低基数。

当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。

Instrumentations 应该记录它们报告的错误列表。

一个仪器库内的 error.type 基数性应该低。从多个仪器库和应用程序聚合数据的遥测消费者，在没有额外过滤时，应准备好 error.type 在查询时具有高基数性。

如果操作已成功完成，Instrumentations 不应设置 error.type。

如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议

使用特定于域的属性
设置 error.type 以捕获所有错误，无论它们是否包含在特定于域的集合中。

[3] server.port: 如果端口被用于通信的网络传输所支持。

[4] server.port: 从客户端观察时，并且在通过中介进行通信时，server.port 应代表任何中介（例如代理）之后的服务器端口，如果可用。

[5] network.protocol.name: 该值应规范化为小写。

[6] network.protocol.version: 如果协议版本需要协商（例如使用 ALPN），此属性应设置为协商后的版本。如果实际协议版本未知，则不应设置此属性。

[7] network.transport: 该值应规范化为小写。

在设置端口号时，应始终考虑设置传输协议，因为没有传输协议的端口号是模糊的。例如，不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[8] rpc.method: 这是从 RPC 接口角度看的方法的逻辑名称，它可能与任何实现的方法/函数名称不同。code.function.name 属性可用于存储后者（例如，实际在服务器端执行调用的方法，RPC 客户端存根方法）。

[9] rpc.service: 这是从 RPC 接口角度看的服务的逻辑名称，它可能与任何实现类的名称不同。code.namespace 属性可用于存储后者（尽管属性名称如此，但它可能包含类名；例如，在服务器端实际执行调用的方法所属的类，RPC 客户端存根类）。

[10] rpc.connect_rpc.request.metadata.<key>: 仪器化应显式配置要捕获的元数据值。包含所有请求元数据值可能存在安全风险 - 显式配置有助于避免泄露敏感信息。

例如，一个值为 ["1.2.3.4", "1.2.3.5"] 的属性 my-custom-key 应被记录为属性 rpc.connect_rpc.request.metadata.my-custom-key，值为 ["1.2.3.4", "1.2.3.5"]。

[11] rpc.connect_rpc.response.metadata.<key>: 仪器化应显式配置要捕获的元数据值。包含所有响应元数据值可能存在安全风险 - 显式配置有助于避免泄露敏感信息。

例如，一个值为 "attribute_value" 的属性 my-custom-key 应被记录为属性 rpc.connect_rpc.response.metadata.my-custom-key，值为 ["attribute_value"]。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
`_OTHER`	当检测不到自定义值时使用的回退错误值。

network.transport 具有以下已知值列表。如果其中一个适用，则必须使用相应的_值_；否则，可以_使用_自定义值。

值	描述	Stability
`pipe`	命名或匿名管道。
`quic`	QUIC
`tcp`	TCP
`udp`	UDP
`unix`	Unix 域套接字

rpc.connect_rpc.error_code 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以自定义值。

值	描述	Stability
`aborted`	aborted
`already_exists`	already_exists
`cancelled`	cancelled
`data_loss`	data_loss
`deadline_exceeded`	deadline_exceeded
`failed_precondition`	failed_precondition
`internal`	internal
`invalid_argument`	invalid_argument
`not_found`	not_found
`out_of_range`	out_of_range
`permission_denied`	permission_denied
`resource_exhausted`	resource_exhausted
`unauthenticated`	unauthenticated
`unavailable`	unavailable
`unimplemented`	unimplemented
`unknown`	unknown

服务器 Span

状态:

此 Span 代表一个入站的远程过程调用 (RPC)。

rpc.system 必须设置为 "connect_rpc"，并且应在创建 Span 时提供。

Span 名称：请参考 Span 名称部分。

Span 类型必须为 SERVER。

**Span 状态**应遵循记录错误文档。

Attributes

键	需求级别	Value Type	描述	Example Values
`server.address`	`必需`	字符串	RPC 服务器主机名。[1]	`example.com`；`10.1.2.80`；`/tmp/my.sock`
`error.type`	`有条件必需` 仅在操作失败时。	字符串	描述操作结束时发生的错误类型。[2]	`timeout`；`java.net.UnknownHostException`；`server_certificate_invalid`；`500`
`rpc.connect_rpc.error_code`	如果可用，则为`条件必需`。	字符串	Connect 请求的错误代码。错误代码始终是字符串值。	`cancelled`; `unknown`; `invalid_argument`
`server.port`	`有条件地必需` [3]	int	服务器端口号。[4]	`80`; `8080`; `443`
`client.address`	`推荐`	字符串	客户端地址 - 如果可用且无需反向 DNS 查找，则为域名；否则，为 IP 地址或 Unix 域套接字名称。[5]	`client.example.com`; `10.1.2.80`; `/tmp/my.sock`
`client.port`	`推荐`	int	客户端端口号。[6]	`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 等效层。[7]	`http`
`network.protocol.version`	`推荐`	字符串	网络通信实际使用的协议版本。[8]	`1.1`; `2`
`network.transport`	`推荐`	字符串	OSI 传输层或进程间通信方法。[9]	`tcp`；`udp`
`rpc.method`	`推荐`	字符串	这是从 RPC 接口角度看的方法的逻辑名称。[10]	`exampleMethod`
`rpc.service`	`推荐`	字符串	正在调用的服务的完整（逻辑）名称，包括其包名称（如果适用）。[11]	`myservice.EchoService`
`rpc.connect_rpc.request.metadata.<key>`	`选择加入`	string[]	Connect 请求元数据，`<key>` 是规范化的 Connect 元数据键（小写），值为元数据值。[12]	`["1.2.3.4", "1.2.3.5"]`
`rpc.connect_rpc.response.metadata.<key>`	`选择加入`	string[]	Connect 响应元数据，`<key>` 是规范化的 Connect 元数据键（小写），值为元数据值。[13]	`["attribute_value"]`

[2] error.type: error.type 应可预测且具有低基数。

当 error.type 设置为某个类型（例如，异常类型）时，应该使用该工件内识别类型的规范类名。

Instrumentations 应该记录它们报告的错误列表。

如果操作已成功完成，Instrumentations 不应设置 error.type。

如果特定域定义了自己的一组错误标识符（例如 HTTP 或 gRPC 状态码），则建议

使用特定于域的属性
设置 error.type 以捕获所有错误，无论它们是否包含在特定于域的集合中。

[3] server.port: 如果端口被用于通信的网络传输所支持。

[4] server.port: 从客户端观察时，并且在通过中介进行通信时，server.port 应代表任何中介（例如代理）之后的服务器端口，如果可用。

[5] client.address: 从服务器端观察时，并且当通过中间设备通信时，client.address 应代表任何中间设备（例如代理）后的客户端地址（如果可用）。

[6] client.port: 从服务器端观察时，并且当通过中间设备通信时，client.port 应代表任何中间设备（例如代理）后的客户端端口（如果可用）。

[7] network.protocol.name: 该值应规范化为小写。

[8] network.protocol.version: 如果协议版本需要协商（例如，使用 ALPN），则此属性应设置为协商后的版本。如果实际协议版本未知，则不应设置此属性。

[9] network.transport: 该值应规范化为小写。

在设置端口号时，应始终考虑设置传输协议，因为没有传输协议的端口号是模糊的。例如，不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。

[10] rpc.method: 这是从 RPC 接口角度看的方法的逻辑名称，它可能与任何实现的方法/函数名称不同。code.function.name 属性可用于存储后者（例如，实际在服务器端执行调用的方法，RPC 客户端存根方法）。

[11] rpc.service: 这是从 RPC 接口角度看的服务的逻辑名称，它可能与任何实现类的名称不同。code.namespace 属性可用于存储后者（尽管属性名称如此，但它可能包含类名；例如，在服务器端实际执行调用的方法所属的类，RPC 客户端存根类）。

[12] rpc.connect_rpc.request.metadata.<key>: 仪器化应显式配置要捕获的元数据值。包含所有请求元数据值可能存在安全风险 - 显式配置有助于避免泄露敏感信息。

例如，一个值为 ["1.2.3.4", "1.2.3.5"] 的属性 my-custom-key 应被记录为属性 rpc.connect_rpc.request.metadata.my-custom-key，值为 ["1.2.3.4", "1.2.3.5"]。

[13] rpc.connect_rpc.response.metadata.<key>: 仪器化应显式配置要捕获的元数据值。包含所有响应元数据值可能存在安全风险 - 显式配置有助于避免泄露敏感信息。

例如，一个值为 "attribute_value" 的属性 my-custom-key 应被记录为属性 rpc.connect_rpc.response.metadata.my-custom-key，值为 ["attribute_value"]。

error.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。

值	描述	Stability
`_OTHER`	当检测不到自定义值时使用的回退错误值。

network.transport 具有以下已知值列表。如果其中一个适用，则必须使用相应的_值_；否则，可以_使用_自定义值。

值	描述	Stability
`pipe`	命名或匿名管道。
`quic`	QUIC
`tcp`	TCP
`udp`	UDP
`unix`	Unix 域套接字

rpc.connect_rpc.error_code 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以自定义值。

值	描述	Stability
`aborted`	aborted
`already_exists`	already_exists
`cancelled`	cancelled
`data_loss`	data_loss
`deadline_exceeded`	deadline_exceeded
`failed_precondition`	failed_precondition
`internal`	internal
`invalid_argument`	invalid_argument
`not_found`	not_found
`out_of_range`	out_of_range
`permission_denied`	permission_denied
`resource_exhausted`	resource_exhausted
`unauthenticated`	unauthenticated
`unavailable`	unavailable
`unimplemented`	unimplemented
`unknown`	unknown

Feedback

这个页面有用吗？

谢谢。您的反馈受到赞赏！

请让我们知道我们如何改进此页面。您的反馈受到赞赏！