{"id":2630,"library":"opentelemetry-instrumentation-elasticsearch","title":"OpenTelemetry Elasticsearch Instrumentation","description":"This library provides instrumentation for the Python Elasticsearch client, allowing automatic capture of traces and metrics for interactions with Elasticsearch databases. It is part of the OpenTelemetry Python Contrib repository, currently at version 0.62b0, and follows the OpenTelemetry project's frequent release cadence, often with beta versions.","status":"active","version":"0.62b0","language":"en","source_language":"en","source_url":"https://github.com/open-telemetry/opentelemetry-python-contrib","tags":["opentelemetry","observability","tracing","elasticsearch","instrumentation","database"],"install":[{"cmd":"pip install opentelemetry-instrumentation-elasticsearch elasticsearch opentelemetry-sdk opentelemetry-exporter-otlp","lang":"bash","label":"Install with OTLP Exporter"}],"dependencies":[{"reason":"The library being instrumented by opentelemetry-instrumentation-elasticsearch.","package":"elasticsearch"},{"reason":"Required for OpenTelemetry SDK functionalities, including TracerProvider and SpanProcessors.","package":"opentelemetry-sdk","optional":false},{"reason":"A common exporter for sending telemetry data to an OTLP collector. Other exporters can be used.","package":"opentelemetry-exporter-otlp","optional":true}],"imports":[{"symbol":"ElasticsearchInstrumentor","correct":"from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor"},{"note":"TracerProvider is an SDK concept; the API provides `trace.get_tracer_provider()` but not `TracerProvider` directly for instantiation.","wrong":"from opentelemetry.trace import TracerProvider","symbol":"TracerProvider","correct":"from opentelemetry.sdk.trace import TracerProvider"},{"symbol":"set_global_tracer_provider","correct":"from opentelemetry import trace; trace.set_global_tracer_provider(...)"}],"quickstart":{"code":"import os\nfrom opentelemetry import trace\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace import TracerProvider\nfrom opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor\nfrom opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor\nfrom elasticsearch import Elasticsearch, ConnectionError # Import ConnectionError for graceful handling\n\n# 1. Configure OpenTelemetry Tracer Provider\n# For demonstration, use ConsoleSpanExporter to print traces to stdout\nresource = Resource.create({\"service.name\": \"my-elasticsearch-app\"})\ntracer_provider = TracerProvider(resource=resource)\nspan_processor = SimpleSpanProcessor(ConsoleSpanExporter())\ntracer_provider.add_span_processor(span_processor)\ntrace.set_global_tracer_provider(tracer_provider)\n\n# 2. Instrument Elasticsearch\nElasticsearchInstrumentor().instrument()\n\n# 3. Use the Elasticsearch client\n# Ensure an Elasticsearch instance is running at this address.\n# For a quick runnable example without a real ES instance, we'll catch ConnectionError.\ntry:\n    # Replace with your Elasticsearch host if different. This will attempt connection.\n    client = Elasticsearch(\"http://localhost:9200\") \n    print(\"Attempting to ping Elasticsearch...\")\n    if client.ping():\n        print(\"Elasticsearch connection successful! Spans should be visible.\")\n    else:\n        print(\"Could not ping Elasticsearch. Check its status.\")\n    \n    # Example of an index operation that will also be traced\n    print(\"Indexing a document...\")\n    client.index(index=\"my-test-index\", id=1, document={\"message\": \"hello opentelemetry\"})\n    print(\"Document indexed. Check for additional spans.\")\n\nexcept ConnectionError as e:\n    print(f\"Could not connect to Elasticsearch: {e}\")\n    print(\"Spans for the connection attempt should still be generated, even if it failed.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n\nfinally:\n    # Ensure all spans are exported before exiting\n    tracer_provider.shutdown()\n","lang":"python","description":"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."},"warnings":[{"fix":"Consult the `opentelemetry-python-contrib` changelog for specific breaking changes related to Elasticsearch instrumentation when upgrading.","message":"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.","severity":"breaking","affected_versions":"0.x.x series"},{"fix":"Ensure `ElasticsearchInstrumentor().instrument()` is called early in your application's startup, prior to any Elasticsearch client instantiation or calls.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Add `elasticsearch` to your project's dependencies.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always configure and set a global `TracerProvider` with appropriate `SpanProcessor` and `SpanExporter` before using any OpenTelemetry instrumentation.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}