omelasticsearch: Elasticsearch Output Module

Server

An array of Elasticsearch servers in the specified format. If no scheme is specified, it will be chosen according to usehttps. If no port is specified, serverport will be used. Defaults to “localhost”.

Requests to Elasticsearch will be load-balanced between all servers in round-robin fashion.

Examples:
     server="localhost:9200"
     server=["elasticsearch1", "elasticsearch2"]

Serverport

Default HTTP port to use to connect to Elasticsearch if none is specified on a server. Defaults to 9200

HealthCheckTimeout

Specifies the number of milliseconds to wait for a successful health check on a server. Before trying to submit events to Elasticsearch, rsyslog will execute an HTTP HEAD to /_cat/health and expect an HTTP OK within this timeframe. Defaults to 3500.

Note, the health check is verifying connectivity only, not the state of the Elasticsearch cluster.

esVersion.major

ElasticSearch is notoriously bad at maintaining backwards compatibility. For this reason, the setting can be used to configure the server’s major version number (e.g. 7, 8, …). As far as we know breaking changes only happen with major version changes. As of now, only value 8 triggers API changes. All other values select pre-version-8 API usage.

searchIndex

Elasticsearch index to send your logs to. Defaults to “system”

dynSearchIndex

Whether the string provided for searchIndex should be taken as a rsyslog template. Defaults to “off”, which means the index name will be taken literally. Otherwise, it will look for a template with that name, and the resulting string will be the index name. For example, let’s assume you define a template named “date-days” containing “%timereported:1:10:date-rfc3339%”. Then, with dynSearchIndex=”on”, if you say searchIndex=”date-days”, each log will be sent to and index named after the first 10 characters of the timestamp, like “2013-03-22”.

searchType

Elasticsearch type to send your index to. Defaults to “events”. Setting this parameter to an empty string will cause the type to be omitted, which is required since Elasticsearch 7.0. See Elasticsearch documentation for more information.

dynSearchType

Like dynSearchIndex, it allows you to specify a rsyslog template for searchType, instead of a static string.

pipelineName

The ingest node pipeline name to be included in the request. This allows pre processing of events before indexing them. By default, events are not send to a pipeline.

dynPipelineName

Like dynSearchIndex, it allows you to specify a rsyslog template for pipelineName, instead of a static string.

skipPipelineIfEmpty

When POST’ing a document, Elasticsearch does not allow an empty pipeline parameter value. If boolean option skipPipelineIfEmpty is set to “on”, the pipeline parameter won’t be posted. Default is “off”.

asyncrepl

No longer supported as ElasticSearch no longer supports it.

usehttps

Default scheme to use when sending events to Elasticsearch if none is specified on a server. Good for when you have Elasticsearch behind Apache or something else that can add HTTPS. Note that if you have a self-signed certificate, you’d need to install it first. This is done by copying the certificate to a trusted path and then running update-ca-certificates. That trusted path is typically /usr/local/share/ca-certificates but check the man page of update-ca-certificates for the default path of your distro

timeout

How long Elasticsearch will wait for a primary shard to be available for indexing your log before sending back an error. Defaults to “1m”.

indexTimeout

Specifies the number of milliseconds to wait for a successful log indexing request on a server. By default there is no timeout.

template

This is the JSON document that will be indexed in Elasticsearch. The resulting string needs to be a valid JSON, otherwise Elasticsearch will return an error. Defaults to:

$template StdJSONFmt, "{\"message\":\"%msg:::json%\",\"fromhost\":\"%HOSTNAME:::json%\",\"facility\":\"%syslogfacility-text%\",\"priority\":\"%syslogpriority-text%\",\"timereported\":\"%timereported:::date-rfc3339%\",\"timegenerated\":\"%timegenerated:::date-rfc3339%\"}"

Which will produce this sort of documents (pretty-printed here for readability):

{
    "message": " this is a test message",
    "fromhost": "test-host",
    "facility": "user",
    "priority": "info",
    "timereported": "2013-03-12T18:05:01.344864+02:00",
    "timegenerated": "2013-03-12T18:05:01.344864+02:00"
}

