使用 OpenTelemetry

您可以使用 OpenTelemetry 通过 Java API 客户端监控 Elasticsearch 请求的性能和行为。Java API 客户端自带内置的 OpenTelemetry instrumentation，默认情况下会发出 分布式跟踪 span。这样，使用 OpenTelemetry 进行插桩或运行 OpenTelemetry Java Agent 的应用程序，会固有地被包含有关 Elasticsearch 请求执行的富有洞察力的信息的额外 span 所丰富。

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

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

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

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

当手动使用 OpenTelemetry Java SDK或使用OpenTelemetry Java Agent时，Java API 客户端的 OpenTelemetry instrumentation 默认启用，并使用全局注册的 OpenTelemetry SDK 实例（即 GlobalOpenTelemetry）。因此，如果您不使用自定义的本地 OpenTelemetry SDK 实例，则无需显式设置即可使用 Java API 客户端的 OpenTelemetry instrumentation。

如果您正在使用 带有自定义 OpenTelemetry SDK 实例的 手动 OpenTelemetry instrumentation，而该实例未全局注册，则可以使用自定义 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 instrumentation。以下是可用的配置选项。

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

默认值： true

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

默认值： false

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

即使启用 instrumentation 并被（OpenTelemetry SDK）积极使用，在绝大多数情况下，开销也非常小，可以忽略不计。在出现明显开销的极端情况下，可以显式禁用 instrumentation，以消除 instrumentation 的任何潜在开销影响。