Merge pull request #130 from kaisecheng/doc_clarify_retry_loop

[Doc] clarify retry loop

Author: kaisecheng

CHANGELOG.md

@@ -1,3 +1,6 @@
+## 5.4.1
+  - Docs: Add retry policy description [#130](https://github.com/logstash-plugins/logstash-output-http/pull/130) 
+
 ## 5.4.0
   - Introduce retryable unknown exceptions for "connection reset by peer" and "timeout" [#127](https://github.com/logstash-plugins/logstash-output-http/pull/127)
 

docs/index.asciidoc

@@ -31,6 +31,40 @@ guaranteed!
 
 Beware, this gem does not yet support codecs. Please use the 'format' option for now.
 
+[id="plugins-{type}s-{plugin}-retry_policy"]
+==== Retry policy
+
+This output has two levels of retry: library and plugin.
+
+[id="plugins-{type}s-{plugin}-library_retry"]
+===== Library retry
+
+The library retry applies to IO related failures. 
+Non retriable errors include SSL related problems, unresolvable hosts,
+connection issues, and OS/JVM level interruptions happening during a request.
+
+The options for library retry are: 
+
+* <<plugins-{type}s-{plugin}-automatic_retries,`automatic_retries`>>. 
+Controls the number of times the plugin should retry after failures at the library level.
+* <<plugins-{type}s-{plugin}-retry_non_idempotent,`retry_non_idempotent`>>. 
+When set to `false`, GET, HEAD, PUT, DELETE, OPTIONS, and TRACE requests will be
+retried.
+
+[id="plugins-{type}s-{plugin}-plugin_retry"]
+===== Plugin retry
+
+The options for plugin level retry are: 
+
+* <<plugins-{type}s-{plugin}-retry_failed,`retry_failed`>>. 
+When set to `true`, the plugin retries indefinitely for HTTP error response codes defined
+in the <<plugins-{type}s-{plugin}-retryable_codes,`retryable_codes`>> option
+(429, 500, 502, 503, 504) and retryable exceptions (socket timeout/ error, DNS resolution failure and client protocol exception).
+* <<plugins-{type}s-{plugin}-retryable_codes,`retryable_codes`>>. 
+Sets http response codes that trigger a retry. 
+
+NOTE: The `retry_failed` option does not control the library level retry.
+
 [id="plugins-{type}s-{plugin}-options"]
 ==== Http Output Configuration Options
 
@@ -85,12 +119,10 @@ output plugins.
   * Value type is <<number,number>>
   * Default value is `1`
 
-How many times should the client retry a failing URL. We highly recommend NOT setting this value
-to zero if keepalive is enabled. Some servers incorrectly end keepalives early requiring a retry!
-Only IO related failures will be retried, such as connection timeouts and unreachable hosts.
-Valid but non 2xx HTTP responses will always be retried, regardless of the value of this setting,
-unless `retry_failed` is set.
-Note: if `retry_non_idempotent` is NOT set only GET, HEAD, PUT, DELETE, OPTIONS, and TRACE requests will be retried.
+How many times should the client retry a failing URL. We recommend setting this option
+to a value other than zero if the <<plugins-{type}s-{plugin}-keepalive,`keepalive` option>> is enabled. 
+Some servers incorrectly end keepalives early, requiring a retry.
+See <<plugins-{type}s-{plugin}-retry_policy,Retry Policy>> for more information.
 
 [id="plugins-{type}s-{plugin}-cacert"]
 ===== `cacert` 
@@ -311,24 +343,32 @@ Timeout (in seconds) for the entire request
   * Value type is <<boolean,boolean>>
   * Default value is `true`
 
-Set this to false if you don't want this output to retry failed requests
+Note that this option controls plugin-level retries only. 
+It has no affect on library-level retries. 
+
+Set this option to `false` if you want to disable infinite retries for HTTP error response codes defined in the <<plugins-{type}s-{plugin}-retryable_codes,`retryable_codes`>> or 
+retryable exceptions (Timeout, SocketException, ClientProtocolException, ResolutionFailure and SocketTimeout).
+See <<plugins-{type}s-{plugin}-retry_policy,Retry policy>> for more information.
 
 [id="plugins-{type}s-{plugin}-retry_non_idempotent"]
 ===== `retry_non_idempotent` 
 
   * Value type is <<boolean,boolean>>
   * Default value is `false`
 
-If `automatic_retries` is enabled this will cause non-idempotent HTTP verbs (such as POST) to be retried.
-This only affects connectivity related errors (see related `automatic_retries` setting).
+When this option is set to `false` and `automatic_retries` is enabled, GET, HEAD, PUT, DELETE, OPTIONS, and TRACE requests will be retried.
+
+When set to `true` and `automatic_retries` is enabled, this will cause non-idempotent HTTP verbs (such as POST) to be retried.
+See <<plugins-{type}s-{plugin}-retry_policy,Retry Policy>> for more information.
 
 [id="plugins-{type}s-{plugin}-retryable_codes"]
 ===== `retryable_codes` 
 
   * Value type is <<number,number>>
   * Default value is `[429, 500, 502, 503, 504]`
 
-If encountered as response codes this plugin will retry these requests
+If the plugin encounters these response codes, the plugin will retry indefinitely.
+See <<plugins-{type}s-{plugin}-retry_policy,Retry Policy>> for more information.
 
 [id="plugins-{type}s-{plugin}-socket_timeout"]
 ===== `socket_timeout` 

logstash-output-http.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name            = 'logstash-output-http'
-  s.version         = '5.4.0'
+  s.version         = '5.4.1'
   s.licenses        = ['Apache License (2.0)']
   s.summary         = "Sends events to a generic HTTP or HTTPS endpoint"
   s.description     = "This gem is a Logstash plugin required to be installed on top of the Logstash core pipeline using $LS_HOME/bin/logstash-plugin install gemname. This gem is not a stand-alone program"