Another template, FullJSONFmt, is available that includes more fields including programname, PROCID (usually the process ID), and MSGID.

bulkmode

The default “off” setting means logs are shipped one by one. Each in its own HTTP request, using the Index API. Set it to “on” and it will use Elasticsearch’s Bulk API to send multiple logs in the same request. The maximum number of logs sent in a single bulk request depends on your maxbytes and queue settings - usually limited by the dequeue batch size. More information about queues can be found here.

maxbytes

When shipping logs with bulkmode on, maxbytes specifies the maximum size of the request body sent to Elasticsearch. Logs are batched until either the buffer reaches maxbytes or the dequeue batch size is reached. In order to ensure Elasticsearch does not reject requests due to content length, verify this value is set according to the http.max_content_length setting in Elasticsearch. Defaults to 100m.

parent

Specifying a string here will index your logs with that string the parent ID of those logs. Please note that you need to define the parent field in your mapping for that to work. By default, logs are indexed without a parent.

dynParent

Using the same parent for all the logs sent in the same action is quite unlikely. So you’d probably want to turn this “on” and specify a rsyslog template that will provide meaningful parent IDs for your logs.

uid

If you have basic HTTP authentication deployed (eg through the elasticsearch-basic plugin), you can specify your user-name here.

pwd

Password for basic authentication.

errorFile

If specified, records failed in bulk mode are written to this file, including their error cause. Rsyslog itself does not process the file any more, but the idea behind that mechanism is that the user can create a script to periodically inspect the error file and react appropriately. As the complete request is included, it is possible to simply resubmit messages from that script.

Please note: when rsyslog has problems connecting to elasticsearch, a general error is assumed and the submit is retried. However, if we receive negative responses during batch processing, we assume an error in the data itself (like a mandatory field is not filled in, a format error or something along those lines). Such errors cannot be solved by simply resubmitting the record. As such, they are written to the error file so that the user (script) can examine them and act appropriately. Note that e.g. after search index reconfiguration (e.g. dropping the mandatory attribute) a resubmit may be successful.

tls.cacert

This is the full path and file name of the file containing the CA cert for the CA that issued the Elasticsearch server cert. This file is in PEM format. For example: /etc/rsyslog.d/es-ca.crt

tls.mycert

This is the full path and file name of the file containing the client cert for doing client cert auth against Elasticsearch. This file is in PEM format. For example: /etc/rsyslog.d/es-client-cert.pem

tls.myprivkey

This is the full path and file name of the file containing the private key corresponding to the cert tls.mycert used for doing client cert auth against Elasticsearch. This file is in PEM format, and must be unencrypted, so take care to secure it properly. For example: /etc/rsyslog.d/es-client-key.pem

allowunsignedcerts

If “on”, this will set the curl CURLOPT_SSL_VERIFYPEER option to 0. You are strongly discouraged to set this to “on”. It is primarily useful only for debugging or testing.

skipverifyhost

If “on”, this will set the curl CURLOPT_SSL_VERIFYHOST option to 0. You are strongly discouraged to set this to “on”. It is primarily useful only for debugging or testing.

bulkid

This is the unique id to assign to the record. The bulk part is misleading - this can be used in both bulk mode bulkmode or in index (record at a time) mode. Although you can specify a static value for this parameter, you will almost always want to specify a template for the value of this parameter, and set dynbulkid=”on” dynbulkid. NOTE: you must use bulkid and dynbulkid in order to use writeoperation=”create” writeoperation.

dynbulkid

If this parameter is set to “on”, then the bulkid parameter bulkid specifies a template to use to generate the unique id value to assign to the record. If using bulkid you will almost always want to set this parameter to “on” to assign a different unique id value to each record. NOTE: you must use bulkid and dynbulkid in order to use writeoperation=”create” writeoperation.

writeoperation

