Elasticsearch input plugin

Authenticate using Elasticsearch API key. Note that this option also requires enabling the ssl_enabled option.

Format is id:api_key where id and api_key are as returned by the Elasticsearch Create API key API.

The SHA-256 fingerprint of an SSL Certificate Authority to trust, such as the autogenerated self-signed CA for an Elasticsearch cluster.

Cloud authentication string ("<username>:<password>" format) is an alternative for the user/password pair.

For more info, check out the Logstash-to-Cloud documentation.

Cloud ID, from the Elastic Cloud web console. If set hosts should not be used.

For more info, check out the Logstash-to-Cloud documentation.

The maximum amount of time, in seconds, to wait while establishing a connection to Elasticsearch. Connect timeouts tend to occur when Elasticsearch or an intermediate proxy is overloaded with requests and has exhausted its connection pool.

If set, include Elasticsearch document information such as index, type, and the id in the event.

It might be important to note, with regards to metadata, that if you’re ingesting documents with the intent to re-index them (or just update them) that the action option in the elasticsearch output wants to know how to handle those things. It can be dynamically assigned with a field added to the metadata.

Example

    input {
      elasticsearch {
        hosts => "es.production.mysite.org"
        index => "mydata-2018.09.*"
        query => '{ "query": { "query_string": { "query": "*" } } }'
        size => 500
        scroll => "5m"
        docinfo => true
        docinfo_target => "[@metadata][doc]"
      }
    }
    output {
      elasticsearch {
        index => "copy-of-production.%{[@metadata][doc][_index]}"
        document_type => "%{[@metadata][doc][_type]}"
        document_id => "%{[@metadata][doc][_id]}"
      }
    }

If set, you can use metadata information in the add_field common option.

Example

    input {
      elasticsearch {
        docinfo => true
        docinfo_target => "[@metadata][doc]"
        add_field => {
          identifier => "%{[@metadata][doc][_index]}:%{[@metadata][doc][_type]}:%{[@metadata][doc][_id]}"
        }
      }
    }

If document metadata storage is requested by enabling the docinfo option, this option lists the metadata fields to save in the current event. See Meta-Fields in the Elasticsearch documentation for more information.

If document metadata storage is requested by enabling the docinfo option, this option names the field under which to store the metadata fields as subfields.

Controls this plugin’s compatibility with the Elastic Common Schema (ECS).

List of one or more Elasticsearch hosts to use for querying. Each host can be either IP, HOST, IP:port, or HOST:port. The port defaults to 9200.

The index or alias to search. Check out Multi Indices documentation in the Elasticsearch documentation for info on referencing multiple indices.

The password to use together with the username in the user option when authenticating to the Elasticsearch server. If set to an empty string authentication will be disabled.

Set the address of a forward HTTP proxy. An empty string is treated as if proxy was not set, this is useful when using environment variables e.g. proxy => '${LS_PROXY:}'.

The query to be executed. Read the Elasticsearch query DSL documentation for more information.

When search_api resolves to search_after and the query does not specify sort, the default sort '{ "sort": { "_shard_doc": "asc" } }' will be added to the query. Please refer to the Elasticsearch search_after parameter to know more.

Which part of the result to transform into Logstash events when processing the response from the query. The default hits will generate one event per returned document (i.e. "hit"). When set to aggregations, a single Logstash event will be generated with the contents of the aggregations object of the query’s response. In this case the hits object will be ignored. The parameter size will be always be set to 0 regardless of the default or user-defined value set in this plugin.

The maximum amount of time, in seconds, for a single request to Elasticsearch. Request timeouts tend to occur when an individual page of data is very large, such as when it contains large-payload documents and/or the size has been specified as a large value.

The number of times to re-run the query after the first failure. If the query fails after all retries, it logs an error message. The default is 0 (no retry). This value should be equal to or greater than zero.

Schedule of when to periodically run statement, in Cron format for example: "* * * * *" (execute query every minute, on the minute)

There is no schedule by default. If no schedule is given, then the statement is run exactly once.

This parameter controls the keepalive time in seconds of the scrolling request and initiates the scrolling process. The timeout applies per round trip (i.e. between the previous scroll request, to the next).

With auto the plugin uses the search_after parameter for Elasticsearch version 8.0.0 or higher, otherwise the scroll API is used instead.

search_after uses point in time and sort value to search. The query requires at least one sort field, as described in the query parameter.

