1Search::Elasticsearch::URsoelre:C:oCnxtnr(i3b)uted PerlSDeoacrucmhe:n:tEaltaisotnicsearch::Role::Cxn(3)
2
6 Search::Elasticsearch::Role::Cxn - Provides common functionality to
7 HTTP Cxn implementations
8
10 version 7.715
11
13 Search::Elasticsearch::Role::Cxn provides common functionality to Cxn
14 implementations. Cxn instances are created by a
15 Search::Elasticsearch::Role::CxnPool implementation, using the
16 Search::Elasticsearch::Cxn::Factory class.
17
19 The configuration options are as follows:
20 "node"
22 A single "node" is passed to "new()" by the
23 Search::Elasticsearch::Cxn::Factory class. It can either be a URI or a
24 hash containing each part. For instance:
25 node => 'localhost'; # equiv of 'http://localhost:80'
27 node => 'localhost:9200'; # equiv of 'http://localhost:9200'
28 node => 'http://localhost:9200';
29 node => 'https://localhost'; # equiv of 'https://localhost:443'
31 node => 'localhost/path'; # equiv of 'http://localhost:80/path'
32 node => 'http://user:pass@localhost'; # equiv of 'http://localhost:80'
35 # with userinfo => 'user:pass'
36 Alternatively, a "node" can be specified as a hash:
38 {
40 scheme => 'http',
41 host => 'search.domain.com',
42 port => '9200',
43 path => '/path',
44 userinfo => 'user:pass'
45 }
46 Similarly, default values can be specified with "port", "path_prefix",
48 "userinfo" and "use_https":
49 $e = Search::Elasticsearch->new(
51 port => 9201,
52 path_prefix => '/path',
53 userinfo => 'user:pass',
54 use_https => 1,
55 nodes => [ 'search1', 'search2' ]
56 )
57 "ssl_options"
59 By default, all backends that support HTTPS disable verification of the
60 host they are connecting to. Use "ssl_options" to configure the type
61 of verification that you would like the client to perform, or to
62 configure the client to present its own certificate.
63 The values accepted by "ssl_options" depend on the "Cxn" class. See
65 the documentation for the "Cxn" class that you are using.
66 "max_content_length"
68 By default, Elasticsearch nodes accept a maximum post body of 100MB or
69 "104_857_600" bytes. This client enforces that limit. The limit can be
70 customised with the "max_content_length" parameter (specified in
71 bytes).
72 If you're using the Search::Elasticsearch::CxnPool::Sniff module, then
74 the "max_content_length" will be automatically retrieved from the live
75 cluster, unless you specify a custom "max_content_length":
76 # max_content_length retrieved from cluster
78 $e = Search::Elasticsearch->new(
79 cxn_pool => 'Sniff'
80 );
81 # max_content_length fixed at 10,000 bytes
83 $e = Search::Elasticsearch->new(
84 cxn_pool => 'Sniff',
85 max_content_length => 10_000
86 );
87 "gzip"
89 Enable Gzip compression of requests to and responses from Elasticsearch
90 as follows:
91 $e = Search::Elasticsearch->new(
93 gzip => 1
94 );
95 "deflate"
97 Enable Inflate/Deflate compression of requests to and responses from
98 Elasticsearch as follows:
99 $e = Search::Elasticsearch->new(
101 deflate => 1
102 );
103 IMPORTANT: The "request_timeout", "ping_timeout", "sniff_timeout", and
105 "sniff_request_timeout" parameters default to values that allow this
106 module to function with low powered hardware and slow networks. When
107 you use Elasticsearch in production, you will probably want to reduce
108 these timeout parameters to values that suit your environment.
109 The configuration parameters are as follows:
111 "request_timeout"
113 $e = Search::Elasticsearch->new(
114 request_timeout => 30
115 );
116 How long a normal request (ie not a ping or sniff request) should wait
118 before throwing a "Timeout" error. Defaults to 30 seconds.
119 Note: In production, no CRUD or search request should take 30 seconds
121 to run, although admin tasks like "upgrade()", "optimize()", or
122 snapshot "create()" may take much longer. A more reasonable value for
123 production would be 10 seconds or lower.
124 "ping_timeout"
126 $e = Search::Elasticsearch->new(
127 ping_timeout => 2
128 );
129 How long a ping request should wait before throwing a "Timeout" error.
131 Defaults to 2 seconds. The Search::Elasticsearch::CxnPool::Static
132 module pings nodes on first use, after any failure, and periodically to
133 ensure that nodes are healthy. The "ping_timeout" should be long enough
134 to allow nodes respond in time, but not so long that sick nodes cause
135 delays. A reasonable value for use in production on reasonable
136 hardware would be 0.3-1 seconds.
137 "dead_timeout"
139 $e = Search::Elasticsearch->new(
140 dead_timeout => 60
141 );
142 How long a Cxn should be considered to be dead (not used to serve
144 requests), before it is retried. The default is 60 seconds. This
145 value is increased by powers of 2 for each time a request fails. In
146 other words, the delay after each failure is as follows:
147 Failure Delay
149 1 60 * 1 = 60 seconds
150 2 60 * 2 = 120 seconds
151 3 60 * 4 = 240 seconds
152 4 60 * 8 = 480 seconds
153 5 60 * 16 = 960 seconds
154 "max_dead_timeout"
156 $e = Search::Elasticsearch->new(
157 max_dead_timeout => 3600
158 );
159 The maximum delay that should be applied to a failed node. If the
161 "dead_timeout" calculation results in a delay greater than
162 "max_dead_timeout" (default "3,600" seconds) then the
163 "max_dead_timeout" is used instead. In other words, dead nodes will be
164 retried at least once every hour by default.
165 "sniff_request_timeout"
167 $e = Search::Elasticsearch->new(
168 sniff_request_timeout => 2
169 );
170 How long a sniff request should wait before throwing a "Timeout" error.
172 Defaults to 2 seconds. A reasonable value for production would be 0.5-2
173 seconds.
174 "sniff_timeout"
176 $e = Search::Elasticsearch->new(
177 sniff_timeout => 1
178 );
179 How long the node being sniffed should wait for responses from other
181 nodes before responding to the client. Defaults to 1 second. A
182 reasonable value in production would be 0.3-1 seconds.
183 Note: The "sniff_timeout" is distinct from the "sniff_request_timeout".
185 For example, let's say you have a cluster with 5 nodes, 2 of which are
186 unhealthy (taking a long time to respond):
187 • If you sniff an unhealthy node, the request will throw a "Timeout"
189 error after "sniff_request_timeout" seconds.
190 • If you sniff a healthy node, it will gather responses from the
192 other nodes, and give up after "sniff_timeout" seconds, returning
193 just the information it has managed to gather from the healthy
194 nodes.
195 NOTE: The "sniff_request_timeout" must be longer than the
197 "sniff_timeout" to ensure that you get information about healthy nodes
198 from the cluster.
199 "handle_args"
201 Any default arguments which should be passed when creating a new
202 instance of the class which handles the network transport, eg
203 HTTP::Tiny.
204 "default_qs_params"
206 $e = Search::Elasticsearch->new(
207 default_qs_params => {
208 session_key => 'my_session_key'
209 }
210 );
211 Any values passed to "default_qs_params" will be added to the query
213 string of every request. Also see "default_headers()" in
214 Search::Elasticsearch::Role::Cxn::HTTP.
215
217 None of the methods listed below are useful to the user. They are
218 documented for those who are writing alternative implementations only.
219 "scheme()"
221 $scheme = $cxn->scheme;
222 Returns the scheme of the connection, ie "http" or "https".
224 "is_https()"
226 $bool = $cxn->is_https;
227 Returns "true" or "false" depending on whether the "/scheme()" is
229 "https" or not.
230 "userinfo()"
232 $userinfo = $cxn->userinfo
233 Returns the username and password of the cxn, if any, eg "user:pass".
235 If "userinfo" is provided, then a Basic Authorization header is added
236 to each request.
237 "default_headers()"
239 $headers = $cxn->default_headers
240 The default headers that are passed with each request. This includes
242 the "Accept-Encoding" header if "/deflate" is true, and the
243 "Authorization" header if "/userinfo" has a value. Also see
244 "default_qs_params" in Search::Elasticsearch::Role::Cxn.
245 "max_content_length()"
247 $int = $cxn->max_content_length;
248 Returns the maximum length in bytes that the HTTP body can have.
250 "build_uri()"
252 $uri = $cxn->build_uri({ path => '/_search', qs => { size => 10 }});
253 Returns the HTTP URI to use for a particular request, combining the
255 passed in "path" parameter with any defined "path_prefix", and adding
256 the query-string parameters.
257
259 None of the methods listed below are useful to the user. They are
260 documented for those who are writing alternative implementations only.
261 "host()"
263 $host = $cxn->host;
264 The value of the "host" parameter, eg "search.domain.com".
266 "port()"
268 $port = $cxn->port;
269 The value of the "port" parameter, eg 9200.
271 "uri()"
273 $uri = $cxn->uri;
274 A URI object representing the node, eg
276 "https://search.domain.com:9200/path".
277 "is_dead()"
279 $bool = $cxn->is_dead
280 Is the current node marked as dead.
282 "is_live()"
284 $bool = $cxn->is_live
285 Is the current node marked as live.
287 "next_ping()"
289 $time = $cxn->next_ping($time)
290 Get/set the time for the next scheduled ping. If zero, no ping is
292 scheduled and the cxn is considered to be alive. If -1, a ping is
293 scheduled before the next use.
294 "ping_failures()"
296 $num = $cxn->ping_failures($num)
297 The number of times that a cxn has been marked as dead.
299 "mark_dead()"
301 $cxn->mark_dead
302 Mark the cxn as dead, set "next_ping()" and increment
304 "ping_failures()".
305 "mark_live()"
307 Mark the cxn as live, set "next_ping()" and "ping_failures()" to zero.
308 "force_ping()"
310 Set "next_ping()" to -1 (ie before next use) and "ping_failures()" to
311 zero.
312 "pings_ok()"
314 $bool = $cxn->pings_ok
315 Try to ping the node and call "mark_live()" or "mark_dead()" depending
317 on the success or failure of the ping.
318 "sniff()"
320 $response = $cxn->sniff;
321 Send a sniff request to the node and return the response.
323 "process_response()"
325 ($code,$result) = $cxn->process_response($params, $code, $msg, $body );
326 Processes the response received from an Elasticsearch node and either
328 returns the HTTP status code and the response body (deserialized from
329 JSON) or throws an error of the appropriate type.
330 The $params are the original params passed to "perform_request()" in
332 Search::Elasticsearch::Transport, the $code is the HTTP status code,
333 the $msg is the error message returned by the backend library and the
334 $body is the HTTP response body returned by Elasticsearch.
335
337 Enrico Zimuel <enrico.zimuel@elastic.co>
338
340 This software is Copyright (c) 2021 by Elasticsearch BV.
341 This is free software, licensed under:
343 The Apache License, Version 2.0, January 2004
345perl v5.34.0 2022-01-21Search::Elasticsearch::Role::Cxn(3)