-
-
02 Apr 2017 17:26:58 UTC
- Distribution: Search-Elasticsearch
- Module version: 5.02
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Repository
- Issues
- Testers (766 / 2 / 0)
- Kwalitee
Bus factor: 1- 72.02% Coverage
- License: apache_2_0
- Activity
24 month- Tools
- Download (101.58KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
- Dependencies
- Any::URI::Escape
- Data::Dumper
- Devel::GlobalDestruction
- Encode
- File::Temp
- HTTP::Headers
- HTTP::Request
- HTTP::Tiny
- IO::Compress::Deflate
- IO::Compress::Gzip
- IO::Select
- IO::Socket
- IO::Uncompress::Gunzip
- IO::Uncompress::Inflate
- JSON::MaybeXS
- JSON::PP
- LWP::UserAgent
- List::Util
- Log::Any
- Log::Any::Adapter
- MIME::Base64
- Module::Runtime
- Moo
- Moo::Role
- POSIX
- Package::Stash
- Scalar::Util
- Sub::Exporter
- Time::HiRes
- Try::Tiny
- URI
- namespace::clean
- overload
- strict
- warnings
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Search::Elasticsearch::Role::Cxn - Provides common functionality to HTTP Cxn implementations
VERSION
version 5.02
DESCRIPTION
Search::Elasticsearch::Role::Cxn provides common functionality to Cxn implementations. Cxn instances are created by a Search::Elasticsearch::Role::CxnPool implementation, using the Search::Elasticsearch::Cxn::Factory class.
CONFIGURATION
The configuration options are as follows:
node
A single
node
is passed tonew()
by the Search::Elasticsearch::Cxn::Factory class. It can either be a URI or a hash containing each part. For instance:node => 'localhost'; # equiv of 'http://localhost:80' node => 'localhost:9200'; # equiv of 'http://localhost:9200' node => 'http://localhost:9200'; node => 'https://localhost'; # equiv of 'https://localhost:443' node => 'localhost/path'; # equiv of 'http://localhost:80/path' node => 'http://user:pass@localhost'; # equiv of 'http://localhost:80' # with userinfo => 'user:pass'
Alternatively, a
node
can be specified as a hash:{ scheme => 'http', host => 'search.domain.com', port => '9200', path => '/path', userinfo => 'user:pass' }
Similarly, default values can be specified with
port
,path_prefix
,userinfo
anduse_https
:$e = Search::Elasticsearch->new( port => 9201, path_prefix => '/path', userinfo => 'user:pass', use_https => 1, nodes => [ 'search1', 'search2' ] )
ssl_options
By default, all backends that support HTTPS disable verification of the host they are connecting to. Use
ssl_options
to configure the type of verification that you would like the client to perform, or to configure the client to present its own certificate.The values accepted by
ssl_options
depend on theCxn
class. See the documentation for theCxn
class that you are using.max_content_length
By default, Elasticsearch nodes accept a maximum post body of 100MB or
104_857_600
bytes. This client enforces that limit. The limit can be customised with themax_content_length
parameter (specified in bytes).If you're using the Search::Elasticsearch::CxnPool::Sniff module, then the
max_content_length
will be automatically retrieved from the live cluster, unless you specify a custommax_content_length
:# max_content_length retrieved from cluster $e = Search::Elasticsearch->new( cxn_pool => 'Sniff' ); # max_content_length fixed at 10,000 bytes $e = Search::Elasticsearch->new( cxn_pool => 'Sniff', max_content_length => 10_000 );
gzip
Enable Gzip compression of requests to and responses from Elasticsearch as follows:
$e = Search::Elasticsearch->new( gzip => 1 );
deflate
Enable Inflate/Deflate compression of requests to and responses from Elasticsearch as follows:
$e = Search::Elasticsearch->new( deflate => 1 );
IMPORTANT: 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:
request_timeout
$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 to30
seconds.Note: In production, no CRUD or search request should take 30 seconds to run, although admin tasks like
upgrade()
,optimize()
, or snapshotcreate()
may take much longer. A more reasonable value for production would be10
seconds or lower.ping_timeout
$e = Search::Elasticsearch->new( ping_timeout => 2 );
How long a ping request should wait before throwing a
Timeout
error. Defaults to2
seconds. The Search::Elasticsearch::CxnPool::Static module pings nodes on first use, after any failure, and periodically to ensure that nodes are healthy. Theping_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 be0.3
-1
seconds.dead_timeout
$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
max_dead_timeout
$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
(default3,600
seconds) then themax_dead_timeout
is used instead. In other words, dead nodes will be retried at least once every hour by default.sniff_request_timeout
$e = Search::Elasticsearch->new( sniff_request_timeout => 2 );
How long a sniff request should wait before throwing a
Timeout
error. Defaults to2
seconds. A reasonable value for production would be0.5
-2
seconds.sniff_timeout
$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 be0.3
-1
seconds.Note: 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):If you sniff an unhealthy node, the request will throw a
Timeout
error aftersniff_request_timeout
seconds.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.
NOTE: The
sniff_request_timeout
must be longer than thesniff_timeout
to ensure that you get information about healthy nodes from the cluster.handle_args
Any default arguments which should be passed when creating a new instance of the class which handles the network transport, eg HTTP::Tiny.
default_qs_params
$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.METHODS
None of the methods listed below are useful to the user. They are documented for those who are writing alternative implementations only.
scheme()
$scheme = $cxn->scheme;
Returns the scheme of the connection, ie
http
orhttps
.is_https()
$bool = $cxn->is_https;
Returns
true
orfalse
depending on whether the/scheme()
ishttps
or not.userinfo()
$userinfo = $cxn->userinfo
Returns the username and password of the cxn, if any, eg
"user:pass"
. Ifuserinfo
is provided, then a Basic Authorization header is added to each request.default_headers()
$headers = $cxn->default_headers
The default headers that are passed with each request. This includes the
Accept-Encoding
header if/deflate
is true, and theAuthorization
header if/userinfo
has a value. Also see "default_qs_params" in Search::Elasticsearch::Role::Cxn.max_content_length()
$int = $cxn->max_content_length;
Returns the maximum length in bytes that the HTTP body can have.
build_uri()
$uri = $cxn->build_uri({ path => '/_search', qs => { size => 10 }});
Returns the HTTP URI to use for a particular request, combining the passed in
path
parameter with any definedpath_prefix
, and adding the query-string parameters.METHODS
None of the methods listed below are useful to the user. They are documented for those who are writing alternative implementations only.
host()
$host = $cxn->host;
The value of the
host
parameter, egsearch.domain.com
.port()
$port = $cxn->port;
The value of the
port
parameter, eg9200
.uri()
$uri = $cxn->uri;
A URI object representing the node, eg
https://search.domain.com:9200/path
.is_dead()
$bool = $cxn->is_dead
Is the current node marked as dead.
is_live()
$bool = $cxn->is_live
Is the current node marked as live.
next_ping()
$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.
ping_failures()
$num = $cxn->ping_failures($num)
The number of times that a cxn has been marked as dead.
mark_dead()
$cxn->mark_dead
Mark the cxn as dead, set "next_ping()" and increment "ping_failures()".
mark_live()
Mark the cxn as live, set "next_ping()" and "ping_failures()" to zero.
force_ping()
Set "next_ping()" to -1 (ie before next use) and "ping_failures()" to zero.
pings_ok()
$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.
sniff()
$response = $cxn->sniff;
Send a sniff request to the node and return the response.
process_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.AUTHOR
Clinton Gormley <drtech@cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2017 by Elasticsearch BV.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
Module Install Instructions
To install Search::Elasticsearch, copy and paste the appropriate command in to your terminal.
cpanm Search::Elasticsearch
perl -MCPAN -e shell install Search::Elasticsearch
For more information on module installation, please visit the detailed CPAN module installation guide.