Adds a search field set to represent search events

CHANGELOG.next.md

@@ -16,6 +16,8 @@ Thanks, you're awesome :-) -->
 
 #### Added
 
+* Added `search.*` fields #729
+
 #### Improvements
 
 #### Deprecated

docs/field-details.asciidoc

@@ -4900,6 +4900,102 @@ example: `1.1`
 
 |=====
 
+[[ecs-search]]
+=== Search Fields
+
+The Search fields describe information about a search request event: query or pagination. The fields that should be used with this field set include: `event.action` to describe the search action (e.g. `search.query`, `search.page`, etc.), `event.duration` to describe the duration of a search request, `@timestamp` to record the event's original timestamp and optionally the `source` fields to record context information such as `user.id` or `geo`.
+
+==== Search Field Details
+
+[options="header"]
+|=====
+| Field  | Description | Level
+
+// ===============================================================
+
+| search.query.id
+| An opaque query identifier. This identifier needs to be unique to a user query, and all subsequent events (pagination, clicks) need to have the same query identifier.
+
+type: keyword
+
+
+
+example: `2dc15175-de0d-44db-86d8-8a99f41b7a11`
+
+| extended
+
+// ===============================================================
+
+| search.query.page
+| For search results that support pagination, this represents the current page being requested. Initial search requests are `1` while subsequent page requests are incremental.
+
+type: long
+
+
+
+example: `1`
+
+| extended
+
+// ===============================================================
+
+| search.query.value
+| The query string being searched on. This field is not analyzed and should not be pre-processed in any way in the event (e.g. normalization list lowercasing). This is useful for search use-cases that use a one- box style search interface. Other interfaces will have to rely on additional custom fields or labels to represent things like filters applied, extra parameters, user context, etc.
+
+type: keyword
+
+
+
+example: `where does the rain in Spain mainly fall`
+
+| extended
+
+// ===============================================================
+
+| search.results.ids
+| A list of opaque document IDs representing the results that were shown to the user. This is effectively the impression list and it's size should be equal to `results.size`. This field can be empty when there are no results to return.
+
+type: keyword
+
+
+Note: this field should contain an array of values.
+
+
+
+example: `['user:82375akja9f', 'issue:2782630']`
+
+| extended
+
+// ===============================================================
+
+| search.results.size
+| The size of the result set displayed to the user. This should be equivalent to the length of the results in `results.ids`. This is also known as the page size or limit.
+
+type: long
+
+
+
+example: `10`
+
+| extended
+
+// ===============================================================
+
+| search.results.total
+| The total number of matches for this query. This number is always greater than or equal to `results.size`. This is the `hits.total` field in the query response.
+
+type: long
+
+
+
+example: `134509`
+
+| extended
+
+// ===============================================================
+
+|=====
+
 [[ecs-server]]
 === Server Fields
 

docs/fields.asciidoc

@@ -80,6 +80,8 @@ all fields are defined.
 
 | <<ecs-rule,Rule>> | Fields to capture details about rules used to generate alerts or other notable events.
 
+| <<ecs-search,Search>> | Fields to describe details of a search event.
+
 | <<ecs-server,Server>> | Fields about the server side of a network connection, used with client.
 
 | <<ecs-service,Service>> | Fields describing the service for or from which the data was collected.

generated/beats/fields.ecs.yml

@@ -3544,6 +3544,74 @@
       description: The version / revision of the rule being used for analysis.
       example: 1.1
       default_field: false
+  - name: search
+    title: Search
+    group: 2
+    description: 'The Search fields describe information about a search request event:
+      query or pagination. The fields that should be used with this field set include:
+      `event.action` to describe the search action (e.g. `search.query`, `search.page`,
+      etc.), `event.duration` to describe the duration of a search request, `@timestamp`
+      to record the event''s original timestamp and optionally the `source` fields
+      to record context information such as `user.id` or `geo`.'
+    type: group
+    fields:
+    - name: query.id
+      level: extended
+      type: keyword
+      ignore_above: 1024
+      description: An opaque query identifier. This identifier needs to be unique
+        to a user query, and all subsequent events (pagination, clicks) need to have
+        the same query identifier.
+      example: 2dc15175-de0d-44db-86d8-8a99f41b7a11
+      default_field: false
+    - name: query.page
+      level: extended
+      type: long
+      description: For search results that support pagination, this represents the
+        current page being requested. Initial search requests are `1` while subsequent
+        page requests are incremental.
+      example: 1
+      default_field: false
+    - name: query.value
+      level: extended
+      type: keyword
+      ignore_above: 4096
+      description: The query string being searched on. This field is not analyzed
+        and should not be pre-processed in any way in the event (e.g. normalization
+        list lowercasing). This is useful for search use-cases that use a one- box
+        style search interface. Other interfaces will have to rely on additional custom
+        fields or labels to represent things like filters applied, extra parameters,
+        user context, etc.
+      example: where does the rain in Spain mainly fall
+      default_field: false
+    - name: results.ids
+      level: extended
+      type: keyword
+      ignore_above: 1024
+      description: A list of opaque document IDs representing the results that were
+        shown to the user. This is effectively the impression list and it's size should
+        be equal to `results.size`. This field can be empty when there are no results
+        to return.
+      example:
+      - user:82375akja9f
+      - issue:2782630
+      default_field: false
+    - name: results.size
+      level: extended
+      type: long
+      description: The size of the result set displayed to the user. This should be
+        equivalent to the length of the results in `results.ids`. This is also known
+        as the page size or limit.
+      example: 10
+      default_field: false
+    - name: results.total
+      level: extended
+      type: long
+      description: The total number of matches for this query. This number is always
+        greater than or equal to `results.size`. This is the `hits.total` field in
+        the query response.
+      example: 134509
+      default_field: false
   - name: server
     title: Server
     group: 2

