gRPC 的语义约定

状态: 开发中

gRPC 的语义约定会扩展并覆盖 RPC spans 和 RPC metrics 的语义约定，这些约定描述了通用 RPC 操作属性，并在此页面上进行了其他描述。

客户端 Span

状态:

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

rpc.system 必须设置为 "grpc"，并且应该在 **创建 span 时** 提供。

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

Span 类型必须为 CLIENT。

Span 状态应根据 grpc 状态码设置。映射定义在 grpc 状态部分。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
rpc.grpc.status_code		必需	int	gRPC 请求的数字状态码。	0; 1; 2
rpc.method		必需	字符串	这是从 RPC 接口角度来看的该方法的逻辑名称。[1]	exampleMethod
rpc.service		必需	字符串	被调用的服务的完整（逻辑）名称，如果适用，包括其包名。[2]	myservice.EchoService
server.address		必需	字符串	RPC 服务器的 [host name](https://grpc.github.io/grpc/core/md_doc_naming.html)。[3]	example.com；10.1.2.80；/tmp/my.sock
error.type		有条件必需 仅在操作失败时。	字符串	描述操作结束时的一类错误。[4]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
server.port		有条件地必需 [5]	int	服务器端口号。[6]	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 等效层。[7]	http
network.protocol.version		推荐	字符串	网络通信实际使用的协议版本。[8]	1.1; 2
network.transport		推荐	字符串	OSI 传输层或进程间通信方法。[9]	tcp；udp
rpc.grpc.request.metadata.<key>		选择加入	string[]	gRPC 请求元数据，<key> 是规范化的 gRPC 元数据键（小写），值是元数据值。[10]	["1.2.3.4", "1.2.3.5"]
rpc.grpc.response.metadata.<key>		选择加入	string[]	gRPC 响应元数据，<key> 是规范化的 gRPC 元数据键（小写），值是元数据值。[11]	["attribute_value"]

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

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

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

[4] error.type：error.type 应是可预测的，并且应具有低基数。

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

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

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

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

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

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

[5] server.port：如果所使用的网络传输支持该端口。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

值	描述	Stability
0	OK
1	CANCELLED
2	UNKNOWN
3	INVALID_ARGUMENT
4	DEADLINE_EXCEEDED
5	NOT_FOUND
6	ALREADY_EXISTS
7	PERMISSION_DENIED
8	RESOURCE_EXHAUSTED
9	FAILED_PRECONDITION
10	ABORTED
11	OUT_OF_RANGE
12	UNIMPLEMENTED
13	INTERNAL
14	UNAVAILABLE
15	DATA_LOSS
16	UNAUTHENTICATED

服务器 Span

状态:

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

rpc.system 必须设置为 "grpc"，并且应该在 **创建 span 时** 提供。

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

Span 类型必须为 SERVER。

Span 状态应根据 grpc 状态码设置。映射定义在 grpc 状态部分。

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
rpc.grpc.status_code		必需	int	gRPC 请求的数字状态码。	0; 1; 2
server.address		必需	字符串	RPC 服务器 主机名。[1]	example.com；10.1.2.80；/tmp/my.sock
error.type		有条件必需 仅在操作失败时。	字符串	描述操作结束时发生的错误类型。[2]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
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.grpc.request.metadata.<key>		选择加入	string[]	gRPC 请求元数据，<key> 是规范化的 gRPC 元数据键（小写），值是元数据值。[12]	["1.2.3.4", "1.2.3.5"]
rpc.grpc.response.metadata.<key>		选择加入	string[]	gRPC 响应元数据，<key> 是规范化的 gRPC 元数据键（小写），值是元数据值。[13]	["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] 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.grpc.request.metadata.<key>：仪器化应要求显式配置要捕获的元数据值。包含所有请求元数据值可能存在安全风险——显式配置有助于避免泄露敏感信息。

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

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

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

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

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

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

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

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

值	描述	Stability
0	OK
1	CANCELLED
2	UNKNOWN
3	INVALID_ARGUMENT
4	DEADLINE_EXCEEDED
5	NOT_FOUND
6	ALREADY_EXISTS
7	PERMISSION_DENIED
8	RESOURCE_EXHAUSTED
9	FAILED_PRECONDITION
10	ABORTED
11	OUT_OF_RANGE
12	UNIMPLEMENTED
13	INTERNAL
14	UNAVAILABLE
15	DATA_LOSS
16	UNAUTHENTICATED

gRPC 状态

下表描述了根据 [gRPC 状态码](https://github.com/grpc/grpc/blob/v1.33.2/doc/statuscodes.md) 和 [Span Kind](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/trace/api.md#spankind) 何时必须将 [Span Status](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.50.0/specification/trace/api.md#set-status) 设置为 Error 或保持未设置。