The value of this parameter is either “index” (the default) or “create”. If “create” is used, this means the bulk action/operation will be create - create a document only if the document does not already exist. The record must have a unique id in order to use create. See bulkid and dynbulkid. See Example 4 for an example.

retryfailures

If this parameter is set to “on”, then the module will look for an “errors”:true in the bulk index response. If found, each element in the response will be parsed to look for errors, since a bulk request may have some records which are successful and some which are failures. Failed requests will be converted back into records and resubmitted back to rsyslog for reprocessing. Each failed request will be resubmitted with a local variable called $.omes. This is a hash consisting of the fields from the metadata header in the original request, and the fields from the response. If the same field is in the request and response, the value from the field in the request will be used, to facilitate retries that want to send the exact same request, and want to know exactly what was sent. See below Example 5 for an example of how retry processing works. NOTE The retried record will be resubmitted at the “top” of your processing pipeline. If your processing pipeline is not idempotent (that is, your processing pipeline expects “raw” records), then you can specify a ruleset to redirect retries to. See retryruleset below.

$.omes fields:

• writeoperation - the operation used to submit the request - for rsyslog omelasticsearch this currently means either “index” or “create”

• status - the HTTP status code - typically an error will have a 4xx or 5xx code - of particular note is 429 - this means Elasticsearch was unable to process this bulk record request due to a temporary condition e.g. the bulk index thread pool queue is full, and rsyslog should retry the operation.

• _index, _type, _id, pipeline, _parent - the metadata associated with the request - not all of these fields will be present with every request - for example, if you do not use “pipelinename” or “dynpipelinename”, there will be no $.omes!pipeline field.

• error - a hash containing one or more, possibly nested, fields containing more detailed information about a failure. Typically there will be fields $.omes!error!type (a keyword) and $.omes!error!reason (a longer string) with more detailed information about the rejection. NOTE: The format is apparently not described in great detail, so code must not make any assumption about the availability of error or any specific sub-field.

There may be other fields too - the code just copies everything in the response. Here is an example of a detailed error response, in JSON format, from Elasticsearch 5.6.9:

{"omes":
  {"writeoperation": "create",
   "_index": "rsyslog_testbench",
   "_type": "test-type",
   "_id": "92BE7AF79CD44305914C7658AF846A08",
   "status": 400,
   "error":
     {"type": "mapper_parsing_exception",
      "reason": "failed to parse [msgnum]",
      "caused_by":
        {"type": "number_format_exception",
         "reason": "For input string: \"x00000025\""}}}}

Reference: https://www.elastic.co/guide/en/elasticsearch/guide/current/bulk.html#bulk

retryruleset

If retryfailures is not “on” (retryfailures) then this parameter has no effect. This parameter specifies the name of a ruleset to use to route retries. This is useful if you do not want retried messages to be processed starting from the top of your processing pipeline, or if you have multiple outputs but do not want to send retried Elasticsearch failures to all of your outputs, and you do not want to clutter your processing pipeline with a lot of conditionals. See below Example 5 for an example of how retry processing works.

ratelimit.interval

If retryfailures is not “on” (retryfailures) then this parameter has no effect. Specifies the interval in seconds onto which rate-limiting is to be applied. If more than ratelimit.burst messages are read during that interval, further messages up to the end of the interval are discarded. The number of messages discarded is emitted at the end of the interval (if there were any discards). Setting this to value zero turns off ratelimiting.

ratelimit.burst

If retryfailures is not “on” (retryfailures) then this parameter has no effect. Specifies the maximum number of messages that can be emitted within the ratelimit.interval interval. For further information, see description there.

rebindinterval

This parameter tells omelasticsearch to close the connection and reconnect to Elasticsearch after this many operations have been submitted. The default value -1 means that omelasticsearch will not reconnect. A value greater than -1 tells omelasticsearch, after this many operations have been submitted to Elasticsearch, to drop the connection and establish a new connection. This is useful when rsyslog connects to multiple Elasticsearch nodes through a router or load balancer, and you need to periodically drop and reestablish connections to help the router balance the connections. Use the counter rebinds to monitor the number of times this has happened.