generated/csv/fields.csv

@@ -444,6 +444,12 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 1.6.0-dev,true,rule,rule.ruleset,keyword,extended,,Standard_Protocol_Filters,Rule ruleset
 1.6.0-dev,true,rule,rule.uuid,keyword,extended,,1100110011,Rule UUID
 1.6.0-dev,true,rule,rule.version,keyword,extended,,1.1,Rule version
+1.6.0-dev,true,search,search.query.id,keyword,extended,,2dc15175-de0d-44db-86d8-8a99f41b7a11,An opaque query identifier.
+1.6.0-dev,true,search,search.query.page,long,extended,,1,The page of search results being requested.
+1.6.0-dev,true,search,search.query.value,keyword,extended,,where does the rain in Spain mainly fall,The query string being searched on.
+1.6.0-dev,true,search,search.results.ids,keyword,extended,array,"['user:82375akja9f', 'issue:2782630']",A list of document IDs in the result set.
+1.6.0-dev,true,search,search.results.size,long,extended,,10,The size of the result set displayed to the user.
+1.6.0-dev,true,search,search.results.total,long,extended,,134509,The total number of matches for this query.
 1.6.0-dev,true,server,server.address,keyword,extended,,,Server network address.
 1.6.0-dev,true,server,server.as.number,long,extended,,15169,Unique number allocated to the autonomous system. The autonomous system number (ASN) uniquely identifies each network on the Internet.
 1.6.0-dev,true,server,server.as.organization.name,keyword,extended,,Google LLC,Organization name.

generated/ecs/ecs_flat.yml

@@ -6159,6 +6159,91 @@ rule.version:
   order: 2
   short: Rule version
   type: keyword
+search.query.id:
+  dashed_name: search-query-id
+  description: An opaque query identifier. This identifier needs to be unique to a
+    user query, and all subsequent events (pagination, clicks) need to have the same
+    query identifier.
+  example: 2dc15175-de0d-44db-86d8-8a99f41b7a11
+  flat_name: search.query.id
+  ignore_above: 1024
+  level: extended
+  name: query.id
+  normalize: []
+  order: 0
+  short: An opaque query identifier.
+  type: keyword
+search.query.page:
+  dashed_name: search-query-page
+  description: For search results that support pagination, this represents the current
+    page being requested. Initial search requests are `1` while subsequent page requests
+    are incremental.
+  example: 1
+  flat_name: search.query.page
+  level: extended
+  name: query.page
+  normalize: []
+  order: 2
+  short: The page of search results being requested.
+  type: long
+search.query.value:
+  dashed_name: search-query-value
+  description: The query string being searched on. This field is not analyzed and
+    should not be pre-processed in any way in the event (e.g. normalization list lowercasing).
+    This is useful for search use-cases that use a one- box style search interface.
+    Other interfaces will have to rely on additional custom fields or labels to represent
+    things like filters applied, extra parameters, user context, etc.
+  example: where does the rain in Spain mainly fall
+  flat_name: search.query.value
+  ignore_above: 4096
+  level: extended
+  name: query.value
+  normalize: []
+  order: 1
+  short: The query string being searched on.
+  type: keyword
+search.results.ids:
+  dashed_name: search-results-ids
+  description: A list of opaque document IDs representing the results that were shown
+    to the user. This is effectively the impression list and it's size should be equal
+    to `results.size`. This field can be empty when there are no results to return.
+  example:
+  - user:82375akja9f
+  - issue:2782630
+  flat_name: search.results.ids
+  ignore_above: 1024
+  level: extended
+  name: results.ids
+  normalize:
+  - array
+  order: 5
+  short: A list of document IDs in the result set.
+  type: keyword
+search.results.size:
+  dashed_name: search-results-size
+  description: The size of the result set displayed to the user. This should be equivalent
+    to the length of the results in `results.ids`. This is also known as the page
+    size or limit.
+  example: 10
+  flat_name: search.results.size
+  level: extended
+  name: results.size
+  normalize: []
+  order: 3
+  short: The size of the result set displayed to the user.
+  type: long
+search.results.total:
+  dashed_name: search-results-total
+  description: The total number of matches for this query. This number is always greater
+    than or equal to `results.size`. This is the `hits.total` field in the query response.
+  example: 134509
+  flat_name: search.results.total
+  level: extended
+  name: results.total
+  normalize: []
+  order: 4
+  short: The total number of matches for this query.
+  type: long
 server.address:
   dashed_name: server-address
   description: 'Some event server addresses are defined ambiguously. The event will