Skip to content

Doc: Expand info for URL options and other minor fixes #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Doc: Expand info for URL options and other minor fixes #120

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d5857f5
Doc: Expand info for url option
karenzone Apr 30, 2021
e5b70a5
Tweaks
karenzone Apr 30, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 10 additions & 12 deletions docs/index.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,8 @@ output plugins.
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.
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 set only GET, HEAD, PUT, DELETE, OPTIONS, and TRACE requests will be retried.

[id="plugins-{type}s-{plugin}-cacert"]
===== `cacert`
Expand Down Expand Up @@ -299,10 +298,8 @@ If you'd like to use an HTTP proxy . This supports multiple configuration syntax
* Value type is <<number,number>>
* Default value is `60`

This module makes it easy to add a very fully configured HTTP client to logstash
based on [Manticore](https://github.com/cheald/manticore).
For an example of its usage see https://github.com/logstash-plugins/logstash-input-http_poller
Timeout (in seconds) for the entire request
This module helps you add a fully configured HTTP client to Logstash based on https://github.com/cheald/manticore[Manticore].
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section looks like it has been copy/pasted from here, and seems a bit out of place here in the middle of the configuration settings.

It can probably be replaced by

Timeout (in seconds) for the entire request

It would be nice to have configuration examples as in the http poller input docs

For an example, see {logstash-ref}/plugins-inputs-http_poller.html[input-http_poller] timeout (in seconds) for the entire request.

[id="plugins-{type}s-{plugin}-retry_failed"]
===== `retry_failed`
Expand All @@ -319,7 +316,6 @@ Set this to false if you don't want this output to retry failed requests
* 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).

[id="plugins-{type}s-{plugin}-retryable_codes"]
===== `retryable_codes`
Expand Down Expand Up @@ -369,7 +365,8 @@ Specify the truststore type here. One of `JKS` or `PKCS12`. Default is `JKS`
* Value type is <<string,string>>
* There is no default value for this setting.

URL to use
URL to use.
This option is {logstash-ref}/event-dependent-configuration.html#sprintf[sprintf]-compliant if your configuration does not use `json-batch` with the <<plugins-{type}s-{plugin}-content_type>> or <<plugins-{type}s-{plugin}-format>> options.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just the format option is relevant here -

Suggested change
This option is {logstash-ref}/event-dependent-configuration.html#sprintf[sprintf]-compliant if your configuration does not use `json-batch` with the <<plugins-{type}s-{plugin}-content_type>> or <<plugins-{type}s-{plugin}-format>> options.
This option is {logstash-ref}/event-dependent-configuration.html#sprintf[sprintf]-compliant if your configuration does not use the `json-batch` <<plugins-{type}s-{plugin}-format>> option.


[id="plugins-{type}s-{plugin}-validate_after_inactivity"]
===== `validate_after_inactivity`
Expand All @@ -380,12 +377,13 @@ URL to use
How long to wait before checking if the connection is stale before executing a request on a connection using keepalive.
You may want to set this lower, possibly to 0 if you get connection errors regularly
Quoting the Apache commons docs (this client is based Apache Commmons):
'Defines period of inactivity in milliseconds after which persistent connections must be re-validated prior to being leased to the consumer. Non-positive value passed to this method disables connection validation. This check helps detect connections that have become stale (half-closed) while kept inactive in the pool.'
See https://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/org/apache/http/impl/conn/PoolingHttpClientConnectionManager.html#setValidateAfterInactivity(int)[these docs for more info]
'Defines period of inactivity in milliseconds after which persistent connections must be re-validated prior to being leased to the consumer. Non-positive value passed to this method disables connection validation.
This check helps detect connections that have become stale (half-closed) while kept inactive in the pool.'
See the https://hc.apache.org/httpcomponents-client-5.0.x/[apache.org docs] for more info.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link here is a tricky one to get right - this amended link points to the top level docs for the http client rather than the specific entry that was initially linked to. The version is also later than the version we actually use - the library that we are referring to here is pulled in by the manticore gem, which is pulled in by the logstash-mixin-http_client gem...

The current,correct active link is https://hc.apache.org/httpcomponents-client-4.5.x/current/httpclient/apidocs/org/apache/http/impl/conn/PoolingHttpClientConnectionManager.html#getValidateAfterInactivity()




[id="plugins-{type}s-{plugin}-common-options"]
include::{include_path}/{type}.asciidoc[]

:default_codec!:
:default_codec!: