HTTP
HTTP 属性
本文档定义了 HTTP 命名空间中的语义约定属性。
Attributes
| 键 | Stability | Value Type | 描述 | Example Values |
|---|---|---|---|---|
http.connection.state |  | 字符串 | HTTP 连接池中 HTTP 连接的状态。 | active; idle |
http.request.body.size | | int | 请求 payload body 的大小（以字节为单位）。这是传输的字节数，不包括标头，通常（但不总是）存在于 Content-Length 标头中。对于使用传输编码的请求，这应该是压缩后的大小。 | 3495 |
http.request.header.<key> |  | string[] | HTTP 请求标头，<key> 是规范化的 HTTP 标头名称（小写），值是标头的值。[1] | ["application/json"]; ["1.2.3.4", "1.2.3.5"] |
http.request.method | | 字符串 | HTTP 请求方法。[2] | GET; POST; HEAD |
http.request.method_original | | 字符串 | 客户端在请求行中发送的原始 HTTP 方法。 | GeT; ACL; foo |
http.request.resend_count | | int | 请求重发尝试的序号（出于任何原因，包括重定向）。[3] | 3 |
http.request.size | | int | 请求的总大小（以字节为单位）。这应该是通过网络传输的总字节数，包括请求行（HTTP/1.1）、帧（HTTP/2 和 HTTP/3）、标头以及请求体（如果存在）。 | 1437 |
http.response.body.size | | int | 响应 payload body 的大小（以字节为单位）。这是传输的字节数，不包括标头，通常（但不总是）存在于 Content-Length 标头中。对于使用传输编码的请求，这应该是压缩后的大小。 | 3495 |
http.response.header.<key> | | string[] | HTTP 响应标头，<key> 是规范化的 HTTP 标头名称（小写），值是标头的值。[4] | ["application/json"]; ["abc", "def"] |
http.response.size | | int | 响应的总大小（以字节为单位）。这应该是通过网络传输的总字节数，包括状态行（HTTP/1.1）、帧（HTTP/2 和 HTTP/3）、标头以及响应体和 trailers（如果存在）。 | 1437 |
http.response.status_code | | int | HTTP 响应状态码. | 200 |
http.route | | 字符串 | 请求的匹配路由模板。这必须是低基数的，并包含所有静态路径段，动态路径段用占位符表示。 | /users/:userID?; my-controller/my-action/{id?} |
[1] http.request.header.<key>: 仪器应要求显式配置要捕获哪些标头。包含所有请求标头可能存在安全风险——显式配置有助于避免泄露敏感信息。
User-Agent 标头已在 user_agent.original 属性中捕获。用户可以显式配置仪器来捕获它们，即使不推荐。
属性值必须由数组形式的多个标头值组成，或者是一个包含可能被逗号连接的字符串的单项数组，具体取决于 HTTP 库访问标头的方式。
示例
- 标头
Content-Type: application/json应被记录为http.request.header.content-type属性，值为["application/json"]。 - 标头
X-Forwarded-For: 1.2.3.4, 1.2.3.5应被记录为http.request.header.x-forwarded-for属性，值为["1.2.3.4", "1.2.3.5"]或["1.2.3.4, 1.2.3.5"]，具体取决于 HTTP 库。
[2] http.request.method: 仪器应“了解”HTTP 请求方法的“已知”值。默认情况下，此约定将“已知”方法定义为 RFC9110 中列出的方法，RFC5789 中定义的 PATCH 方法，以及 httpbis-safe-method-w-body 中定义的 QUERY 方法。
如果 HTTP 请求方法仪器不了解，则必须将 http.request.method 属性设置为 _OTHER。
如果 HTTP 仪器最终可能将有效的 HTTP 请求方法转换为 _OTHER，则必须提供一种方法来覆盖已知 HTTP 方法的列表。如果此覆盖是通过环境变量完成的，则环境变量必须命名为 OTEL_INSTRUMENTATION_HTTP_KNOWN_METHODS，并支持一个逗号分隔的、区分大小写的已知 HTTP 方法列表（此列表必须完全覆盖默认已知方法，而不是默认方法之外的已知方法列表）。
HTTP 方法名称区分大小写，http.request.method 属性值必须精确匹配一个已知的 HTTP 方法名称。对于将 HTTP 方法视为不区分大小写的特定 Web 框架的仪器，应填充一个规范等效值。进行此操作的跟踪仪器还必须将 http.request.method_original 设置为原始值。
[3] http.request.resend_count: 每次客户端重发 HTTP 请求时，都应更新重发计数，无论重发的原因为何（例如，重定向、授权失败、503 服务器不可用、网络问题或其他任何原因）。
[4] http.response.header.<key>: 仪器应要求显式配置要捕获哪些标头。包含所有响应标头可能存在安全风险——显式配置有助于避免泄露敏感信息。
用户可以显式配置仪器来捕获它们，即使不推荐。
属性值必须由数组形式的多个标头值组成，或者是一个包含可能被逗号连接的字符串的单项数组，具体取决于 HTTP 库访问标头的方式。
示例
- 标头
Content-Type: application/json应被记录为http.request.response.content-type属性，值为["application/json"]。 - 标头
My-custom-header: abc, def应被记录为http.response.header.my-custom-header属性，值为["abc", "def"]或["abc, def"]，具体取决于 HTTP 库。
[5] http.route: 当 HTTP 服务器框架不支持此属性时，不得填充此属性，因为路由属性必须是低基数的，并且 URI 路径不能替代它。如果存在应用程序根目录，则应包含 应用程序根目录。
静态路径段是路由模板中具有固定、低基数值的ส่วน。这包括字面字符串，如 /users/，以及受限于有限、预定义值集合的占位符，例如 {controller} 或 {action}。
动态路径段是占位符，用于存储具有高基数且不受预定义列表约束的值，就像静态路径段一样。
仪器应使用相应 Web 框架提供的路由信息。它们应选择最精确的路由信息来源，并可以支持自定义路由格式。仪器应记录使用的格式和获取路由字符串的 API。
http.connection.state 具有以下一组知名值。如果适用其中一个，则必须使用相应的名称；否则，可以使用自定义名称。
| 值 | 描述 | Stability |
|---|---|---|
active | active 状态。 | |
idle | idle 状态。 | |
http.request.method 具有以下一组知名值。如果适用其中一个，则必须使用相应的名称；否则，可以使用自定义名称。
| 值 | 描述 | Stability |
|---|---|---|
_OTHER | 仪器不了解的任何 HTTP 方法。 | |
CONNECT | CONNECT 方法。 | |
DELETE | DELETE 方法。 | |
GET | GET 方法。 | |
HEAD | HEAD 方法。 | |
OPTIONS | OPTIONS 方法。 | |
PATCH | PATCH 方法。 | |
POST | POST 方法。 | |
PUT | PUT 方法。 | |
QUERY | QUERY 方法。 | |
TRACE | TRACE 方法。 | |
已弃用的 HTTP 属性
描述了已弃用的 HTTP 属性。
Attributes
| 键 | Stability | Value Type | 描述 | Example Values |
|---|---|---|---|---|
http.client_ip |  已替换为 client.address。 | 字符串 | 已弃用，请改用 client.address。 | 83.164.160.102 |
http.flavor | 已拆分为 network.protocol.name 和 network.protocol.version | 字符串 | 已弃用，请改用 network.protocol.name 和 network.protocol.version。 | 1.0; 1.1; 2.0 |
http.host | 根据用法，已替换为 server.address、client.address 或 http.request.header.host 之一。 | 字符串 | 已弃用，请根据用法改用 server.address、client.address 或 http.request.header.host 之一。 | www.example.org |
http.method | 已替换为 http.request.method。 | 字符串 | 已弃用，请改用 http.request.method。 | GET; POST; HEAD |
http.request_content_length | 已替换为 http.request.header.content-length。 | int | 已弃用，请改用 http.request.header.content-length。 | 3495 |
http.request_content_length_uncompressed | 已替换为 http.request.body.size。 | int | 已弃用，请改用 http.request.body.size。 | 5493 |
http.response_content_length | 已替换为 http.response.header.content-length。 | int | 已弃用，请改用 http.response.header.content-length。 | 3495 |
http.response_content_length_uncompressed | 已替换为 http.response.body.size。 | int | 已弃用，请改用 http.response.body.size。 | 5493 |
http.scheme | 已替换为 url.scheme。 | 字符串 | 已弃用，请改用 url.scheme。 | http; https |
http.server_name | 已替换为 server.address。 | 字符串 | 已弃用，请改用 server.address。 | example.com |
http.status_code | 已替换为 http.response.status_code。 | int | 已弃用，请改用 http.response.status_code。 | 200 |
http.target | 已拆分为 url.path 和 url.query。 | 字符串 | 已弃用，请改用 url.path 和 url.query。 | /search?q=OpenTelemetry#SemConv |
http.url | 已替换为 url.full。 | 字符串 | 已弃用，请改用 url.full。 | https://www.foo.bar/search?q=OpenTelemetry#SemConv |
http.user_agent | 已替换为 user_agent.original。 | 字符串 | 已弃用，请改用 user_agent.original。 | CERN-LineMode/2.15 libwww/2.17b3; Mozilla/5.0 (iPhone; CPU iPhone OS 14_7_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.1.2 Mobile/15E148 Safari/604.1 |
http.flavor 具有以下一组知名值。如果适用其中一个，则必须使用相应的名称；否则，可以使用自定义名称。
| 值 | 描述 | Stability |
|---|---|---|
1.0 | HTTP/1.0 | |
1.1 | HTTP/1.1 | |
2.0 | HTTP/2 | |
3.0 | HTTP/3 | |
QUIC | QUIC 协议。 | |
SPDY | SPDY 协议。 | |