Registry / observability / opentelemetry-instrumentation-elasticsearch

opentelemetry-instrumentation-elasticsearch

JSON →
library0.64b0pypypi✓ verified 23d ago

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.

pip install opentelemetry-instrumentation-elasticsearch elasticsearch opentelemetry-sdk opentelemetry-exporter-otlp
INSTALL
IMPORT
SIG · OPENTELEMETRY-INST
O
opentelemetry-instrumentation-elasticsearch
observabilitypythonv0.64b0
Install
6.4s avg
Import
1390ms
Disk
65MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.64b0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 1.436s · 66.1MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 6.4s · import 1.344s · 65MB
65MB installed
● package 65MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ElasticsearchInstrumentor
from opentelemetry.instrumentation.elasticsearch import ElasticsearchInstrumentor
TracerProvider
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.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(...)

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()
Debug
Known issues
breakingAs 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.
affects: 0.x.x series
gotchaThe `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.
affects: All versions
gotchaThis 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.
affects: All versions
gotchaIf 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.
affects: All versions
Upgrade
Version history
0.64b0latest on PyPI · released Jun 24, 2026
Audit
Dependencies
elasticsearchrequiredThe library being instrumented by opentelemetry-instrumentation-elasticsearch.
opentelemetry-sdkrequiredRequired for OpenTelemetry SDK functionalities, including TracerProvider and SpanProcessors.
opentelemetry-exporter-otlpoptionalA common exporter for sending telemetry data to an OTLP collector. Other exporters can be used.
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
opentelemetry-instrumentation-elasticsearch — pip install opentelemetry-instrumentation-elasticsearch · libregistry