User agent processor

The user_agent processor is used to extract information from the user agent string, such as the browser, device, and operating system used by the client. The user_agent processor is particularly useful for analyzing user behavior and identifying trends based on user devices, operating systems, and browsers. It can also be helpful for troubleshooting issues specific to certain user agent configurations.

The following is the syntax for the user_agent processor:

  1. {
  2.   "processor": {
  3.     "user_agent": {
  4.       "field": "user_agent",
  5.       "target_field": "user_agent_info"
  6.     }
  7.   }
  8. }

copy

Configuration parameters

The following table lists the required and optional parameters for the user_agent processor.

ParameterRequired/OptionalDescription
fieldRequiredThe field containing the user agent string.
target_fieldOptionalThe field in which to store the extracted user agent information. If not specified, then the information is stored in the user_agent field.
ignore_missingOptionalSpecifies whether the processor should ignore documents that do not contain the specified field. If set to true, the processor does not modify the document if the field does not exist. Default is false.
regex_fileOptionalA file containing regular expression patterns used to parse the user agent string. This file should be located in the config/ingest-user-agent directory within the OpenSearch package. If not specified, then the default file regexes.yaml is used.
propertiesOptionalA list of properties to be extracted from the user agent string and added to the target_field. If not specified, then the default properties are name, major, minor, patch, build, os, os_name, os_major, os_minor, and device.
descriptionOptionalA brief description of the processor.
ifOptionalA condition for running the processor.
ignore_failureOptionalSpecifies whether the processor continues to run even if it encounters an error. If set to true, then failures are ignored. Default is false.
on_failureOptionalA list of processors to run if the processor fails.
tagOptionalAn identifier tag for the processor. Useful for debugging in order to distinguish between processors of the same type.

Using the processor

Follow these steps to use the processor in a pipeline.

Step 1: Create a pipeline

The following query creates a pipeline named user_agent_pipeline that uses the user_agent processor to extract user agent information:

  1. PUT _ingest/pipeline/user_agent_pipeline
  2. {
  3.   "description": "User agent pipeline",
  4.   "processors": [
  5.     {
  6.       "user_agent": {
  7.         "field": "user_agent",
  8.         "target_field": "user_agent_info"
  9.       }
  10.     }
  11.   ]
  12. }

copy

Step 2 (Optional): Test the pipeline

It is recommended that you test your pipeline before you ingest documents.

To test the pipeline, run the following query:

  1. POST _ingest/pipeline/user_agent_pipeline/_simulate
  2. {
  3.   "pipeline": "user_agent_pipeline",
  4.   "docs": [
  5.     {
  6.       "_source": {
  7.         "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3"
  8.       }
  9.     }
  10.   ]
  11. }

copy

Response

The following example response confirms that the pipeline is working as expected:

  1. {
  2.   "docs": [
  3.     {
  4.       "doc": {
  5.         "_index": "_index",
  6.         "_id": "_id",
  7.         "_source": {
  8.           "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
  9.           "user_agent_info": {
  10.             "name": "Chrome",
  11.             "original": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
  12.             "os": {
  13.               "name": "Windows",
  14.               "version": "10",
  15.               "full": "Windows 10"
  16.             },
  17.             "device": {
  18.               "name": "Other"
  19.             },
  20.             "version": "58.0.3029.110"
  21.           }
  22.         },
  23.         "_ingest": {
  24.           "timestamp": "2024-04-25T21:41:28.744407425Z"
  25.         }
  26.       }
  27.     }
  28.   ]
  29. }

Step 3: Ingest a document

The following query ingests a document into an index named testindex1:

  1. PUT testindex1/_doc/1?pipeline=user_agent_pipeline
  2. {
  3.   "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36"
  4. }

copy

Response

The preceding request parses the user_agent string into its components and indexes the document, along with all documents containing those components, into the testindex1 index, as shown in the following response:

  1. {
  2.   "_index": "testindex1",
  3.   "_id": "1",
  4.   "_version": 66,
  5.   "result": "updated",
  6.   "_shards": {
  7.     "total": 2,
  8.     "successful": 1,
  9.     "failed": 0
  10.   },
  11.   "_seq_no": 65,
  12.   "_primary_term": 47
  13. }

Step 4 (Optional): Retrieve the document

To retrieve the document, run the following query:

  1. GET testindex1/_doc/1

copy

Response

The response includes the original user_agent field and the parsed user_agent_info field containing the device, operating system, and browser information:

  1. {
  2.   "_index": "testindex1",
  3.   "_id": "1",
  4.   "_version": 66,
  5.   "_seq_no": 65,
  6.   "_primary_term": 47,
  7.   "found": true,
  8.   "_source": {
  9.     "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
  10.     "user_agent_info": {
  11.       "original": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36",
  12.       "os": {
  13.         "name": "Mac OS X",
  14.         "version": "10.15.7",
  15.         "full": "Mac OS X 10.15.7"
  16.       },
  17.       "name": "Chrome",
  18.       "device": {
  19.         "name": "Mac"
  20.       },
  21.       "version": "90.0.4430.212"
  22.     }
  23.   }
  24. }