signalfx-instrumentation-elasticsearch 1.0.1
OpenTracing support for Elasticsearch
License: Apache License 2.0

#########################
ElasticSearch Opentracing
#########################

This package enables distributed tracing for the Python elasticsearch-py and elasticsearch-dsl libraries.

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):

.. code-block:: python

    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:

.. code-block:: python

    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:

.. code-block:: python

    # 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`_.

.. _opentracing.io: http://opentracing.io/
.. _join the mailing list: http://opentracing.us13.list-manage.com/subscribe?u=180afe03860541dae59e84153&id=19117aa6cd
.. _community@opentracing.io: community@opentracing.io