Beef up the description of the log field set. (#540)

Author: Mathieu Martin

code/go/ecs/log.go

@@ -2103,7 +2103,11 @@ example: `1.1`
 [[ecs-log]]
 === Log Fields
 
-Fields which are specific to log events.
+Details about the event's logging mechanism or logging transport.
+
+The log.* fields are typically populated with details about the logging mechanism used to create and/or transport the event. For example, syslog details belong under `log.syslog.*`.
+
+The details specific to your event source are typically not logged under `log.*`, but rather in `event.*` or in other ECS fields.
 
 ==== Log Field Details
 

docs/field-details.asciidoc

@@ -52,7 +52,7 @@ all fields are defined.
 
 | <<ecs-http,HTTP>> | Fields describing an HTTP request.
 
-| <<ecs-log,Log>> | Fields which are specific to log events.
+| <<ecs-log,Log>> | Details about the event's logging mechanism.
 
 | <<ecs-network,Network>> | Fields describing the communication path over which the event happened.
 

docs/fields.asciidoc

@@ -1590,7 +1590,14 @@
   - name: log
     title: Log
     group: 2
-    description: Fields which are specific to log events.
+    description: 'Details about the event''s logging mechanism or logging transport.
+
+      The log.* fields are typically populated with details about the logging mechanism
+      used to create and/or transport the event. For example, syslog details belong
+      under `log.syslog.*`.
+
+      The details specific to your event source are typically not logged under `log.*`,
+      but rather in `event.*` or in other ECS fields.'
     type: group
     fields:
     - name: level

generated/beats/fields.ecs.yml

@@ -2571,7 +2571,14 @@ http:
   title: HTTP
   type: group
 log:
-  description: Fields which are specific to log events.
+  description: 'Details about the event''s logging mechanism or logging transport.
+
+    The log.* fields are typically populated with details about the logging mechanism
+    used to create and/or transport the event. For example, syslog details belong
+    under `log.syslog.*`.
+
+    The details specific to your event source are typically not logged under `log.*`,
+    but rather in `event.*` or in other ECS fields.'
   fields:
     level:
       description: 'Original log level of the log event.
@@ -2730,7 +2737,7 @@ log:
   group: 2
   name: log
   prefix: log.
-  short: Fields which are specific to log events.
+  short: Details about the event's logging mechanism.
   title: Log
   type: group
 network:

generated/ecs/ecs_nested.yml

@@ -1533,7 +1533,7 @@
     "type": "group"
   }, 
   "log": {
-    "description": "Fields which are specific to log events.\n", 
+    "description": "Details about the event's logging mechanism or logging transport.\nThe log.* fields are typically populated with details about the logging mechanism used to create and/or transport the event. For example, syslog details belong under `log.syslog.*`.\nThe details specific to your event source are typically not logged under `log.*`, but rather in `event.*` or in other ECS fields.\n", 
     "fields": {
       "log.level": {
         "description": "Original log level of the log event.\nIf the source of the event provides a log level or textual severity, this is the one that goes in `log.level`. If your source doesn't specify one, you may put your event transport's severity here (e.g. Syslog severity).\nSome examples are `warn`, `err`, `i`, `informational`.", 

schema.json

@@ -2,8 +2,16 @@
 - name: log
   title: Log
   group: 2
+  short: Details about the event's logging mechanism.
   description: >
-    Fields which are specific to log events.
+    Details about the event's logging mechanism or logging transport.
+
+    The log.* fields are typically populated with details about the logging
+    mechanism used to create and/or transport the event.
+    For example, syslog details belong under `log.syslog.*`.
+
+    The details specific to your event source are typically not logged under `log.*`,
+    but rather in `event.*` or in other ECS fields.
   type: group
   fields: