|
@@ -1,88 +1,7 @@
|
|
|
[[ingest-user-agent]]
|
|
|
-=== Ingest user agent processor plugin
|
|
|
+=== Ingest `user_agent` Processor Plugin
|
|
|
|
|
|
-The `user_agent` processor extracts details from the user agent string a browser sends with its web requests.
|
|
|
-This processor adds this information by default under the `user_agent` field.
|
|
|
+The `user_agent` processor is no longer distributed as a plugin, but is now a module
|
|
|
+distributed by default with Elasticsearch. See
|
|
|
+{ref}/ingest-user-agent.html[Ingest `user_agent` processor] for more details.
|
|
|
|
|
|
-The ingest-user-agent 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.
|
|
|
-
|
|
|
-:plugin_name: ingest-user-agent
|
|
|
-include::install_remove.asciidoc[]
|
|
|
-
|
|
|
-[[using-ingest-user-agent]]
|
|
|
-==== Using the user_agent Processor in a Pipeline
|
|
|
-
|
|
|
-[[ingest-user-agent-options]]
|
|
|
-.User-agent options
|
|
|
-[options="header"]
|
|
|
-|======
|
|
|
-| Name | Required | Default | Description
|
|
|
-| `field` | yes | - | The field containing the user agent string.
|
|
|
-| `target_field` | no | user_agent | The field that will be filled with the user agent details.
|
|
|
-| `regex_file` | no | - | The name of the file in the `config/ingest-user-agent` 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-user-agent 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`.
|
|
|
-| `ignore_missing` | no | `false` | If `true` and `field` does not exist, the processor quietly exits without modifying the document
|
|
|
-|======
|
|
|
-
|
|
|
-Here is an example that adds the user agent details to the `user_agent` field based on the `agent` field:
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-PUT _ingest/pipeline/user_agent
|
|
|
-{
|
|
|
- "description" : "Add user agent information",
|
|
|
- "processors" : [
|
|
|
- {
|
|
|
- "user_agent" : {
|
|
|
- "field" : "agent"
|
|
|
- }
|
|
|
- }
|
|
|
- ]
|
|
|
-}
|
|
|
-PUT my_index/_doc/my_id?pipeline=user_agent
|
|
|
-{
|
|
|
- "agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36"
|
|
|
-}
|
|
|
-GET my_index/_doc/my_id
|
|
|
---------------------------------------------------
|
|
|
-// CONSOLE
|
|
|
-
|
|
|
-Which returns
|
|
|
-
|
|
|
-[source,js]
|
|
|
---------------------------------------------------
|
|
|
-{
|
|
|
- "found": true,
|
|
|
- "_index": "my_index",
|
|
|
- "_type": "_doc",
|
|
|
- "_id": "my_id",
|
|
|
- "_version": 1,
|
|
|
- "_seq_no": 22,
|
|
|
- "_primary_term": 1,
|
|
|
- "_source": {
|
|
|
- "agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
|
|
|
- "user_agent": {
|
|
|
- "name": "Chrome",
|
|
|
- "major": "51",
|
|
|
- "minor": "0",
|
|
|
- "patch": "2704",
|
|
|
- "os_name": "Mac OS X",
|
|
|
- "os": "Mac OS X 10.10.5",
|
|
|
- "os_major": "10",
|
|
|
- "os_minor": "10",
|
|
|
- "device": "Other"
|
|
|
- }
|
|
|
- }
|
|
|
-}
|
|
|
---------------------------------------------------
|
|
|
-// TESTRESPONSE[s/"_seq_no": \d+/"_seq_no" : $body._seq_no/ s/"_primary_term": 1/"_primary_term" : $body._primary_term/]
|
|
|
-
|
|
|
-===== 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-user-agent` 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-user-agent` is the `regexes.yaml` from uap-core: https://github.com/ua-parser/uap-core/blob/master/regexes.yaml
|