Enhance description of event.outcome field (#759)

CHANGELOG.next.md

@@ -23,6 +23,7 @@ Thanks, you're awesome :-) -->
 
 * Temporary workaround for Beats templates' `default_field` growing too big. #687
 * Identify which fields should contain arrays of values, rather than scalar values. #727, #661
+* Updated definition of `event.outcome` based on community feedback #759
 
 #### Deprecated
 

docs/field-details.asciidoc

@@ -1680,7 +1680,13 @@ example: `Sep 19 08:26:10 host CEF:0|Security| threatmanager|1.0&
 | event.outcome
 | This is one of four ECS Categorization Fields, and indicates the lowest level in the ECS category hierarchy.
 
-`event.outcome` simply denotes whether the event represent a success or a failure. Note that not all events will have an associated outcome. For example, this field is generally not populated for metric events or events with `event.type:info`.
+`event.outcome` simply denotes whether the event represents a success or a failure from the perspective of the entity that produced the event.
+
+Note that when a single transaction is described in multiple events, each event may populate different values of `event.outcome`, according to their perspective.
+
+Also note that in the case of a compound event (a single event that contains multiple logical events), this field should be populated with the value that best captures the overall success or failure from the perspective of the event producer.
+
+Further note that not all events will have an associated outcome. For example, this field is generally not populated for metric events, events with `event.type:info`, or any events for which an outcome does not make logical sense.
 
 type: keyword
 

docs/field-values.asciidoc

@@ -416,7 +416,13 @@ The start event type is used for the subset of events within a category that ind
 
 This is one of four ECS Categorization Fields, and indicates the lowest level in the ECS category hierarchy.
 
-`event.outcome` simply denotes whether the event represent a success or a failure. Note that not all events will have an associated outcome. For example, this field is generally not populated for metric events or events with `event.type:info`.
+`event.outcome` simply denotes whether the event represents a success or a failure from the perspective of the entity that produced the event.
+
+Note that when a single transaction is described in multiple events, each event may populate different values of `event.outcome`, according to their perspective.
+
+Also note that in the case of a compound event (a single event that contains multiple logical events), this field should be populated with the value that best captures the overall success or failure from the perspective of the event producer.
+
+Further note that not all events will have an associated outcome. For example, this field is generally not populated for metric events, events with `event.type:info`, or any events for which an outcome does not make logical sense.
 
 WARNING: After the beta period for categorization, only the allowed categorization
 values listed in the ECS repository and official ECS documentation should be considered
@@ -443,7 +449,7 @@ Indicates that this event describes a failed result. A common example is `event.
 [[ecs-event-outcome-success]]
 ==== success
 
-Indicates that this event describes a successful result.  A common example is `event.category:file AND event.type:create AND event.outcome:success` to indicate that a file was successfully created.
+Indicates that this event describes a successful result. A common example is `event.category:file AND event.type:create AND event.outcome:success` to indicate that a file was successfully created.
 
 
 
@@ -453,7 +459,7 @@ Indicates that this event describes a successful result.  A common example is `e
 [[ecs-event-outcome-unknown]]
 ==== unknown
 
-Indicates that this event describes only an attempt for which the result is unknown. For example, if the event contains information only about a request in an entity transaction that usually results in a response, populating `event.outcome:unknown` is appropriate.
+Indicates that this event describes only an attempt for which the result is unknown from the perspective of the event producer. For example, if the event contains information only about the request side of a transaction that results in a response, populating `event.outcome:unknown` in the request event is appropriate. The unknown value should not be used when an outcome doesn't make logical sense for the event. In such cases `event.outcome` should not be populated.
 
 
 

generated/beats/fields.ecs.yml

@@ -1270,9 +1270,21 @@
       description: 'This is one of four ECS Categorization Fields, and indicates the
         lowest level in the ECS category hierarchy.
 
-        `event.outcome` simply denotes whether the event represent a success or a
-        failure. Note that not all events will have an associated outcome. For example,
-        this field is generally not populated for metric events or events with `event.type:info`.'
+        `event.outcome` simply denotes whether the event represents a success or a
+        failure from the perspective of the entity that produced the event.
+
+        Note that when a single transaction is described in multiple events, each
+        event may populate different values of `event.outcome`, according to their
+        perspective.
+
+        Also note that in the case of a compound event (a single event that contains
+        multiple logical events), this field should be populated with the value that
+        best captures the overall success or failure from the perspective of the event
+        producer.
+
+        Further note that not all events will have an associated outcome. For example,
+        this field is generally not populated for metric events, events with `event.type:info`,
+        or any events for which an outcome does not make logical sense.'
       example: success
     - name: provider
       level: extended

generated/csv/fields.csv

@@ -149,7 +149,7 @@ ECS_Version,Indexed,Field_Set,Field,Type,Level,Normalization,Example,Description
 1.5.0-dev,true,event,event.kind,keyword,core,,alert,The kind of the event. The highest categorization field in the hierarchy.
 1.5.0-dev,true,event,event.module,keyword,core,,apache,Name of the module this data is coming from.
 1.5.0-dev,false,event,event.original,keyword,core,,Sep 19 08:26:10 host CEF:0|Security| threatmanager|1.0|100| worm successfully stopped|10|src=10.0.0.1 dst=2.1.2.2spt=1232,Raw text message of entire event.
-1.5.0-dev,true,event,event.outcome,keyword,core,,success,The outcome of the event. The lowest categorization field in the hierarchy.
+1.5.0-dev,true,event,event.outcome,keyword,core,,success,The outcome of the event. The lowest level categorization field in the hierarchy.
 1.5.0-dev,true,event,event.provider,keyword,extended,,kernel,Source of the event.
 1.5.0-dev,true,event,event.risk_score,float,core,,,Risk score or priority of the event (e.g. security solutions). Use your system's original value here.
 1.5.0-dev,true,event,event.risk_score_norm,float,extended,,,Normalized risk score or priority of the event (0-100).

generated/ecs/ecs_flat.yml

@@ -2153,34 +2153,47 @@ event.outcome:
 
       '
     name: failure
-  - description: 'Indicates that this event describes a successful result.  A common
+  - description: 'Indicates that this event describes a successful result. A common
       example is `event.category:file AND event.type:create AND event.outcome:success`
       to indicate that a file was successfully created.
 
       '
     name: success
   - description: 'Indicates that this event describes only an attempt for which the
-      result is unknown. For example, if the event contains information only about
-      a request in an entity transaction that usually results in a response, populating
-      `event.outcome:unknown` is appropriate.
+      result is unknown from the perspective of the event producer. For example, if
+      the event contains information only about the request side of a transaction
+      that results in a response, populating `event.outcome:unknown` in the request
+      event is appropriate. The unknown value should not be used when an outcome doesn''t
+      make logical sense for the event. In such cases `event.outcome` should not be
+      populated.
 
       '
     name: unknown
   dashed_name: event-outcome
   description: 'This is one of four ECS Categorization Fields, and indicates the lowest
     level in the ECS category hierarchy.
 
-    `event.outcome` simply denotes whether the event represent a success or a failure.
-    Note that not all events will have an associated outcome. For example, this field
-    is generally not populated for metric events or events with `event.type:info`.'
+    `event.outcome` simply denotes whether the event represents a success or a failure
+    from the perspective of the entity that produced the event.
+
+    Note that when a single transaction is described in multiple events, each event
+    may populate different values of `event.outcome`, according to their perspective.
+
+    Also note that in the case of a compound event (a single event that contains multiple
+    logical events), this field should be populated with the value that best captures
+    the overall success or failure from the perspective of the event producer.
+
+    Further note that not all events will have an associated outcome. For example,
+    this field is generally not populated for metric events, events with `event.type:info`,
+    or any events for which an outcome does not make logical sense.'
   example: success
   flat_name: event.outcome
   ignore_above: 1024
   level: core
   name: outcome
   normalize: []
   order: 5
-  short: The outcome of the event. The lowest categorization field in the hierarchy.
+  short: The outcome of the event. The lowest level categorization field in the hierarchy.
   type: keyword
 event.provider:
   dashed_name: event-provider

generated/ecs/ecs_nested.yml

@@ -2411,34 +2411,50 @@ event:
 
           '
         name: failure
-      - description: 'Indicates that this event describes a successful result.  A
-          common example is `event.category:file AND event.type:create AND event.outcome:success`
+      - description: 'Indicates that this event describes a successful result. A common
+          example is `event.category:file AND event.type:create AND event.outcome:success`
           to indicate that a file was successfully created.
 
           '
         name: success
       - description: 'Indicates that this event describes only an attempt for which
-          the result is unknown. For example, if the event contains information only
-          about a request in an entity transaction that usually results in a response,
-          populating `event.outcome:unknown` is appropriate.
+          the result is unknown from the perspective of the event producer. For example,
+          if the event contains information only about the request side of a transaction
+          that results in a response, populating `event.outcome:unknown` in the request
+          event is appropriate. The unknown value should not be used when an outcome
+          doesn''t make logical sense for the event. In such cases `event.outcome`
+          should not be populated.
 
           '
         name: unknown
       dashed_name: event-outcome
       description: 'This is one of four ECS Categorization Fields, and indicates the
         lowest level in the ECS category hierarchy.
 
-        `event.outcome` simply denotes whether the event represent a success or a
-        failure. Note that not all events will have an associated outcome. For example,
-        this field is generally not populated for metric events or events with `event.type:info`.'
+        `event.outcome` simply denotes whether the event represents a success or a
+        failure from the perspective of the entity that produced the event.
+
+        Note that when a single transaction is described in multiple events, each
+        event may populate different values of `event.outcome`, according to their
+        perspective.
+
+        Also note that in the case of a compound event (a single event that contains
+        multiple logical events), this field should be populated with the value that
+        best captures the overall success or failure from the perspective of the event
+        producer.
+
+        Further note that not all events will have an associated outcome. For example,
+        this field is generally not populated for metric events, events with `event.type:info`,
+        or any events for which an outcome does not make logical sense.'
       example: success
       flat_name: event.outcome
       ignore_above: 1024
       level: core
       name: outcome
       normalize: []
       order: 5
-      short: The outcome of the event. The lowest categorization field in the hierarchy.
+      short: The outcome of the event. The lowest level categorization field in the
+        hierarchy.
       type: keyword
     provider:
       dashed_name: event-provider

schemas/event.yml

@@ -244,14 +244,24 @@
     - name: outcome
       level: core
       type: keyword
-      short: The outcome of the event. The lowest categorization field in the hierarchy.
+      short: The outcome of the event. The lowest level categorization field in the hierarchy.
       description: >
         This is one of four ECS Categorization Fields, and indicates the
         lowest level in the ECS category hierarchy.
 
-        `event.outcome` simply denotes whether the event represent a success or a failure.
-        Note that not all events will have an associated outcome. For example, this field is
-        generally not populated for metric events or events with `event.type:info`.
+        `event.outcome` simply denotes whether the event represents a success or a failure from
+        the perspective of the entity that produced the event.
+
+        Note that when a single transaction is described in multiple events, each event may
+        populate different values of `event.outcome`, according to their perspective.
+
+        Also note that in the case of a compound event (a single event that contains multiple logical events),
+        this field should be populated with the value that best captures the overall success or failure from
+        the perspective of the event producer.
+
+        Further note that not all events will have an associated outcome. For example, this field is
+        generally not populated for metric events, events with `event.type:info`, or any events for
+        which an outcome does not make logical sense.
       example: success
       allowed_values:
         - name: failure
@@ -261,15 +271,18 @@
             to indicate that a file access was attempted, but was not successful.
         - name: success
           description: >
-            Indicates that this event describes a successful result.  A common example is
+            Indicates that this event describes a successful result. A common example is
             `event.category:file AND event.type:create AND event.outcome:success`
             to indicate that a file was successfully created.
         - name: unknown
           description: >
             Indicates that this event describes only an attempt for which the result
-            is unknown. For example, if the event contains information only about a
-            request in an entity transaction that usually results in a response,
-            populating `event.outcome:unknown` is appropriate.
+            is unknown from the perspective of the event producer.
+            For example, if the event contains information only about the request side
+            of a transaction that results in a response, populating `event.outcome:unknown`
+            in the request event is appropriate.
+            The unknown value should not be used when an outcome doesn't make logical sense for
+            the event. In such cases `event.outcome` should not be populated.
 
     - name: type
       level: core