Instalation

Run the following command:

$ pip install signalfx-instrumentation-elasticsearch

Getting started

Please see the examples directory. Overall, usage requires that a tracer gets set, and initialize the Elasticsearch client specifying TracingTransport as tracing class, and optionally set an active span (to be used as parent span when tracing the actual Elasticsearch statements):

import elasticsearch_opentracing

elasticsearch_opentracing.init_tracing(tracer) # An OpenTracing compatible tracer.
es = Elasticsearch(transport_class=elasticsearch_opentracing.TracingTransport)

elasticsearch_opentracing.set_active_span(main_span) # Optional.

es.index(index='test-index', doc_type='tweet', id=99, body={
    'author': 'linus',
    'text': 'Hello there',
    'timestamp': datetime.now(),
})
res = es.get(index='test-index', doc_type='tweet', id=99)

elasticsearch_opentracing.clear_active_span()

By default, all Elasticsearch requests are traced. It’s possible to have it set to false when initializing the library, and call enable_tracing and disable_tracing to explicitly trace statements happening within that section:

elasticsearch_opentracing.init_tracing(tracer, trace_all_requests=False)

elasticsearch_opentracing.enable_tracing()

res1 = es.get(index='test-index', doc_type='tweet', id=99)
res2 = es.get(index='test-index', doc_type='user', id=666)

elasticsearch_opentracing.disable_tracing()

When using trace_all_requests, any calls made to enable_tracing and disable_tracing are ignored.

In case of an exception happening under this block, an implicit call to disable_tracing will take place, with the request causing the error including error information with it.

DSL

When using the elasticsearch-dsl library (which runs on top of elasticsearch-py), the same semantics and calls are used. When creating a default connection, the transport can be specified as well:

# elasticsearch_dsl.connections.connections
connections.create_connection(hosts=['127.0.0.1'],
                              transport_class=elasticsearch_opentracing.TracingTransport)

Multithreading

Tracing and parent span data is kept as thread local data, which means that applications using many threads (Django, Flask, Pyramid, etc) will work just fine.

Further information

If you’re interested in learning more about the OpenTracing standard, please visit opentracing.io or join the mailing list. If you would like to implement OpenTracing in your project and need help, feel free to send us a note at community@opentracing.io.