Elasticsearch

See every request your application makes to Elasticsearch, including its operation, duration, outcome, and target, as a span (one unit of work: a single operation, with a name, a start, and a duration) in Logfire.

Logfire is built on OpenTelemetry (OTel), the open industry standard for collecting traces, metrics, and logs. From version 8.15, the Elasticsearch Python client uses OTel directly to create spans through the active global tracer provider. You do not need a Logfire wrapper or the older opentelemetry-instrumentation-elasticsearch package.

Before you start

You’ll need a Logfire project. Open Add data in your project (top navigation) and follow the setup for your language: it signs your machine in with logfire auth (a browser sign-in, no token to copy) and, for production or other languages, creates a write token (the credential your app uses to send data). New to Logfire? Start with Getting Started.

Install the client

Install Logfire and Elasticsearch 8.15 or later:

Terminal

pip install 'logfire' 'elasticsearch>=8.15'

Trace Elasticsearch requests

Call logfire.configure() before making an Elasticsearch request. The client looks up the active OTel tracer provider when it starts a request, so you can create the client before or after this call. Requests made before configuration are not sent to Logfire, but requests made after configuration are traced normally.

from elasticsearch import Elasticsearch

import logfire

client = Elasticsearch('http://localhost:9200')

logfire.configure()
client.search(index='products', query={'match': {'name': 'coffee'}})

Control whether search queries are recorded

By default, the client does not attach the search query body to spans because it can contain sensitive or personally identifiable information (PII). To record query bodies, set this environment variable before starting your application:

Terminal

export OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_CAPTURE_SEARCH_QUERY=raw

Caution

Setting this option to raw sends query values to Logfire, where they are stored with the span. Logfire does not scrub the db.query.text attribute. Enable query capture only when the queries do not contain sensitive values.

Stop tracing Elasticsearch requests

The Elasticsearch client creates spans by default whenever an OTel tracer provider is active. To turn off its native tracing, set this environment variable before creating the client:

Terminal

export OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_ENABLED=false

Troubleshoot missing spans

• No Elasticsearch spans appear: check that you use elasticsearch 8.15 or later, call logfire.configure() before the request you want to trace, and have not set OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_ENABLED=false.
• The query body is missing: restart the application after setting OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_CAPTURE_SEARCH_QUERY=raw. Query capture is disabled by default.
• Duplicate spans appear: remove opentelemetry-instrumentation-elasticsearch and its setup. The client already creates spans natively.

Reference

• Elasticsearch Python client OpenTelemetry documentation