Capture the Elasticsearch cluster name on OpenTelemetry spans from response headers

[vagrawal-newrelic]

Summary

Records the Elasticsearch cluster name on the client's OpenTelemetry spans as db.elasticsearch.cluster.name, read from the response headers. This gives spans an address-independent cluster identity, so telemetry can be correlated to the right cluster even behind a load balancer, proxy or node list — where server.address doesn't identify the cluster.

Resolves #1304.

What it does

In OpenTelemetryForElasticsearch, once the HTTP response is received, the cluster name is read from the response headers and stamped on the span, in this order of precedence:

1. X-Found-Handling-Cluster — set by the Elastic Cloud proxy (canonical, globally-unique cluster id).
2. Elastic-Cluster-Name — emitted by self-managed Elasticsearch when http.headers.cluster_name.enabled: true is set (added in Add cluster name header for onprem elasticsearch#157191, available in 9.6+).

If neither header is present, the attribute is simply not set. The capture is automatic (no configuration), makes no extra request, and never affects the actual request.

Why headers

Data-plane responses (_search, _bulk, …) never return cluster_name, and server.address reflects whichever node / load balancer / proxy the transport happened to hit — not the cluster's own identity. Reading the value the cluster itself stamps on the response is address-independent and works across all deployment topologies. This mirrors how the .NET client populates db.elasticsearch.cluster.name.

Testing

Extended OpenTelemetryForElasticsearchTest with full scenario coverage:

• X-Found-Handling-Cluster only → captured
• Elastic-Cluster-Name only → captured
• both present → X-Found-Handling-Cluster wins (precedence)
• neither present → attribute not set
• empty X-Found-Handling-Cluster → falls back to Elastic-Cluster-Name
• both headers empty → attribute not set

./gradlew check passes (checkstyle + tests).

Note

This replaces the earlier draft on this branch, which used an opt-in GET / active-discovery approach. Now that the server-side Elastic-Cluster-Name header has merged (elastic/elasticsearch#157191), the self-managed case is covered passively by a header too — so the active-discovery machinery is no longer needed, and the change is just the header read.

[cla-checker-service]

💚 CLA has been signed

[l-trotta]

nit: we should document the difference between the on-prem and cloud value

[vagrawal-newrelic]

@l-trotta Thanks for the feedback! updated the docs to spell out the value in each case: the canonical globally-unique cluster id on Elastic Cloud (X-Found-Handling-Cluster) vs the configured cluster.name on self-managed (Elastic-Cluster-Name). Thanks!

[l-trotta]

thank you so much! LGTM