使用 OpenTelemetry

您可以使用 OpenTelemetry 通过 Ruby 客户端监控 Elasticsearch 请求的性能和行为。Ruby 客户端自带内置的 OpenTelemetry 检测，默认情况下会发出分布式追踪 span。这样，使用 OpenTelemetry 进行检测或使用 OpenTelemetry Ruby SDK 的应用程序将固有地获得额外的 span，这些 span 包含有关 Elasticsearch 请求执行情况的深入信息。

Ruby 客户端中的原生检测遵循 OpenTelemetry Elasticsearch 语义约定。特别是，客户端中的检测涵盖了 Elasticsearch 请求的逻辑层。每个请求都会创建一个 span，该 span 由服务通过 Ruby 客户端处理。下图显示了一个追踪，该追踪记录了两个不同的 Elasticsearch 请求的处理：一个 ping 请求和一个 search 请求。

通常，OpenTelemetry 自动检测模块附带对 HTTP 级别通信的检测支持。在这种情况下，除了逻辑 Elasticsearch 客户端请求之外，还将捕获客户端发出的物理 HTTP 请求的 span。下图显示了一个同时包含 Elasticsearch span（蓝色）和相应的 HTTP 级别 span（红色）的追踪

通过逻辑 Elasticsearch span 和物理 HTTP span 的组合，可以揭示高级 Ruby 客户端行为，例如节点轮询和请求重试。以下示例显示了在具有两个节点场景中的 search 请求

第一个节点不可用，并导致 HTTP 错误，而重试到第二个节点成功。两个 HTTP 请求都包含在逻辑 Elasticsearch 请求 span（蓝色）中。

当手动使用 OpenTelemetry Ruby SDK 或使用 OpenTelemetry Ruby 自动检测时，默认情况下会启用 Ruby 客户端的 OpenTelemetry 检测，并使用带有全局跟踪器提供程序的全局 OpenTelemetry SDK。您可以在实例化客户端时通过 Ruby 客户端配置选项 opentelemetry_tracer_provider 提供跟踪器提供程序。这有时对于测试或其他特定用例很有用。

client = Elasticsearch::Client.new(
  cloud_id: '<CloudID>',
  api_key: '<ApiKey>',
  opentelemetry_tracer_provider: tracer_provider
)

您可以通过环境变量配置 OpenTelemetry 检测。以下配置选项可用。

通过此配置选项，您可以启用（默认）或禁用内置的 OpenTelemetry 检测。

默认值: true

默认情况下，由于数据隐私方面的考虑，内置的 OpenTelemetry 检测不会捕获请求正文。如果您希望收集此信息，则可以使用此选项来启用捕获 Elasticsearch 搜索请求的请求正文中的搜索查询。选项是捕获原始搜索查询、使用默认的敏感键列表清理查询，或者完全不捕获。

默认值: omit

有效选项: omit, sanitize, raw

您可以配置在捕获搜索查询时对其值进行编辑的键列表。值必须以逗号分隔。请注意，在 v8.3.0 和 v8.3.1 中，环境变量 OTEL_INSTRUMENTATION_ELASTICSEARCH_CAPTURE_SEARCH_QUERY 可用，但现在已弃用，而支持包含 RUBY 的环境变量。

默认值: nil

示例

OTEL_RUBY_INSTRUMENTATION_ELASTICSEARCH_SEARCH_QUERY_SANITIZE_KEYS='sensitive-key,other-sensitive-key'

OpenTelemetry 检测（与任何其他监控方法一样）可能会对 CPU、内存和/或延迟产生轻微的开销。仅当启用检测（默认）并且 OpenTelemetry SDK 在目标应用程序中处于活动状态时，才会发生开销。当检测被禁用或目标应用程序中没有活动的 OpenTelemetry SDK 时，在使用客户端时不会出现监控开销。

即使在启用检测并由 OpenTelemetry SDK 积极使用的情况下，开销也很小，并且在绝大多数情况下可以忽略不计。在出现明显开销的极端情况下，可以显式禁用检测，以消除对性能的任何潜在影响。