omelasticsearch: Elasticsearch Output Module¶
Module Name: |
omelasticsearch |
Author: |
Purpose¶
This module provides native support for logging to Elasticsearch.
Notable Features¶
Configuration Parameters¶
Note
Parameter names are case-insensitive; CamelCase is recommended for readability.
Note
This module supports action parameters, only.
Action Parameters¶
Parameter |
Summary |
---|---|
List of Elasticsearch servers to send events to. |
|
Default port used when server URLs omit a port. |
|
Milliseconds to wait for an HTTP health check before sending events. |
|
Elasticsearch major version used to select compatible APIs. |
|
Elasticsearch index where events are written. |
|
Treat searchIndex as a template name instead of a literal. |
|
Elasticsearch type to use; empty string omits the type. |
|
Treat searchType as a template name. |
|
Ingest pipeline to run before indexing. |
|
Treat pipelineName as a template name. |
|
Omit the pipeline parameter when pipelineName expands to an empty string. |
|
Deprecated option formerly enabling asynchronous replication. |
|
Default scheme for servers missing one. |
|
How long Elasticsearch waits for a primary shard before failing. |
|
Milliseconds to wait for an indexing request to complete. |
|
Template used to render the JSON document sent to Elasticsearch. |
|
Use the Elasticsearch Bulk API to send batched events. |
|
Maximum size of a bulk request body when bulkmode is enabled. |
|
Parent document ID assigned to indexed events. |
|
Treat parent as a template for per-record parent IDs. |
|
User name for basic HTTP authentication. |
|
Password for basic HTTP authentication. |
|
File that receives records rejected during bulk mode. |
|
CA certificate file used to verify the Elasticsearch server. |
|
Client certificate for mutual TLS authentication. |
|
Unencrypted private key for tls.mycert. |
|
Disable TLS peer verification (insecure, for testing only). |
|
Disable TLS host name verification (insecure, for testing). |
|
Unique identifier assigned to each record. |
|
Treat bulkid as a template that generates per-record IDs. |
|
Bulk action type: index (default) or create to avoid overwrites. |
|
Resubmit failed bulk items back into rsyslog for retry. |
|
Ruleset used when processing retried records. |
|
Seconds over which retry rate limiting is calculated. |
|
Maximum messages allowed in a rate-limit interval. |
|
Operations after which to reconnect; -1 disables periodic reconnect. |
Statistic Counter¶
This plugin maintains global statistics, which accumulate all action instances. The statistic is named “omelasticsearch”. Parameters are:
submitted - number of messages submitted for processing (with both success and error result)
fail.httprequests - the number of times an HTTP request failed. Note that a single HTTP request may be used to submit multiple messages, so this number may be (much) lower than fail.http.
fail.http - number of message failures due to connection like-problems (things like remote server down, broken link etc)
fail.es - number of failures due to elasticsearch error reply; Note that this counter does NOT count the number of failed messages but the number of times a failure occurred (a potentially much smaller number). Counting messages would be quite performance-intense and is thus not done.
The following counters are available when retryfailures=”on” is used:
response.success - number of records successfully sent in bulk index requests - counts the number of successful responses
response.bad - number of times omelasticsearch received a response in a bulk index response that was unrecognized or unable to be parsed. This may indicate that omelasticsearch is attempting to communicate with a version of Elasticsearch that is incompatible, or is otherwise sending back data in the response that cannot be handled
response.duplicate - number of records in the bulk index request that were duplicates of already existing records - this will only be reported if using writeoperation=”create” and bulkid to assign each record a unique ID
response.badargument - number of times omelasticsearch received a response that had a status indicating omelasticsearch sent bad data to Elasticsearch. For example, status 400 and an error message indicating omelasticsearch attempted to store a non-numeric string value in a numeric field.
response.bulkrejection - number of times omelasticsearch received a response that had a status indicating Elasticsearch was unable to process the record at this time - status 429. The record can be retried.
response.other - number of times omelasticsearch received a response not recognized as one of the above responses, typically some other 4xx or 5xx HTTP status.
rebinds - if using rebindinterval this will be the number of times omelasticsearch has reconnected to Elasticsearch
The fail.httprequests and fail.http counters reflect only failures that omelasticsearch detected. Once it detects problems, it (usually, depends on circumstances) tell the rsyslog core that it wants to be suspended until the situation clears (this is a requirement for rsyslog output modules). Once it is suspended, it does NOT receive any further messages. Depending on the user configuration, messages will be lost during this period. Those lost messages will NOT be counted by impstats (as it does not see them).
Note that some previous (pre 7.4.5) versions of this plugin had different counters. These were experimental and confusing. The only ones really used were “submits”, which were the number of successfully processed messages and “connfail” which were equivalent to “failed.http”.
How Retries Are Handled¶
When using retryfailures=”on” (retryfailures), the original Message object (that is, the original smsg_t *msg object) is not available. This means none of the metadata associated with that object, such as various timestamps, hosts/ip addresses, etc. are not available for the retry operation. The only thing available are the metadata header (_index, _type, _id, pipeline, _parent) and original JSON string sent in the original request, and whatever data is returned in the error response. All of these are made available in the $.omes fields. If the same field name exists in the request metadata and the response, the field from the request will be used, in order to facilitate retrying the exact same request. For the message to retry, the code will take the original JSON string and parse it back into an internal Message object. This means you may need to use a different template to output messages for your retry ruleset. For example, if you used the following template to format the Elasticsearch message for the initial submission:
template(name="es_output_template"
type="list"
option.json="on") {
constant(value="{")
constant(value="\"timestamp\":\"") property(name="timereported" dateFormat="rfc3339")
constant(value="\",\"message\":\"") property(name="msg")
constant(value="\",\"host\":\"") property(name="hostname")
constant(value="\",\"severity\":\"") property(name="syslogseverity-text")
constant(value="\",\"facility\":\"") property(name="syslogfacility-text")
constant(value="\",\"syslogtag\":\"") property(name="syslogtag")
constant(value="\"}")
}
You would have to use a different template for the retry, since none of the timereported, msg, etc. fields will have the same values for the retry as for the initial try.
Same with the other omelasticsearch parameters which can be constructed with templates, such as “dynpipelinename”, “dynsearchindex”, “dynsearchtype”, “dynparent”, and “dynbulkid”. For example, if you generate the _id to use in the request, you will want to reuse the same _id for each subsequent retry:
template(name="id-template" type="string" string="%$.es_msg_id%")
if strlen($.omes!_id) > 0 then {
set $.es_msg_id = $.omes!_id;
} else {
# NOTE: depends on rsyslog being compiled with --enable-uuid
set $.es_msg_id = $uuid;
}
action(type="omelasticsearch" bulkid="id-template" ...)
That is, if this is a retry, $.omes!_id will be set, so use that value for the bulk id for this record, otherwise, generate a new one with $uuid. Note that the template uses the temporary variable $.es_msg_id which must be set each time, to either $.omes!_id or $uuid.
The rawmsg field is a special case. If the original request had a field called message, then when constructing the new message from the original to retry, the rawmsg message property will be set to the value of the message field. Otherwise, the rawmsg property value will be set to the entire original request - the data part, not the metadata. In previous versions, without the message field, the rawmsg property was set to the value of the data plus the Elasticsearch metadata, which caused problems with retries. See rsyslog issue 3573
Examples¶
Example 1¶
The following sample does the following:
loads the omelasticsearch module
outputs all logs to Elasticsearch using the default settings
module(load="omelasticsearch")
action(type="omelasticsearch")
Example 2¶
The following sample does the following:
loads the omelasticsearch module
outputs all logs to Elasticsearch using the full JSON logging template including program name
module(load="omelasticsearch")
action(type="omelasticsearch" template="FullJSONFmt")
Example 3¶
The following sample does the following:
loads the omelasticsearch module
defines a template that will make the JSON contain the following properties
RFC-3339 timestamp when the event was generated
the message part of the event
hostname of the system that generated the message
severity of the event, as a string
facility, as a string
the tag of the event
outputs to Elasticsearch with the following settings
host name of the server is myserver.local
port is 9200
JSON docs will look as defined in the template above
index will be “test-index”
type will be “test-type”
activate bulk mode. For that to work effectively, we use an in-memory queue that can hold up to 5000 events. The maximum bulk size will be 300
retry indefinitely if the HTTP request failed (eg: if the target server is down)
module(load="omelasticsearch")
template(name="testTemplate"
type="list"
option.json="on") {
constant(value="{")
constant(value="\"timestamp\":\"") property(name="timereported" dateFormat="rfc3339")
constant(value="\",\"message\":\"") property(name="msg")
constant(value="\",\"host\":\"") property(name="hostname")
constant(value="\",\"severity\":\"") property(name="syslogseverity-text")
constant(value="\",\"facility\":\"") property(name="syslogfacility-text")
constant(value="\",\"syslogtag\":\"") property(name="syslogtag")
constant(value="\"}")
}
action(type="omelasticsearch"
server="myserver.local"
serverport="9200"
template="testTemplate"
searchIndex="test-index"
searchType="test-type"
bulkmode="on"
maxbytes="100m"
queue.type="linkedlist"
queue.size="5000"
queue.dequeuebatchsize="300"
action.resumeretrycount="-1")
Example 4¶
The following sample shows how to use writeoperation with dynbulkid and bulkid. For simplicity, it assumes rsyslog has been built with –enable-libuuid which provides the uuid property for each record:
module(load="omelasticsearch")
set $!es_record_id = $uuid;
template(name="bulkid-template" type="list") { property(name="$!es_record_id") }
action(type="omelasticsearch"
...
bulkmode="on"
bulkid="bulkid-template"
dynbulkid="on"
writeoperation="create")
Example 5¶
The following sample shows how to use retryfailures to process, discard, or retry failed operations. This uses writeoperation=”create” with a unique bulkid so that we can check for and discard duplicate messages as successful. The try_es ruleset is used both for the initial attempt and any subsequent retries. The code in the ruleset assumes that if $.omes!status is set and is non-zero, this is a retry for a previously failed operation. If the status was successful, or Elasticsearch said this was a duplicate, the record is already in Elasticsearch, so we can drop the record. If there was some error processing the response e.g. Elasticsearch sent a response formatted in some way that we did not know how to process, then submit the record to the error_es ruleset. If the response was a “hard” error like 400, then submit the record to the error_es ruleset. In any other case, such as a status 429 or 5xx, the record will be resubmitted to Elasticsearch. In the example, the error_es ruleset just dumps the records to a file.
module(load="omelasticsearch")
module(load="omfile")
template(name="bulkid-template" type="list") { property(name="$.es_record_id") }
ruleset(name="error_es") {
action(type="omfile" template="RSYSLOG_DebugFormat" file="es-bulk-errors.log")
}
ruleset(name="try_es") {
if strlen($.omes!status) > 0 then {
# retry case
if ($.omes!status == 200) or ($.omes!status == 201) or (($.omes!status == 409) and ($.omes!writeoperation == "create")) then {
stop # successful
}
if ($.omes!writeoperation == "unknown") or (strlen($.omes!error!type) == 0) or (strlen($.omes!error!reason) == 0) then {
call error_es
stop
}
if ($.omes!status == 400) or ($.omes!status < 200) then {
call error_es
stop
}
# else fall through to retry operation
}
if strlen($.omes!_id) > 0 then {
set $.es_record_id = $.omes!_id;
} else {
# NOTE: depends on rsyslog being compiled with --enable-uuid
set $.es_record_id = $uuid;
}
action(type="omelasticsearch"
...
bulkmode="on"
bulkid="bulkid-template"
dynbulkid="on"
writeoperation="create"
retryfailures="on"
retryruleset="try_es")
}
call try_es
Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project
Contributing: Source & docs: rsyslog source project
© 2008–2025 Rainer Gerhards and others. Licensed under the Apache License 2.0.