使用 OpenTelemetry

您可以使用 OpenTelemetry 通过 Java API 客户端监控 Elasticsearch 请求的性能和行为。Java API 客户端内置了 OpenTelemetry 监控功能，默认情况下会发出 分布式追踪跨度。这样，使用 OpenTelemetry 进行监控 或运行 OpenTelemetry Java Agent 的应用程序会自然地丰富额外的跨度信息，这些信息包含有关 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 Java SDK 或使用 OpenTelemetry Java Agent 时，Java API 客户端的 OpenTelemetry 监控功能默认启用，并使用*全局*注册的 OpenTelemetry SDK 实例（即 GlobalOpenTelemetry）。因此，如果您不使用自定义的本地 OpenTelemetry SDK 实例，则无需显式设置即可使用 Java API 客户端的 OpenTelemetry 监控功能。

如果您使用的是 带有自定义 OpenTelemetry SDK 实例（未全局注册）的手动 OpenTelemetry 监控功能，则可以使用自定义 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);

// Use the client...

// Close the client, also closing the underlying transport object and network connections.
esClient.close();

您可以通过 Java 系统属性或环境变量配置 OpenTelemetry 监控功能。以下配置选项可用。

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

默认： true

默认情况下，内置的 OpenTelemetry 监控功能不会捕获请求正文，原因是出于数据隐私考虑。如果您希望无论如何都要捕获此信息，则可以使用此选项启用从 Elasticsearch 搜索请求的请求正文中捕获搜索查询。

默认： false

OpenTelemetry 监控功能（与任何其他监控方法一样）可能会对 CPU、内存和/或延迟带来少量开销。开销可能仅在启用监控功能（默认）并且目标应用程序中启用了 OpenTelemetry SDK（或 OpenTelemetry Agent）时才会发生。如果禁用监控功能或目标应用程序中没有活动的 OpenTelemetry SDK（或 OpenTelemetry Agent），则使用客户端时不会产生任何监控开销。

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