Elasticsearch 客户端操作的语义约定

状态: 开发中

Elasticsearch 的语义约定扩展并重写了 数据库语义约定。

Span

状态:

表示 Elasticsearch 调用的 Span 遵循通用的 数据库客户端 Span 的语义约定。

db.system.name 必须设置为 "elasticsearch"，并且应在 **Span 创建时** 提供。

Span 名称应遵循通用的 数据库 Span 名称约定，其中端点标识符存储在 db.operation.name 中，索引存储在 db.collection.name 中。

**Span 类型**应为 CLIENT。

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

Attributes

键	Stability	需求级别	Value Type	描述	Example Values
db.operation.name		必需	字符串	正在执行的操作或命令的名称。[1]	search; ml.close_job; cat.aliases
http.request.method		必需	字符串	HTTP 请求方法。[2]	GET; POST; HEAD
url.full		必需	字符串	根据 RFC3986 [3] 描述网络资源的绝对 URL	https://:9200/index/_search?q=user.id:kimchy
db.operation.parameter.<key>		当 URL 包含路径参数时，有条件地必需	字符串	URL 路径中的动态值。[4]	db.operation.parameter.index="test-index"; db.operation.parameter="123"
db.response.status_code		如果收到了响应，则 有条件地必需。	字符串	Elasticsearch 集群返回的 HTTP 响应码。[5]	200; 201; 429
error.type		有条件必需 仅在操作失败时。	字符串	描述操作结束时的错误类别。[6]	timeout；java.net.UnknownHostException；server_certificate_invalid；500
server.port		有条件地必需 [7]	int	服务器端口号。[8]	80; 8080; 443
db.collection.name		推荐	字符串	查询执行的目标索引或数据流。[9]	my_index; index1, index2
db.namespace		推荐	字符串	客户端连接的 Elasticsearch 集群的名称。[10]	customers; test.users
db.operation.batch.size		推荐	int	批处理操作中包含的查询数量。[11]	2; 3; 4
db.query.text		推荐 [12]	字符串	指向 搜索类型查询 的请求正文，以 JSON 字符串格式。[13]	"{\"query\":{\"term\":{\"user.id\":\"kimchy\"}}}"
elasticsearch.node.name		推荐	字符串	表示请求路由到的节点/实例的可读标识符。[14]	instance-0000000001
server.address		推荐	字符串	数据库主机名。[15]	example.com；10.1.2.80；/tmp/my.sock

[1] db.operation.name: db.operation.name 应与请求中提供的端点标识符匹配（请参阅 Elasticsearch schema）。对于批处理操作，如果已知单个操作具有相同的操作名称，则应使用该操作名称，并在前面加上 bulk ；否则，db.operation.name 应为 bulk。

[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] url.full: 对于网络调用，URL 通常具有 scheme://host[:port][path][?query][#fragment] 格式，其中 fragment 不通过 HTTP 传输，但如果已知，仍应包含在内。

url.full 不能包含通过 URL 形式传递的凭证，例如 https://username:password@www.example.com/。在这种情况下，用户名和密码应被redacted，属性值应为 https://REDACTED:REDACTED@www.example.com/。

url.full 应该捕获可用（或可以重建）的绝对 URL。

url.full 中提供的敏感内容应在仪表化工具能够识别时进行清除。

查询字符串中以下键的值应默认redacted，并替换为 REDACTED 值。

• AWSAccessKeyId
• Signature
• sig
• X-Goog-Signature

此列表可能会随时间而更改。

当查询字符串值被redacted时，查询字符串键仍应保留，例如 https://www.example.com/path?color=blue&sig=REDACTED。

[4] db.operation.parameter.<key>: 许多 Elasticsearch URL 路径允许动态值。这些值应以 db.operation.parameter.<key> 的格式记录在 Span 属性中，其中 <key> 是路径参数的名称。实现应参考 elasticsearch schema 以将路径参数值映射到其名称。

[5] db.response.status_code: 4xx 和 5xx 范围内的 HTTP 响应码应被视为错误。

[6] error.type: error.type 应与数据库返回的 db.response.status_code 或异常的规范名称匹配。当使用规范异常类型名称时，仪器化应尽最大努力报告最相关的类型。例如，如果原始异常被包装在一个通用异常中，则应优先选择原始异常。仪器化应记录 error.type 的填充方式。

[7] server.port: 如果使用非默认端口与此 DBMS 通信，并且设置了 server.address。

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

[9] db.collection.name: 查询可能针对多个索引或数据流，在这种情况下，它应为这些名称的逗号分隔列表。如果查询不针对特定索引，则此字段不得设置。

[10] db.namespace: 与 Elastic Cloud 部署通信时，应从“X-Found-Handling-Cluster” HTTP 响应头收集。

[11] db.operation.batch.size: 操作仅在包含两个或更多操作时才被视为批处理，因此 db.operation.batch.size 绝不应为 1。

[12] db.query.text: 默认情况下应为搜索类型查询收集，并且仅当存在排除敏感信息的清理时才收集。

[13] db.query.text: 有关清理，请参阅 db.query.text 的清理。对于批处理操作，如果已知单个操作具有相同的查询文本，则应使用该查询文本；否则，所有单个查询文本应与分隔符 ; 或其他更适用的数据库系统特定分隔符连接。参数化查询文本不应被清理。尽管参数化查询文本可能包含敏感数据，但通过使用参数化查询，用户提供了明确的信号，表明任何敏感数据都将作为参数值传递，并且默认捕获查询文本静态部分的可观察性收益大于风险。param-style queries should not be sanitized. Even though param-style query text can potentially have sensitive data, by using a param-style query the user is giving a strong signal that any sensitive data will be passed as parameter values, and the benefit to observability of capturing the static part of the query text by default outweighs the risk.

[14] elasticsearch.node.name: 与 Elastic Cloud 部署通信时，应从“X-Found-Handling-Instance” HTTP 响应头收集。

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

以下属性对于做出采样决策可能很重要，并且应在跨度创建时提供（如果提供的话）

• db.collection.name
• db.namespace
• db.operation.name
• db.query.text
• http.request.method
• server.address
• server.port
• url.full

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

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

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 方法。

示例

指标

Elasticsearch 客户端仪器应根据通用的 数据库客户端指标的语义约定 收集指标。

db.system.name 必须设置为 "elasticsearch"。