使用 OpenTelemetry

您可以使用 OpenTelemetry 通过 Java API 客户端监控 Elasticsearch 请求的性能和行为。Java API 客户端自带内置的 OpenTelemetry 检测，默认情况下会发出 分布式跟踪跨度。这样，使用 OpenTelemetry 检测的应用程序 或运行 OpenTelemetry Java 代理 本质上会丰富额外的跨度，其中包含有关 Elasticsearch 请求执行的深入信息。

Java API 客户端中的原生检测遵循 OpenTelemetry Elasticsearch 语义约定。特别是，客户端中的检测涵盖逻辑 Elasticsearch 请求层，因此，为服务针对 Java API 客户端执行的每个请求创建一个跨度。下图显示了一个结果跟踪，其中执行了三个不同的 Elasticsearch 请求，即 index、get 和搜索 request

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

高级 Java API 客户端行为（例如节点轮询和请求重试）通过逻辑 Elasticsearch 跨度和物理 HTTP 跨度的组合来揭示。以下示例显示了在有两个 Elasticsearch 节点的场景中 index 请求

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

设置 OpenTelemetry 检测编辑

当使用 手动 OpenTelemetry Java SDK 或使用 OpenTelemetry Java 代理 时，Java API 客户端的 OpenTelemetry 检测默认情况下处于启用状态，并使用全局注册的 OpenTelemetry SDK 实例（即 GlobalOpenTelemetry）。因此，如果您不使用自定义的本地 OpenTelemetry SDK 实例，则无需进行显式设置即可使用 Java API 客户端的 OpenTelemetry 检测。

使用自定义 OpenTelemetry 实例编辑

如果您使用的是 手动 OpenTelemetry 检测，并且使用的是未全局注册的自定义 OpenTelemetry SDK 实例，则可以使用自定义 OpenTelemetry 实例创建 Java API 客户端。以下代码片段显示了使用自定义 OpenTelemetry 实例的示例。

// URL and API key
String serverUrl = "https://127.0.0.1:9200";
String apiKey = "VnVhQ2ZHY0JDZGJrU...";

// Create the low-level client
RestClient restClient = RestClient
    .builder(HttpHost.create(serverUrl))
    .setDefaultHeaders(new Header[]{
            new BasicHeader("Authorization", "ApiKey " + apiKey)
    })
    .build();
// Create and configure custom OpenTelemetry instance
OpenTelemetry customOtel = OpenTelemetrySdk.builder().build();

// Create Instrumentation instance using the custom OpenTelemetry instance
// Second constructor argument allows to enable/disable search body capturing
OpenTelemetryForElasticsearch esOtelInstrumentation =
    new OpenTelemetryForElasticsearch(customOtel, false);

// Create the transport with the custom Instrumentation instance
ElasticsearchTransport transport = new RestClientTransport(
    restClient, new JacksonJsonpMapper(), null, esOtelInstrumentation
);

// And create the API client
ElasticsearchClient esClient = new ElasticsearchClient(transport);

配置 OpenTelemetry 检测编辑

您可以通过 Java 系统属性或环境变量配置 OpenTelemetry 检测。以下配置选项可用。

启用/禁用 OpenTelemetry 检测编辑

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

默认值： true

捕获搜索请求主体编辑

默认情况下，内置的 OpenTelemetry 检测不会捕获请求主体，因为存在数据隐私问题。如果您希望捕获此信息，无论如何，都可以使用此选项启用从 Elasticsearch 搜索请求的请求主体中捕获搜索查询。

默认值： false

开销编辑

OpenTelemetry 检测（与任何其他监控方法一样）可能会在 CPU、内存和/或延迟方面带来一些开销。开销可能仅在检测启用（默认）且目标应用程序中存在 OpenTelemetry SDK（或 OpenTelemetry 代理）时才会发生。如果检测被禁用或目标应用程序中没有活动的 OpenTelemetry SDK（或 OpenTelemetry 代理），则使用客户端时预计不会出现任何监控开销。

即使检测已启用并正在积极使用（由 OpenTelemetry SDK 使用），在绝大多数情况下，开销非常小，可以忽略不计。在极少数情况下，如果出现明显的开销，则可以 显式禁用检测，以消除检测带来的任何潜在开销影响。