使用 OpenTelemetry

您可以使用 OpenTelemetry 来监控您的 Elasticsearch 请求在使用 Ruby 客户端时的性能和行为。Ruby 客户端内置了 OpenTelemetry 检测功能，默认情况下会发出 分布式追踪跨度 (span)。因此，使用 OpenTelemetry 检测或使用 OpenTelemetry Ruby SDK 的应用程序天然地获得了额外的跨度，这些跨度包含了关于 Elasticsearch 请求执行情况的深刻信息。

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

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

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

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

当手动使用 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 使用）的情况下，开销也是最小的，在绝大多数情况下可以忽略不计。在存在明显开销的极端情况下，可以显式禁用检测以消除对性能的任何潜在影响。