75 lines
3.4 KiB
Plaintext
75 lines
3.4 KiB
Plaintext
|
[[ingest-useragent]]
|
||
|
|
=== Ingest Useragent Processor Plugin
|
||
|
|
|
||
|
|
The Useragent processor extracts details from the user agent string a browser sends with its web requests.
|
||
|
|
This processor adds this information by default under the `useragent` field.
|
||
|
|
|
||
|
|
The ingest-useragent plugin ships by default with the regexes.yaml made available by uap-java with an Apache 2.0 license. For more details see https://github.com/ua-parser/uap-core.
|
||
|
|
|
||
|
|
[[ingest-useragent-install]]
|
||
|
|
[float]
|
||
|
|
==== Installation
|
||
|
|
|
||
|
|
This plugin can be installed using the plugin manager:
|
||
|
|
|
||
|
|
[source,sh]
|
||
|
|
----------------------------------------------------------------
|
||
|
|
sudo bin/elasticsearch-plugin install ingest-useragent
|
||
|
|
----------------------------------------------------------------
|
||
|
|
|
||
|
|
The plugin must be installed on every node in the cluster, and each node must
|
||
|
|
be restarted after installation.
|
||
|
|
|
||
|
|
[[ingest-useragent-remove]]
|
||
|
|
[float]
|
||
|
|
==== Removal
|
||
|
|
|
||
|
|
The plugin can be removed with the following command:
|
||
|
|
|
||
|
|
[source,sh]
|
||
|
|
----------------------------------------------------------------
|
||
|
|
sudo bin/elasticsearch-plugin remove ingest-useragent
|
||
|
|
----------------------------------------------------------------
|
||
|
|
|
||
|
|
The node must be stopped before removing the plugin.
|
||
|
|
|
||
|
|
[[using-ingest-useragent]]
|
||
|
|
==== Using the Useragent Processor in a Pipeline
|
||
|
|
|
||
|
|
[[ingest-useragent-options]]
|
||
|
|
.Useragent options
|
||
|
|
[options="header"]
|
||
|
|
|======
|
||
|
|
| Name | Required | Default | Description
|
||
|
|
| `field` | yes | - | The field containing the user agent string.
|
||
|
|
| `target_field` | no | useragent | The field that will be filled with the user agent details.
|
||
|
|
| `regex_file` | no | - | The name of the file in the `config/ingest-useragent` directory containing the regular expressions for parsing the user agent string. Both the directory and the file have to be created before starting Elasticsearch. If not specified, ingest-useragent will use the regexes.yaml from uap-core it ships with (see below).
|
||
|
|
| `properties` | no | [`name`, `major`, `minor`, `patch`, `build`, `os`, `os_name`, `os_major`, `os_minor`, `device`] | Controls what properties are added to `target_field`.
|
||
|
|
|======
|
||
|
|
|
||
|
|
Here is an example that adds the user agent details to the `useragent` field based on the `agent` field:
|
||
|
|
|
||
|
|
[source,js]
|
||
|
|
--------------------------------------------------
|
||
|
|
{
|
||
|
|
"description" : "...",
|
||
|
|
"processors" : [
|
||
|
|
{
|
||
|
|
"useragent" : {
|
||
|
|
"field" : "agent"
|
||
|
|
}
|
||
|
|
}
|
||
|
|
]
|
||
|
|
}
|
||
|
|
--------------------------------------------------
|
||
|
|
|
||
|
|
===== Using a custom regex file
|
||
|
|
To use a custom regex file for parsing the user agents, that file has to be put into the `config/ingest-useragent` directory and
|
||
|
|
has to have a `.yaml` filename extension. The file has to be present at node startup, any changes to it or any new files added
|
||
|
|
while the node is running will not have any effect.
|
||
|
|
|
||
|
|
In practice, it will make most sense for any custom regex file to be a variant of the default file, either a more recent version
|
||
|
|
or a customised version.
|
||
|
|
|
||
|
|
The default file included in `ingest-useragent` is the `regexes.yaml` from uap-core: https://github.com/ua-parser/uap-core/blob/master/regexes.yaml
|