Elasticsearch instrumentation
Add Respan TASK input/output to the official Elasticsearch client's native
OpenTelemetry spans. Elasticsearch 8.13 through 9.x sync and async clients use
their real transport and typed response objects. This adapter retains native
span names and helper tracing, and observes the API response before its native
span ends. It creates a span for direct elastic_transport requests.
pip install 'elasticsearch[async]>=8.13,<10' respan-instrumentation-elasticsearch
For review before the paired change is published, install this package checkout
with python -m pip install . from its directory, or install its validated wheel.
The older published plugin does not contain these repairs. The checkout version
is managed by the repository's release workflow.
Configure your initialized native client and exporter in the application, then pass the same OTel provider explicitly:
from elasticsearch import Elasticsearch
from opentelemetry.sdk.trace import TracerProvider
from respan_instrumentation_elasticsearch import ElasticsearchInstrumentor
def search_with_tracing(client: Elasticsearch, provider: TracerProvider):
instrumentor = ElasticsearchInstrumentor(tracer_provider=provider)
instrumentor.activate()
try:
return client.search(index="documents", query={"match_all": {}})
finally:
instrumentor.deactivate()
Without an explicit provider, the adapter resolves the application's global
provider when calls begin. Native SDK tracing must be enabled; the SDK's
OTEL_PYTHON_INSTRUMENTATION_ELASTICSEARCH_ENABLED=false opt-out is honored.
The community OTel instrumentor already defers to these native spans and only
wraps sync transport; activating it does not provide canonical Respan capture.
The SDK's mature tracing remains the delegate here.
Automatic DB operations emit respan.entity.log_type=task, upstream database,
server and HTTP attributes sourced from native spans/response metadata, and
canonical JSON input/output. They do not emit embedding/model/token usage or
invent a status. Requests retain method, target, params, headers, native path
configuration, body and effective transport settings. Output preserves the
native body, including full vectors, history, schema, false, zero and empty
values. Native response metadata is retained separately at
respan.metadata.elasticsearch.response. Raised native errors retain their
actual type/status and sanitized native message; no error output is fabricated.
Ignored HTTP errors preserve the actual returned body and remain successful
native API calls. HeadApiResponse preserves its actual boolean, including
false. Object/list/text/binary responses and native streaming_bulk generators
retain their concrete type, identity, bytes, iteration and resource behavior.
Content capture defaults on with no adapter size/item cap. Set
capture_content=False, RESPAN_TRACE_CONTENT=false, or
TRACELOOP_TRACE_CONTENT=false for bodyless spans. The canonical Respan context
flag and Traceloop override/attribute flag are honored before extraction, at
callbacks, and before detach/end. Initial and observed ancestor vetoes cannot
widen later. General and LLM suppression and sampling prevent extraction;
unknown local span carriers fail closed, while genuine remote parents retain
propagation. Credential values are redacted in native JSON, headers, text and
URLs, including sensitive schema defaults. Unknown customer object conversion
and formatting hooks are omitted from telemetry. Approved structural run
markers survive private spans; other diagnostic events/messages/descriptions
are cleared, including the SDK's finished-span snapshot on late vetoes.
max_attribute_chars=None is the default. An explicitly supplied positive
integer opts into a preview envelope for oversized canonical JSON; native data
is never modified. The OTel SDK's own attribute-count limit can bound indexed
or convenience fields; full canonical input/output are written last.
Optional request_hook(span, method, target, kwargs) and
response_hook(span, native_body) run only during eligible capture. Their
failures fail closed for telemetry and preserve the native operation.
Activation/deactivation is idempotent and shared for matching configuration;
conflicting active configuration raises ValueError. Owned patches/processors
are removed by identity, retaining foreign wrappers. Deactivation during an
active call vetoes its retained content; its native call still completes.
Elasticsearch 8.13 lacks newer helpers_span/use_span methods, so bulk helper
wrapper spans depend on the native version; request spans are captured in both.
The adapter does not drain a caller generator or aggregate a helper wrapper's
unconsumed results. Fixture validation uses genuine localhost HTTP transports
and parsers; it does not validate a running Elasticsearch search engine.
Complete local-first examples are in python/tracing/elasticsearch of the
examples repository. Live-cluster calls and synthetic trace export have
separate explicit opt-ins. HTTP export success and stored-trace semantic
acceptance are separate checks.
Metadata
Release files for respan-instrumentation-elasticsearch 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| respan_instrumentation_elasticsearch-0.2.0.tar.gz | 16.0 kB | With provenance | Details for respan_instrumentation_elasticsearch-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| respan_instrumentation_elasticsearch-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for respan_instrumentation_elasticsearch-0.2.0-py3-none-any.whl |
Total release size: 32.8 kB
Release files / respan_instrumentation_elasticsearch-0.2.0.tar.gz
| Download URL | respan_instrumentation_elasticsearch-0.2.0.tar.gz |
|---|---|
| Size | 16.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
233c2f6e738e21984532a7e9ad60964110410f47a6d8fc72f7a06ecece9e9060
|
|
BLAKE2b-256 checksum How to use checksums |
bfa03c6d5f382c089503718c6393836ea59c444b4116d9f53eade5c8bc29c96a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logRelease files / respan_instrumentation_elasticsearch-0.2.0-py3-none-any.whl
| Download URL | respan_instrumentation_elasticsearch-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f31e0ad934d71d52d9070708baaea07f29bcdb8e78f804b45bcf2f8406aa95da
|
|
BLAKE2b-256 checksum How to use checksums |
674bed30a664217f0206abfc1b5b55936a3d09698bc8832471aac7fe3e8265ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logSecurity for respan-instrumentation-elasticsearch 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for respan_instrumentation_elasticsearch-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 13, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.