From 88310009f707ab358b8f45524c030e07b3c2de1f Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 4 Mar 2019 17:46:17 -0500 Subject: [PATCH] Review comments + minor additional tweaks to wording & field name quoting --- README.md | 38 ++++++++++++++++++++++++-------------- docs/implementing.md | 38 ++++++++++++++++++++++++-------------- 2 files changed, 48 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 879ca8abbb..e6c36c719d 100644 --- a/README.md +++ b/README.md @@ -623,20 +623,30 @@ in the future. Please avoid using them: **How to populate ECS fields** -* Start by populating Core fields. These fields are the most common across all use cases. -* Populate as many Extended fields as practical. They generally apply to more narrow - use cases, so feel free to skip fields that are not applicable to your use case. -* When populating ECS fields, don't hesitate to duplicate data to all applicable - fields. This will ensure your data will be interoperable with the most - applications and content (such as visualizations), whether they are made by Elastic - or from the community. -* Try to populate ECS fields even if they are not in your event source. For example, - a Firewall event coming over syslog will not mention syslog. But `agent.type` - should still be set to "syslog". -* You're free to duplicate existing fields over to ECS fields, or to migrate your - fields to use the ECS names. The decision is up to you or the implementation. - What's important for ECS content and applications is the presence of the ECS - fields. Other fields are custom fields, and you can use them however you prefer. +In order to maximize the level of interoperability of your data with future analysis content +(e.g., saved searches, visualizations, dashboards, alerts, machine learning jobs, +reports, apps, etc.); whether this content is provided by Elastic +or shared by the community, please keep the following guidelines in mind. + + +* Start by populating ECS Core fields. These fields are the most common across + all use cases. Your implementation should attempt to populate as many of + the ECS Core fields as practical. + * ...even if these fields or values are metadata that are not present in your + original event. For example, a firewall event shipped to the Elastic Stack + over syslog may not actually include a field with value ”syslog,” but the + ECS `agent.type` field should still be set to “syslog." + * ...even if the data has already been mapped to one ECS field. For example, + if you’ve mapped your event’s client IP address to ECS `client.ip`, you can + also copy the same value to ECS `source.ip` and append it to `related.ip`. +* Populate as many ECS Extended fields as apply to the subject and use case of + your event. ECS Extended fields generally apply to more narrow use cases, + so feel free to skip ECS Extended fields that are not applicable to your use case. +* You're free to choose whether to copy your event fields to ECS fields, + leaving your original fields intact as custom fields, or to rename your existing + event fields to ECS, essentially migrating them to the ECS field names. + Future ECS content and applications will depend only upon the presence of + the ECS fields, and will ignore any custom fields. ## Normalization diff --git a/docs/implementing.md b/docs/implementing.md index e8f28279c0..ba3b893850 100644 --- a/docs/implementing.md +++ b/docs/implementing.md @@ -36,20 +36,30 @@ in the future. Please avoid using them: **How to populate ECS fields** -* Start by populating Core fields. These fields are the most common across all use cases. -* Populate as many Extended fields as practical. They generally apply to more narrow - use cases, so feel free to skip fields that are not applicable to your use case. -* When populating ECS fields, don't hesitate to duplicate data to all applicable - fields. This will ensure your data will be interoperable with the most - applications and content (such as visualizations), whether they are made by Elastic - or from the community. -* Try to populate ECS fields even if they are not in your event source. For example, - a Firewall event coming over syslog will not mention syslog. But `agent.type` - should still be set to "syslog". -* You're free to duplicate existing fields over to ECS fields, or to migrate your - fields to use the ECS names. The decision is up to you or the implementation. - What's important for ECS content and applications is the presence of the ECS - fields. Other fields are custom fields, and you can use them however you prefer. +In order to maximize the level of interoperability of your data with future analysis content +(e.g., saved searches, visualizations, dashboards, alerts, machine learning jobs, +reports, apps, etc.); whether this content is provided by Elastic +or shared by the community, please keep the following guidelines in mind. + + +* Start by populating ECS Core fields. These fields are the most common across + all use cases. Your implementation should attempt to populate as many of + the ECS Core fields as practical. + * ...even if these fields or values are metadata that are not present in your + original event. For example, a firewall event shipped to the Elastic Stack + over syslog may not actually include a field with value ”syslog,” but the + ECS `agent.type` field should still be set to “syslog." + * ...even if the data has already been mapped to one ECS field. For example, + if you’ve mapped your event’s client IP address to ECS `client.ip`, you can + also copy the same value to ECS `source.ip` and append it to `related.ip`. +* Populate as many ECS Extended fields as apply to the subject and use case of + your event. ECS Extended fields generally apply to more narrow use cases, + so feel free to skip ECS Extended fields that are not applicable to your use case. +* You're free to choose whether to copy your event fields to ECS fields, + leaving your original fields intact as custom fields, or to rename your existing + event fields to ECS, essentially migrating them to the ECS field names. + Future ECS content and applications will depend only upon the presence of + the ECS fields, and will ignore any custom fields. ## Normalization