Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  SEARCH::ELASTICSEARCH::ROLE::CXN (3)

.ds Aq ’


Search::Elasticsearch::Role::Cxn - Provides common functionality to Cxn implementations



version 2.00


Search::Elasticsearch::Role::Cxn provides common functionality to the Cxn implementations. Cxn instances are created by a Search::Elasticsearch::Role::CxnPool implementation, using the Search::Elasticsearch::Cxn::Factory class.


<B>IMPORTANT:B> The request_timeout, ping_timeout, sniff_timeout, and sniff_request_timeout parameters default to values that allow this module to function with low powered hardware and slow networks. When you use Elasticsearch in production, you will probably want to reduce these timeout parameters to values that suit your environment.

The configuration parameters are as follows:


    $e = Search::Elasticsearch->new(
        request_timeout => 30

How long a normal request (ie not a ping or sniff request) should wait before throwing a Timeout error. Defaults to 30 seconds.

<B>Note:B> In production, no CRUD or search request should take 30 seconds to run, although admin tasks like upgrade(), optimize(), or snapshot create() may take much longer. A more reasonable value for production would be 10 seconds or lower.


    $e = Search::Elasticsearch->new(
        ping_timeout => 2

How long a ping request should wait before throwing a Timeout error. Defaults to 2 seconds. The Search::Elasticsearch::CxnPool::Static module pings nodes on first use, after any failure, and periodically to ensure that nodes are healthy. The ping_timeout should be long enough to allow nodes respond in time, but not so long that sick nodes cause delays. A reasonable value for use in production on reasonable hardware would be 0.3-1 seconds.


    $e = Search::Elasticsearch->new(
        dead_timeout => 60

How long a Cxn should be considered to be dead (not used to serve requests), before it is retried. The default is 60 seconds. This value is increased by powers of 2 for each time a request fails. In other words, the delay after each failure is as follows:

    Failure     Delay
    1           60 * 1  = 60 seconds
    2           60 * 2  = 120 seconds
    3           60 * 4  = 240 seconds
    4           60 * 8  = 480 seconds
    5           60 * 16 = 960 seconds


    $e = Search::Elasticsearch->new(
        max_dead_timeout => 3600

The maximum delay that should be applied to a failed node. If the dead_timeout calculation results in a delay greater than max_dead_timeout (default 3,600 seconds) then the max_dead_timeout is used instead. In other words, dead nodes will be retried at least once every hour by default.


    $e = Search::Elasticsearch->new(
        sniff_request_timeout => 2

How long a sniff request should wait before throwing a Timeout error. Defaults to 2 seconds. A reasonable value for production would be 0.5-2 seconds.


    $e = Search::Elasticsearch->new(
        sniff_timeout => 1

How long the node being sniffed should wait for responses from other nodes before responding to the client. Defaults to 1 second. A reasonable value in production would be 0.3-1 seconds.

<B>Note:B> The sniff_timeout is distinct from the sniff_request_timeout. For example, let’s say you have a cluster with 5 nodes, 2 of which are unhealthy (taking a long time to respond):
o If you sniff an unhealthy node, the request will throw a Timeout error after sniff_request_timeout seconds.
o If you sniff a healthy node, it will gather responses from the other nodes, and give up after sniff_timeout seconds, returning just the information it has managed to gather from the healthy nodes.
<B>NOTE:B> The sniff_request_timeout must be longer than the sniff_timeout to ensure that you get information about healthy nodes from the cluster.


Any default arguments which should be passed when creating a new instance of the class which handles the network transport, eg HTTP::Tiny.


    $e = Search::Elasticsearch->new(
        default_qs_params => {
            session_key => my_session_key

Any values passed to default_qs_params will be added to the query string of every request. Also see default_headers() in Search::Elasticsearch::Role::Cxn::HTTP.


None of the methods listed below are useful to the user. They are documented for those who are writing alternative implementations only.


    $host = $cxn->host;

The value of the host parameter, eg


    $port = $cxn->port;

The value of the port parameter, eg 9200.


    $uri = $cxn->uri;

A URI object representing the node, eg


    $bool = $cxn->is_dead

Is the current node marked as dead.


    $bool = $cxn->is_live

Is the current node marked as live.


    $time = $cxn->next_ping($time)

Get/set the time for the next scheduled ping. If zero, no ping is scheduled and the cxn is considered to be alive. If -1, a ping is scheduled before the next use.


    $num = $cxn->ping_failures($num)

The number of times that a cxn has been marked as dead.



Mark the cxn as dead, set next_ping() and increment ping_failures().


Mark the cxn as live, set next_ping() and ping_failures() to zero.


Set next_ping() to -1 (ie before next use) and ping_failures() to zero.


    $bool = $cxn->pings_ok

Try to ping the node and call mark_live() or mark_dead() depending on the success or failure of the ping.


    $response = $cxn->sniff;

Send a sniff request to the node and return the response.


    ($code,$result) = $cxn->process_response($params, $code, $msg, $body );

Processes the response received from an Elasticsearch node and either returns the HTTP status code and the response body (deserialized from JSON) or throws an error of the appropriate type.

The $params are the original params passed to perform_request() in Search::Elasticsearch::Transport, the $code is the HTTP status code, the $msg is the error message returned by the backend library and the $body is the HTTP response body returned by Elasticsearch.


Clinton Gormley <>


This software is Copyright (c) 2015 by Elasticsearch BV.

This is free software, licensed under:

  The Apache License, Version 2.0, January 2004

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 SEARCH::ELASTICSEARCH::ROLE::CXN (3) 2015-10-28

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.