通用属性
状态: 开发中
本节所述属性不特定于某个操作，而是通用的。它们可以用于任何适用的 Span。特定操作可能会引用或需要其中一些属性。
服务器、客户端和共享网络属性
这些属性可用于描述基于连接的网络交互中的客户端和服务器，其中有一方会发起连接（客户端是发起连接的一方）。这涵盖了所有 TCP 网络交互，因为 TCP 是面向连接的，并且有一方会发起连接（对于使用 TCP 的点对点通信会有一个例外，在这种情况下，协议/API 的“面向用户”的表面没有明确区分客户端和服务器的概念）。这也涵盖了其中一方会发起交互的 UDP 网络交互，例如 QUIC (HTTP/3) 和 DNS。
在理想情况下，不考虑代理、多个 IP 地址或主机名，server.* 属性在客户端和服务器上是相同的。
地址和端口属性
对于所有基于 IP 的协议，“地址”应仅为 IP 级地址。地址的协议特定部分会拆分到其他属性中（如果适用），例如 TCP 和 UDP 的“端口”属性。如果收集了此类传输特定信息，并且属性名称尚未唯一标识传输，则特别鼓励设置 network.transport。
服务器属性
警告 本节中的属性正在被 HTTP 语义约定使用。一旦 HTTP 语义约定被声明为稳定，对此类属性的更改将仅在不导致 HTTP 语义约定发生破坏性更改的情况下才被允许。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
server.address |  | 推荐 | 字符串 | 服务器域名（如果无需反向 DNS 查找即可获得）；否则，是 IP 地址或 Unix 域套接字名称。[1] | example.com；10.1.2.80；/tmp/my.sock |
server.port | | 推荐 | int | 服务器端口号。[2] | 80; 8080; 443 |
[1] server.address： 从客户端观察时，并且当通过中间设备通信时，server.address 应代表任何中间设备（例如代理）后面的服务器地址，如果可用。
[2] server.port： 从客户端观察，并且在通过中介通信时，server.port 应表示任何中介（例如代理）后面的服务器端口，如果可用的话。
server.address 和 server.port 代表逻辑服务器名称和端口。引用这些属性的语义约定应在其上下文中指定这些属性的含义。
server.address
对于基于 IP 的通信，该名称应为服务的 DNS 主机名。在客户端，它匹配远程服务名称；在服务器端，它代表客户端看到的本地服务名称。
当连接到 URL https://example.com/foo 时，server.address 在客户端和服务器端都匹配 "example.com"。
在客户端，它通常以 URL、连接字符串、主机名等形式传递。有时，主机名仅作为字符串提供给仪器化，该字符串可能包含 DNS 名称或 IP 地址。server.address 应设置为可用的已知主机名（例如，如果连接到 URL https://127.0.0.1/foo，则设置为 "127.0.0.1"）。
如果只有 IP 地址可用，则应将其填充到 server.address。不应使用反向 DNS 查找来获取 DNS 名称。
如果 network.transport 是 "pipe"，则表示它的文件的绝对路径应作为 server.address 使用。如果没有这样的文件（例如匿名管道），则名称应明确设置为空字符串，以区别于名称未知或未被仪器化覆盖的情况。
对于 Unix 域套接字，server.address 属性在客户端表示远程端点地址，在服务器端表示本地端点地址。
客户端属性
警告 本节中的属性正在被 HTTP 语义约定使用。一旦 HTTP 语义约定被声明为稳定，对此类属性的更改将仅在不导致 HTTP 语义约定发生破坏性更改的情况下才被允许。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
client.address | | 推荐 | 字符串 | 客户端地址 - 如果可用且无需反向 DNS 查找，则为域名；否则，为 IP 地址或 Unix 域套接字名称。[1] | client.example.com; 10.1.2.80; /tmp/my.sock |
client.port | | 推荐 | int | 客户端端口号。[2] | 65123 |
[1] client.address: 从服务器端观察时，通过中介进行通信时，client.address 应表示任何中介（例如代理）后面的客户端地址，如果可用的话。
[2] client.port: 从服务器端观察时，通过中介进行通信时，client.port 应表示任何中介（例如代理）后面的客户端端口，如果可用的话。
源和目标属性
这些属性可用于描述网络交换/数据包的发送者和接收者。当双方之间没有客户端/服务器关系，或者这种关系未知时，应使用这些属性。这涵盖了低级网络交互（例如，数据包跟踪），您不知道是否存在连接或哪一方发起的。这也涵盖了单向 UDP 流和点对点通信，其中协议/API 的“面向用户”的表面没有明确区分客户端和服务器的概念。
源
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
source.address |  | 推荐 | 字符串 | 源地址 - 如果可用且无需反向 DNS 查找，则为域名；否则，为 IP 地址或 Unix 域套接字名称。[1] | source.example.com; 10.1.2.80; /tmp/my.sock |
source.port | | 推荐 | int | 源端口号 | 3389; 2888 |
[1] source.address: 从目标端观察时，通过中介进行通信时，source.address 应表示任何中介（例如代理）后面的源地址，如果可用的话。
目标
目标字段捕获网络交换/数据包接收者的详细信息。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
destination.address | | 推荐 | 字符串 | 目标地址 - 如果可用且无需反向 DNS 查找，则为域名；否则，为 IP 地址或 Unix 域套接字名称。[1] | destination.example.com; 10.1.2.80; /tmp/my.sock |
destination.port | | 推荐 | int | 目标端口号 | 3389; 2888 |
[1] destination.address: 从源端观察时，通过中介进行通信时，destination.address 应表示任何中介（例如代理）后面的目标地址，如果可用的话。
其他网络属性
警告 本节中的属性正在被 HTTP 语义约定使用。一旦 HTTP 语义约定被声明为稳定，对此类属性的更改将仅在不导致 HTTP 语义约定发生破坏性更改的情况下才被允许。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
network.local.address | | 推荐 | 字符串 | 本地网络连接地址 - IP 地址或 Unix 域套接字名称。 | 10.1.2.80；/tmp/my.sock |
network.local.port | | 推荐 | int | 本地网络连接端口号。 | 65123 |
network.peer.address | | 推荐 | 字符串 | 网络连接的对端地址 - IP 地址或 Unix 域套接字名称。 | 10.1.2.80；/tmp/my.sock |
network.peer.port | | 推荐 | int | 网络连接的对等端口号。 | 65123 |
network.protocol.name | | 推荐 | 字符串 | OSI 应用层或非 OSI 等效项。[1] | amqp; http; mqtt |
network.protocol.version | | 推荐 | 字符串 | 网络通信的实际协议版本。[2] | 1.1; 2 |
network.transport | | 推荐 | 字符串 | OSI 传输层或进程间通信方法。[3] | tcp；udp |
network.type | | 推荐 | 字符串 | OSI 网络层或非 OSI 等效项。[4] | ipv4; ipv6 |
[1] network.protocol.name: 该值应转换为小写。
[2] network.protocol.version: 如果协议版本需要协商（例如，使用ALPN），则此属性应设置为协商后的版本。如果实际协议版本未知，则不应设置此属性。
[3] network.transport: 该值应转换为小写。
在设置端口号时，应始终考虑设置传输协议，因为没有传输协议的端口号是模糊的。例如，不同的进程可能正在监听 TCP 端口 12345 和 UDP 端口 12345。
[4] network.type: 该值应转换为小写。
network.transport 具有以下已知值列表。如果其中一个适用，则必须使用相应的_值_；否则，可以_使用_自定义值。
| 值 | 描述 | Stability |
|---|---|---|
pipe | 命名或匿名管道。 | |
quic | QUIC | |
tcp | TCP | |
udp | UDP | |
unix | Unix 域套接字 | |
network.type 具有以下预定义值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
ipv4 | IPv4 | |
ipv6 | IPv6 | |
network.peer.* 和 network.local.* 属性
这些属性标识直接相互连接的网络对等点。
network.peer.address 和 network.local.address 应为 IP 地址、Unix 域套接字名称或其他特定于网络类型的地址。
注意：获取套接字级别属性的特定结构和方法仅作为示例提及。仪器化通常会使用其环境或套接字实现提供的套接字 API。
当使用 connect(2)（Linux 或其他 POSIX 系统 / Windows）或 bind(2)（Linux 或其他 POSIX 系统 / Windows）并使用 AF_INET 地址族进行连接时，network.peer.address 和 network.peer.port 代表 sockaddr_in 结构中的 sin_addr 和 sin_port 字段。
可以通过调用 getpeername 方法（Linux 或其他 POSIX 系统 / Windows）获取 network.peer.address 和 network.peer.port。
可以通过调用 getsockname 方法（Linux 或其他 POSIX 系统 / Windows）获取 network.local.address 和 network.local.port。
使用 network.peer.* 的客户端/服务器示例
请注意，这些示例中未包含 network.local.* 属性，因为它们通常是选择加入的。
简单的客户端/服务器示例
带反向代理的客户端/服务器示例
带正向代理的客户端/服务器示例
网络连接和运营商属性
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
network.carrier.icc | | 推荐 | 字符串 | 与移动运营商网络关联的 ISO 3166-1 alpha-2 2 位国家/地区代码。 | DE |
network.carrier.mcc | | 推荐 | 字符串 | 移动运营商国家代码。 | 310 |
network.carrier.mnc | | 推荐 | 字符串 | 移动运营商网络代码。 | 001 |
network.carrier.name | | 推荐 | 字符串 | 移动运营商的名称。 | sprint |
network.connection.subtype | | 推荐 | 字符串 | 这描述了 connection.type 的更多详细信息。它可以是连接的蜂窝技术类型，也可以用于描述 Wi-Fi 连接的详细信息。 | LTE |
network.connection.type | | 推荐 | 字符串 | 互联网连接类型。 | wifi |
network.connection.subtype 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
cdma | CDMA | |
cdma2000_1xrtt | CDMA2000 1XRTT | |
edge | EDGE | |
ehrpd | EHRPD | |
evdo_0 | EVDO Rel. 0 | |
evdo_a | EVDO Rev. A | |
evdo_b | EVDO Rev. B | |
gprs | GPRS | |
gsm | GSM | |
hsdpa | HSDPA | |
hspa | HSPA | |
hspap | HSPAP | |
hsupa | HSUPA | |
iden | IDEN | |
iwlan | IWLAN | |
lte | LTE | |
lte_ca | LTE CA | |
nr | 5G NR (New Radio) | |
nrnsa | 5G NRNSA (New Radio Non-Standalone) | |
td_scdma | TD-SCDMA | |
umts | UMTS | |
network.connection.type 具有以下已知值列表。如果其中一个适用，则必须使用相应的值；否则，可以使用自定义值。
| 值 | 描述 | Stability |
|---|---|---|
cell | cell | |
unavailable | unavailable | |
unknown | unknown | |
wifi | wifi | |
wired | wired | |
对于 Unix 和 pipe，由于连接通过文件系统进行，而不是直接连接到已知的对等方，因此 server.address 是通常有意义的唯一属性（请参阅下文 server.address 的描述）。
通用远程服务属性
此属性可用于访问任何远程服务的任何操作。用户可以根据其分布式系统中的特定语义来定义服务名称。仪器化应提供一种让用户配置此名称的方法。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
peer.service | | 推荐 | 字符串 | 远程服务的service.name。如果可用，应等于远程服务的实际 service.name 资源属性。[1] | AuthTokenCache |
[1] peer.service: 用户可能指定的 peer.service 示例
- 一个 Redis 身份验证令牌缓存，其
peer.service为"AuthTokenCache"。 - 一个 gRPC 服务
rpc.service="io.opentelemetry.AuthService"可能托管在网关peer.service="ExternalApiService"和后端peer.service="AuthService"中。
通用线程属性
这些属性可用于任何操作，以存储有关启动 Span 的线程的信息。
Attributes
| 键 | Stability | 需求级别 | Value Type | 描述 | Example Values |
|---|---|---|---|---|---|
thread.id | | 推荐 | int | 当前“托管”线程 ID（与 OS 线程 ID 相反）。[1] | 42 |
thread.name | | 推荐 | 字符串 | 当前线程名称。[2] | main |
[1] thread.id: 可以从中提取值的示例
| 语言或平台 | Source |
|---|---|
| JVM | Thread.currentThread().threadId() |
| .NET | Thread.CurrentThread.ManagedThreadId |
| Python | threading.current_thread().ident |
| Ruby | Thread.current.object_id |
| C++ | std::this_thread::get_id() |
| Erlang | erlang:self() |
[2] thread.name: 可以从中提取值的示例
| 语言或平台 | Source |
|---|---|
| JVM | Thread.currentThread().getName() |
| .NET | Thread.CurrentThread.Name |
| Python | threading.current_thread().name |
| Ruby | Thread.current.name |
| Erlang | erlang:process_info(self(), registered_name) |
源代码属性
状态：候选发布
通常，Span 与负责处理 Span 所描述操作的代码单元（通常是启动 Span 的方法）紧密相关。例如，对于 HTTP 服务器 Span，这将是处理传入请求的函数。代码属性允许报告此代码单元，从而提供更多上下文。