From 568ed079d143f589d5375fff1dbc11dbede36a1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Honza=20Kr=C3=A1l?= Date: Wed, 23 Oct 2013 16:55:00 +0200 Subject: [PATCH] Some additional documentation --- docs/connection.rst | 2 +- docs/index.rst | 59 +++++++++++++++++++++++++++++++++++++++------ docs/transports.rst | 10 ++++++++ 3 files changed, 62 insertions(+), 9 deletions(-) diff --git a/docs/connection.rst b/docs/connection.rst index d91a9c49..2e22f1ee 100644 --- a/docs/connection.rst +++ b/docs/connection.rst @@ -18,7 +18,7 @@ For example if you wanted to use your own implementation of the Transport --------- -.. autoclass:: Transport(hosts, connection_class=Urllib3HttpConnection, connection_pool_class=ConnectionPool, nodes_to_host_callback=construct_hosts_list, sniff_on_start=False, sniff_after_requests=None, sniff_on_connection_fail=False, serializer=JSONSerializer(), max_retries=3, ** kwargs) +.. autoclass:: Transport(hosts, connection_class=Urllib3HttpConnection, connection_pool_class=ConnectionPool, nodes_to_host_callback=construct_hosts_list, sniff_on_start=False, sniffer_timeout=None, sniff_on_connection_fail=False, serializer=JSONSerializer(), max_retries=3, ** kwargs) :members: diff --git a/docs/index.rst b/docs/index.rst index 3d66d5f2..0fea9a51 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -56,14 +56,29 @@ allow for maximum flexibility. This means that there are no opinions in this client; it also means that some of the APIs are a little cumbersome to use from Python. We have created some :ref:`helpers` to help with this issue. -Extendability -~~~~~~~~~~~~~ +Persistent Connections +~~~~~~~~~~~~~~~~~~~~~~ -Configurable connections and load balancing (see :ref:`connection_api`):: - * persistent connections - * configurable load balancing strategy - * different protocols and connection classes - * ... +``elasticsearch-py`` uses persistent connections inside of individual connection +pools (one per each configured or sniffed node). Out of the box you can choose +to use ``http``, ``thrift`` or an experimental ``memcached`` protocol to +communicate with the elasticsearch nodes. See :ref:`transports` for more +information. + +The transport layer will create an instance of the selected connection class +per node and keep track of the health of individual nodes - if a node becomes +unresponsive (throwing exceptions while connecting to it) it's put on a timeout +by the :class:`~elasticsearch.ConnectionPool` class and only returned to the +circulation after the timeout is over (or when no live nodes are left). By +default node are randomized before passed into the pool and round-robin +strategy is used for load balancing. + +You can customize this behavior by passing parameters to the +:ref:`connection_api` (all keyword arguments to the +:class:`~elasticsearch.Elasticsearch` class will be passed through). If what +you want to accomplish is not supported you should be able to create a subclass +of the relevant component and pass it in as a parameter to be used instead of +the default implementation. Sniffing @@ -72,7 +87,35 @@ Sniffing The client can be configured to inspect the cluster state to get a list of nodes upon startup, periodically and/or on failure. See :class:`~elasticsearch.Transport` parameters for details. - + +Some example configurations:: + + from elasticsearch import Elasticsearch + + # by default we don't sniff, ever + es = Elasticsearch() + + # you can specify to sniff on startup to inspect the cluster and load + # balance across all nodes + es = Elasticsearch(["seed1", "seed2"], sniff_on_start=True) + + # you can also sniff periodically and/or after failure: + es = Elasticsearch(["seed1", "seed2"], sniff_on_start=True, sniff_on_connection_fail=True, sniffer_timeout=60) + + +Logging +~~~~~~~ + +``elasticsearch-py`` uses the standard `logging library`_ from python to define +two loggers: ``elasticsearch`` and ``elasticsearch.trace``. ``elasticsearch`` +is used by the client to log standard activity, depending on the log level. +``elasticsearch.trace`` can be used to log requests to the server in the form +of ``curl`` commands using pretty-printed json that can then be executed from +command line. The tace logger doesn't inherit from the base one - it needs to +be activated separately. + +.. _logging library: http://docs.python.org/3.3/library/logging.html + Contents -------- diff --git a/docs/transports.rst b/docs/transports.rst index b4ab4e8e..35c64bb0 100644 --- a/docs/transports.rst +++ b/docs/transports.rst @@ -1,3 +1,5 @@ +.. _transports: + Transport classes ================= @@ -7,6 +9,14 @@ it to the constructor of :class:`~elasticsearch.Elasticsearch` as and require a plugin to be installed in your cluster as well as additional dependencies (`thrift==0.9` and `pylibmc==1.2`). +For example to use the thrift connection just import it and use it. The +connection classes are aware of their respective default ports (9500 for +thrift) so there is no need to specify them unless modified:: + + from elasticsearch import Elasticsearch, ThriftConnection + es = Elasticsearch(connection_class=ThriftConnection) + + .. py:module:: elasticsearch.connection Connection