Introduce the related. field set with only one field, to start. (el…

…astic#206)

CHANGELOG.md

@@ -11,6 +11,9 @@ All notable changes to this project will be documented in this file based on the
 * Add `host.name` field and clarify usage of `host.hostname`. #187
 * Add `event.start` and `event.end` date fields. #185
 * Add `process.thread.id` field. #200
+* Add `host.name` field and clarify usage of `host.hostname`.
+* Add `event.start` and `event.end` date fields.
+* Create new `related` field set with `related.ip`. #206
 
 ### Improvements
 * Improve and clarify the definition of Device fields #192

README.md

@@ -64,6 +64,7 @@ ECS defines these fields.
  * [Organization fields](#organization)
  * [Operating System fields](#os)
  * [Process fields](#process)
+ * [Related fields](#related)
  * [Service fields](#service)
  * [Source fields](#source)
  * [URL fields](#url)
@@ -345,6 +346,18 @@ These fields contain information about a process. These fields can help you corr
 | <a name="process.thread.id"></a>process.thread.id | Thread ID. | extended | long | `4242` |
 
 
+## <a name="related"></a> Related fields
+
+This field set is meant to facilitate pivoting around a piece of data. Some pieces of information can be seen in many places in ECS. To facilitate searching for them, append values to their corresponding field in `related.`.
+
+A concrete example is IP addresses, which can be under host, device, source, destination, and network.forwarded_ip. If you append all IPs to `related.ip`, you can then search for a given IP trivially, no matter where it appeared, by querying `related.ip:a.b.c.d`.
+
+
+| Field  | Description  | Level  | Type  | Example  |
+|---|---|---|---|---|
+| <a name="related.ip"></a>related.ip | All of the IPs seen on your event. | extended | ip |  |
+
+
 ## <a name="service"></a> Service fields
 
 The service fields describe the service for or from which the data was collected. These fields help you find and correlate logs for a specific service and version.

fields.yml

@@ -1010,6 +1010,28 @@
           description: >
             Thread ID.
     
+    - name: related
+      title: Related
+      group: 2
+      description: >
+        This field set is meant to facilitate pivoting around a piece of data.
+        Some pieces of information can be seen in many places in ECS. To facilitate
+        searching for them, append values to their corresponding field in
+        `related.`.
+    
+        A concrete example is IP addresses, which can be under host, device, source,
+        destination, and network.forwarded_ip. If you append all IPs to
+        `related.ip`, you can then search for a given IP trivially,
+        no matter where it appeared, by querying `related.ip:a.b.c.d`.
+      type: group
+      fields:
+
+        - name: ip
+          level: extended
+          type: ip
+          description: >
+            All of the IPs seen on your event.
+    
     - name: service
       title: Service
       group: 2

schema.csv

@@ -106,6 +106,7 @@ process.pid,long,core,4242
 process.ppid,long,extended,
 process.thread.id,long,extended,4242
 process.title,keyword,extended,
+related.ip,ip,extended,
 service.ephemeral_id,keyword,extended,8a4f500f
 service.id,keyword,core,d37e5ebfe0ae6c4972dbe9f0174a1637bb8247f6
 service.name,keyword,core,elasticsearch-metrics

schemas/related.yml

@@ -0,0 +1,22 @@
+---
+- name: related
+  title: Related
+  group: 2
+  description: >
+    This field set is meant to facilitate pivoting around a piece of data.
+    Some pieces of information can be seen in many places in ECS. To facilitate
+    searching for them, append values to their corresponding field in
+    `related.`.
+
+    A concrete example is IP addresses, which can be under host, device, source,
+    destination, and network.forwarded_ip. If you append all IPs to
+    `related.ip`, you can then search for a given IP trivially,
+    no matter where it appeared, by querying `related.ip:a.b.c.d`.
+  type: group
+  fields:
+
+    - name: ip
+      level: extended
+      type: ip
+      description: >
+        All of the IPs seen on your event.

template.json

@@ -516,6 +516,13 @@
             }
           }
         },
+        "related": {
+          "properties": {
+            "ip": {
+              "type": "ip"
+            }
+          }
+        },
         "service": {
           "properties": {
             "ephemeral_id": {