From 369fb5dfdfd094874c04d74430f2757f32d167cd Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Wed, 16 Oct 2024 14:47:28 -0500 Subject: [PATCH 1/3] Add doc about timeout best practices --- docs/configuration.asciidoc | 3 ++- docs/timeout-best-practices.asciidoc | 10 ++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) create mode 100644 docs/timeout-best-practices.asciidoc 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/timeout-best-practices.asciidoc b/docs/timeout-best-practices.asciidoc new file mode 100644 index 000000000..84292fa4b --- /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) From eb64979e51257c41c079e68398841dc90a33a2aa Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Thu, 17 Oct 2024 11:39:45 -0500 Subject: [PATCH 2/3] Include new doc file --- docs/index.asciidoc | 1 + 1 file changed, 1 insertion(+) 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[] From d3c5ab61da4b220b1deaa13d46cf43252379b5d6 Mon Sep 17 00:00:00 2001 From: Josh Mock Date: Fri, 18 Oct 2024 10:40:37 -0500 Subject: [PATCH 3/3] Add missing slash --- docs/timeout-best-practices.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/timeout-best-practices.asciidoc b/docs/timeout-best-practices.asciidoc index 84292fa4b..0d2fb4772 100644 --- a/docs/timeout-best-practices.asciidoc +++ b/docs/timeout-best-practices.asciidoc @@ -1,7 +1,7 @@ [[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. +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: