使用 OpenTelemetry

您可以使用 OpenTelemetry 通过 Ruby 客户端监控 Elasticsearch 请求的性能和行为。Ruby 客户端附带内置的 OpenTelemetry 监控，默认情况下会发出 分布式跟踪跨度。这样，使用 OpenTelemetry 进行监控 或使用 OpenTelemetry Ruby SDK 的应用程序会自然地丰富包含有关 Elasticsearch 请求执行的深入信息的额外跨度。

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

通常，OpenTelemetry 自动监控模块附带对 HTTP 级通信的监控支持。在这种情况下，除了逻辑 Elasticsearch 客户端请求之外，还会捕获客户端发出的物理 HTTP 请求的跨度。下图显示了一个跟踪，其中包含 Elasticsearch 跨度（蓝色）和相应的 HTTP 级跨度（红色）。

高级 Ruby 客户端行为（例如节点循环和请求重试）通过逻辑 Elasticsearch 跨度和物理 HTTP 跨度的组合来揭示。以下示例显示了在有两个节点的情况下进行的 search 请求。

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

设置 OpenTelemetry 监控编辑

当 手动使用 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 监控。以下配置选项可用。

启用/禁用 OpenTelemetry 监控编辑

使用此配置选项，您可以启用（默认）或禁用内置的 OpenTelemetry 监控。

默认值： true

捕获搜索请求正文编辑

默认情况下，内置的 OpenTelemetry 监控不会捕获请求正文，因为要考虑数据隐私问题。如果您希望收集此信息，无论如何，您可以使用此选项来启用从 Elasticsearch 搜索请求的请求正文中捕获搜索查询。选项是捕获原始搜索查询、使用默认敏感键列表对查询进行清理，或者根本不捕获。

默认值： omit

有效选项： omit, sanitize, raw

清理 Elasticsearch 搜索请求正文编辑

您可以配置在捕获搜索查询时对其值进行屏蔽的键列表。值必须以逗号分隔。请注意，在 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）的情况下，在绝大多数情况下，开销也是微不足道的。在某些边缘情况下，如果存在明显的开销，则可以 明确禁用监控，以消除对性能的任何潜在影响。