OpenTelemetry Elasticsearch Instrumentation

Warnings

• breaking As a `0.x.x` version package within `opentelemetry-python-contrib`, `opentelemetry-instrumentation-elasticsearch` is considered 'beta' and its API is subject to breaking changes between minor versions (e.g., from 0.61b0 to 0.62b0). Always review release notes when upgrading.
  Fix: Consult the `opentelemetry-python-contrib` changelog for specific breaking changes related to Elasticsearch instrumentation when upgrading.
• gotcha The `instrument()` method must be called *before* the `elasticsearch.Elasticsearch` client is initialized or used. If the client is created first, its methods will not be patched for tracing.
  Fix: Ensure `ElasticsearchInstrumentor().instrument()` is called early in your application's startup, prior to any Elasticsearch client instantiation or calls.
• gotcha This instrumentation only wraps the `elasticsearch` client library. You must explicitly install the `elasticsearch` package (`pip install elasticsearch`) for the instrumentation to have a client to patch.
  Fix: Add `elasticsearch` to your project's dependencies.
• gotcha If no `TracerProvider` is configured and set globally using `trace.set_global_tracer_provider()`, the instrumentation will default to a `NoOpTracer`. This means no traces or spans will be collected, even if `instrument()` is called.
  Fix: Always configure and set a global `TracerProvider` with appropriate `SpanProcessor` and `SpanExporter` before using any OpenTelemetry instrumentation.

Install

• pip install opentelemetry-instrumentation-elasticsearch elasticsearch opentelemetry-sdk opentelemetry-exporter-otlp Install with OTLP Exporter

Imports

• ElasticsearchInstrumentor

  from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor

• TracerProvider

  from opentelemetry.sdk.trace import TracerProvider

  TracerProvider is an SDK concept; the API provides `trace.get_tracer_provider()` but not `TracerProvider` directly for instantiation.
• set_global_tracer_provider

  from opentelemetry import trace; trace.set_global_tracer_provider(...)

Quickstart

This quickstart configures a basic OpenTelemetry SDK with a `ConsoleSpanExporter` to print traces to the console. It then instruments the Elasticsearch client and attempts a `ping()` and `index()` operation. Spans representing these operations will be generated and printed to stdout. It includes error handling for cases where an Elasticsearch instance is not running.

import os
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor
from elasticsearch import Elasticsearch, ConnectionError # Import ConnectionError for graceful handling

# 1. Configure OpenTelemetry Tracer Provider
# For demonstration, use ConsoleSpanExporter to print traces to stdout
resource = Resource.create({"service.name": "my-elasticsearch-app"})
tracer_provider = TracerProvider(resource=resource)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
tracer_provider.add_span_processor(span_processor)
trace.set_global_tracer_provider(tracer_provider)

# 2. Instrument Elasticsearch
ElasticsearchInstrumentor().instrument()

# 3. Use the Elasticsearch client
# Ensure an Elasticsearch instance is running at this address.
# For a quick runnable example without a real ES instance, we'll catch ConnectionError.
try:
    # Replace with your Elasticsearch host if different. This will attempt connection.
    client = Elasticsearch("http://localhost:9200") 
    print("Attempting to ping Elasticsearch...")
    if client.ping():
        print("Elasticsearch connection successful! Spans should be visible.")
    else:
        print("Could not ping Elasticsearch. Check its status.")
    
    # Example of an index operation that will also be traced
    print("Indexing a document...")
    client.index(index="my-test-index", id=1, document={"message": "hello opentelemetry"})
    print("Document indexed. Check for additional spans.")

except ConnectionError as e:
    print(f"Could not connect to Elasticsearch: {e}")
    print("Spans for the connection attempt should still be generated, even if it failed.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

finally:
    # Ensure all spans are exported before exiting
    tracer_provider.shutdown()