From 6c47109b61c2caed00a9ae55d5e2816e1aee2bf6 Mon Sep 17 00:00:00 2001 From: Mathieu Martin Date: Mon, 18 Feb 2019 15:56:09 -0500 Subject: [PATCH] Split up some field set definitions in multiple paragraphs This will improve consistency with field definitions. --- README.md | 14 +++++++++++--- code/go/ecs/process.go | 8 ++++---- code/go/ecs/related.go | 13 +++++++------ code/go/ecs/server.go | 16 ++++++++-------- fields.yml | 7 ++++++- schema.json | 6 +++--- schemas/process.yml | 1 + schemas/related.yml | 2 ++ schemas/server.yml | 4 +++- 9 files changed, 45 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index ed8893bdc7..ad2aa32333 100644 --- a/README.md +++ b/README.md @@ -395,7 +395,9 @@ Note also that the `os` fields are not expected to be used directly at the top l ## Process fields -These fields contain information about a process. These fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation. +These fields contain information about a process. + +These fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation. | Field | Description | Level | Type | Example | @@ -413,7 +415,11 @@ These fields contain information about a process. These fields can help you corr ## 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, observer, source, destination, client, server, 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`. +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, observer, source, destination, client, server, 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 | @@ -423,7 +429,9 @@ This field set is meant to facilitate pivoting around a piece of data. Some piec ## Server fields -A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. +A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. + +For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. Client / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately. diff --git a/code/go/ecs/process.go b/code/go/ecs/process.go index 8cad946d9c..b81da4e3dc 100644 --- a/code/go/ecs/process.go +++ b/code/go/ecs/process.go @@ -23,10 +23,10 @@ import ( "time" ) -// These fields contain information about a process. These fields can help you -// correlate metrics information with a process id/name from a log message. -// The `process.pid` often stays in the metric itself and is copied to the -// global field for correlation. +// These fields contain information about a process. +// These fields can help you correlate metrics information with a process +// id/name from a log message. The `process.pid` often stays in the metric +// itself and is copied to the global field for correlation. type Process struct { // Process id. PID int64 `ecs:"pid"` diff --git a/code/go/ecs/related.go b/code/go/ecs/related.go index f4a7f8dc22..ae4b8108d3 100644 --- a/code/go/ecs/related.go +++ b/code/go/ecs/related.go @@ -19,13 +19,14 @@ package ecs -// 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 +// 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, -// observer, source, destination, client, server, 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`. +// `related.`. +// A concrete example is IP addresses, which can be under host, observer, +// source, destination, client, server, 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 Related struct { // All of the IPs seen on your event. IP string `ecs:"ip"` diff --git a/code/go/ecs/server.go b/code/go/ecs/server.go index c05b64b2fc..ca81c34ceb 100644 --- a/code/go/ecs/server.go +++ b/code/go/ecs/server.go @@ -20,14 +20,14 @@ package ecs // A Server is defined as the responder in a network connection for events -// regarding sessions, connections, or bidirectional flow records. For TCP -// events, the server is the receiver of the initial SYN packet(s) of the TCP -// connection. For other protocols, the server is generally the responder in -// the network transaction. Some systems actually use the term "responder" to -// refer the server in TCP connections. The server fields describe details -// about the system acting as the server in the network event. Server fields -// are usually populated in conjunction with client fields. Server fields are -// generally not populated for packet-level events. +// regarding sessions, connections, or bidirectional flow records. +// For TCP events, the server is the receiver of the initial SYN packet(s) of +// the TCP connection. For other protocols, the server is generally the +// responder in the network transaction. Some systems actually use the term +// "responder" to refer the server in TCP connections. The server fields +// describe details about the system acting as the server in the network event. +// Server fields are usually populated in conjunction with client fields. +// Server fields are generally not populated for packet-level events. // Client / server representations can add semantic context to an exchange, // which is helpful to visualize the data in certain situations. If your // context falls in that category, you should still ensure that source and diff --git a/fields.yml b/fields.yml index 7b0d87a82a..085f68e834 100644 --- a/fields.yml +++ b/fields.yml @@ -1279,6 +1279,7 @@ group: 2 description: > These fields contain information about a process. + These fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation. @@ -1361,9 +1362,11 @@ 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, observer, source, destination, client, server, 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: @@ -1378,7 +1381,9 @@ title: Server group: 2 description: > - A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. + A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. + + For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. Client / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately. type: group diff --git a/schema.json b/schema.json index 20b7c9be7c..53fae04f1c 100644 --- a/schema.json +++ b/schema.json @@ -1441,7 +1441,7 @@ "type": "group" }, "process": { - "description": "These fields contain information about a process. These fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation.\n", + "description": "These fields contain information about a process.\nThese fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation.\n", "fields": { "process.args": { "description": "Array of process arguments.\nMay be filtered to protect sensitive information.", @@ -1540,7 +1540,7 @@ "type": "group" }, "related": { - "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, observer, source, destination, client, server, 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`.\n", + "description": "This field set is meant to facilitate pivoting around a piece of data.\nSome pieces of information can be seen in many places in ECS. To facilitate searching for them, append values to their corresponding field in `related.`.\nA concrete example is IP addresses, which can be under host, observer, source, destination, client, server, 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`.\n", "fields": { "related.ip": { "description": "All of the IPs seen on your event.", @@ -1559,7 +1559,7 @@ "type": "group" }, "server": { - "description": "A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term \"responder\" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events.\nClient / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately.\n", + "description": "A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records.\nFor TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term \"responder\" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events.\nClient / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately.\n", "fields": { "server.address": { "description": "Some event server addresses are defined ambiguously. The event will sometimes list an IP, a domain or a unix socket. You should always store the raw address in the `.address` field.\nThen it should be duplicated to `.ip` or `.domain`, depending on which one it is.", diff --git a/schemas/process.yml b/schemas/process.yml index 55ef14d2dd..a14ecbeba9 100644 --- a/schemas/process.yml +++ b/schemas/process.yml @@ -4,6 +4,7 @@ group: 2 description: > These fields contain information about a process. + These fields can help you correlate metrics information with a process id/name from a log message. The `process.pid` often stays in the metric itself and is copied to the global field for correlation. diff --git a/schemas/related.yml b/schemas/related.yml index 9815aa80dc..ee04841236 100644 --- a/schemas/related.yml +++ b/schemas/related.yml @@ -4,9 +4,11 @@ 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, observer, source, destination, client, server, 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: diff --git a/schemas/server.yml b/schemas/server.yml index 9c590546a4..d3a3fb158b 100644 --- a/schemas/server.yml +++ b/schemas/server.yml @@ -3,7 +3,9 @@ title: Server group: 2 description: > - A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. + A Server is defined as the responder in a network connection for events regarding sessions, connections, or bidirectional flow records. + + For TCP events, the server is the receiver of the initial SYN packet(s) of the TCP connection. For other protocols, the server is generally the responder in the network transaction. Some systems actually use the term "responder" to refer the server in TCP connections. The server fields describe details about the system acting as the server in the network event. Server fields are usually populated in conjunction with client fields. Server fields are generally not populated for packet-level events. Client / server representations can add semantic context to an exchange, which is helpful to visualize the data in certain situations. If your context falls in that category, you should still ensure that source and destination are filled appropriately. type: group