scroll uses scroll API to search, which is no longer recommended.

This allows you to set the maximum number of hits returned per scroll.

In some cases, it is possible to improve overall throughput by consuming multiple distinct slices of a query simultaneously using sliced scrolls, especially if the pipeline is spending significant time waiting on Elasticsearch to provide results.

If set, the slices parameter tells the plugin how many slices to divide the work into, and will produce events from the slices in parallel until all of them are done scrolling.

If the slices parameter is left unset, the plugin will not inject slice instructions into the query.

SSL certificate to use to authenticate the client. This certificate should be an OpenSSL-style X.509 certificate file.

The .cer or .pem files to validate the server’s certificate.

The list of cipher suites to use, listed by priorities. Supported cipher suites vary depending on the Java and protocol versions.

Enable SSL/TLS secured communication to Elasticsearch cluster. Leaving this unspecified will use whatever scheme is specified in the URLs listed in hosts or extracted from the cloud_id. If no explicit protocol is specified plain HTTP will be used.

OpenSSL-style RSA private key that corresponds to the ssl_certificate.

Set the keystore password

The keystore used to present a certificate to the server. It can be either .jks or .p12

The format of the keystore file. It must be either jks or pkcs12.

List of allowed SSL/TLS versions to use when establishing a connection to the Elasticsearch cluster.

For Java 8 'TLSv1.3' is supported only since 8u262 (AdoptOpenJDK), but requires that you set the LS_JAVA_OPTS="-Djdk.tls.client.protocols=TLSv1.3" system property in Logstash.

Set the truststore password.

The truststore to validate the server’s certificate. It can be either .jks or .p12.

The format of the truststore file. It must be either jks or pkcs12.

Defines how to verify the certificates presented by another party in the TLS connection:

full validates that the server certificate has an issue date that’s within the not_before and not_after dates; chains to a trusted Certificate Authority (CA), and has a hostname or IP address that matches the names within the certificate.

none performs no certificate validation.

The maximum amount of time, in seconds, to wait on an incomplete response from Elasticsearch while no additional data has been appended. Socket timeouts usually occur while waiting for the first byte of a response, such as when executing a particularly complex query.

Without a target, events are created from each hit’s _source at the root level. When the target is set to a field reference, the _source of the hit is placed in the target field instead.

This option can be useful to avoid populating unknown fields when a downstream schema such as ECS is enforced. It is also possible to target an entry in the event’s metadata, which will be available during event processing but not exported to your outputs (e.g., target \=> "[@metadata][_source]").

The username to use together with the password in the password option when authenticating to the Elasticsearch server. If set to an empty string authentication will be disabled.

SSL Certificate Authority file in PEM encoded format, must also include any chain certificates as necessary.

If enabled, SSL will be used when communicating with the Elasticsearch server (i.e. HTTPS will be used instead of plain HTTP).

Option to validate the server’s certificate. Disabling this severely compromises security. When certificate validation is disabled, this plugin implicitly trusts the machine resolved at the given address without validating its proof-of-identity. In this scenario, the plugin can transmit credentials to or process data from an untrustworthy man-in-the-middle or other compromised infrastructure. More information on the importance of certificate verification: https://www.cs.utexas.edu/~shmat/shmat_ccs12.pdf.

Add a field to an event

The codec used for input data. Input codecs are a convenient method for decoding your data before it enters the input, without needing a separate filter in your Logstash pipeline.

Disable or enable metric logging for this specific plugin instance by default we record all the metrics we can, but you can disable metrics collection for a specific plugin.

Add a unique ID to the plugin configuration. If no ID is specified, Logstash will generate one. It is strongly recommended to set this ID in your configuration. This is particularly useful when you have two or more plugins of the same type, for example, if you have 2 elasticsearch inputs. Adding a named ID in this case will help in monitoring Logstash when using the monitoring APIs.

input {
  elasticsearch {
    id => "my_plugin_id"
  }
}

Add any number of arbitrary tags to your event.

This can help with processing later.

Add a type field to all events handled by this input.

Types are used mainly for filter activation.

The type is stored as part of the event itself, so you can also use the type to search for it in Kibana.

If you try to set a type on an event that already has one (for example when you send an event from a shipper to an indexer) then a new input will not override the existing type. A type set at the shipper stays with that event for its life even when sent to another Logstash server.