Link Search Menu Expand Document Documentation Menu
Documentation

This version of the OpenSearch documentation is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.

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:

{
  "processor": {
    "user_agent": {
      "field": "user_agent",
      "target_field": "user_agent_info"
    }
  }
}

Configuration parameters

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

Parameter Required/Optional Description
field Required The field containing the user agent string.
target_field Optional The field in which to store the extracted user agent information. If not specified, then the information is stored in the user_agent field.
ignore_missing Optional Specifies 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_file Optional A 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.
properties Optional A 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.
description Optional A brief description of the processor.
if Optional A condition for running the processor.
ignore_failure Optional Specifies whether the processor continues to run even if it encounters an error. If set to true, then failures are ignored. Default is false.
on_failure Optional A list of processors to run if the processor fails.
tag Optional An 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:

PUT _ingest/pipeline/user_agent_pipeline
{
  "description": "User agent pipeline",
  "processors": [
    {
      "user_agent": {
        "field": "user_agent",
        "target_field": "user_agent_info"
      }
    }
  ]
}

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:

POST _ingest/pipeline/user_agent_pipeline/_simulate
{
  "pipeline": "user_agent_pipeline",
  "docs": [
    {
      "_source": {
        "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"
      }
    }
  ]
}

Response

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

{
  "docs": [
    {
      "doc": {
        "_index": "_index",
        "_id": "_id",
        "_source": {
          "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",
          "user_agent_info": {
            "name": "Chrome",
            "original": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.3",
            "os": {
              "name": "Windows",
              "version": "10",
              "full": "Windows 10"
            },
            "device": {
              "name": "Other"
            },
            "version": "58.0.3029.110"
          }
        },
        "_ingest": {
          "timestamp": "2024-04-25T21:41:28.744407425Z"
        }
      }
    }
  ]
}

Step 3: Ingest a document

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

PUT testindex1/_doc/1?pipeline=user_agent_pipeline
{
  "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"
}

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:

{
  "_index": "testindex1",
  "_id": "1",
  "_version": 66,
  "result": "updated",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 65,
  "_primary_term": 47
}

Step 4 (Optional): Retrieve the document

To retrieve the document, run the following query:

GET testindex1/_doc/1

Response

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

{
  "_index": "testindex1",
  "_id": "1",
  "_version": 66,
  "_seq_no": 65,
  "_primary_term": 47,
  "found": true,
  "_source": {
    "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",
    "user_agent_info": {
      "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",
      "os": {
        "name": "Mac OS X",
        "version": "10.15.7",
        "full": "Mac OS X 10.15.7"
      },
      "name": "Chrome",
      "device": {
        "name": "Mac"
      },
      "version": "90.0.4430.212"
    }
  }
}
350 characters left

Have a question? .

Want to contribute? or .