diff --git a/docs/configuration.asciidoc b/docs/configuration.asciidoc index e5c4f32f8..402c5e9a3 100644 --- a/docs/configuration.asciidoc +++ b/docs/configuration.asciidoc @@ -2,10 +2,11 @@ == Configuration -The client is designed to be easily configured for your needs. In the following +The client is designed to be easily configured for your needs. In the following section, you can see the possible options that you can use to configure it. * <> * <> +* <> * <> * <> diff --git a/docs/index.asciidoc b/docs/index.asciidoc index eda790be4..51206f0b0 100644 --- a/docs/index.asciidoc +++ b/docs/index.asciidoc @@ -21,3 +21,4 @@ include::reference.asciidoc[] include::examples/index.asciidoc[] include::helpers.asciidoc[] include::redirects.asciidoc[] +include::timeout-best-practices.asciidoc[] diff --git a/docs/timeout-best-practices.asciidoc b/docs/timeout-best-practices.asciidoc new file mode 100644 index 000000000..0d2fb4772 --- /dev/null +++ b/docs/timeout-best-practices.asciidoc @@ -0,0 +1,10 @@ +[[timeout-best-practices]] +=== Timeout best practices + +This client is configured by default to operate like many HTTP client libraries do, by using a relatively short (30 second) timeout on all requests sent to {es}, raising a `TimeoutError` when that time period has elapsed without receiving a response. However, {es} will always eventually respond to any request, even if it takes several minutes. The {ref}/modules-network.html#_http_client_configuration[official {es} recommendation] is to disable response timeouts entirely by default. + +Since changing this default would be a breaking change, we won't do that until the next major release. In the meantime, here is our recommendation for properly configuring your client: + +* Ensure keep-alive is enabled; this is the default, so no settings need to be changed, unless you have set `agent` to `false` or provided an alternate `agent` that disables keep-alive +* If using the default `UndiciConnection`, disable request timeouts by setting `timeout` to `0` +* If using the legacy `HttpConnection`, set `timeout` to a very large number (e.g. `86400000`, or one day)