From f5461ae24999ca1c0c2cb70a8ad173ec2a5a186e Mon Sep 17 00:00:00 2001 From: Christoph Wurm Date: Wed, 16 Jan 2019 16:20:26 +0000 Subject: [PATCH] [Auditbeat] Cherry-pick #10101 to 6.6: Rename "metricset" to "dataset" in docs (#10106) Cherry-pick of PR #10101 to 6.6 branch. Original message: Follow up to https://github.com/elastic/beats/pull/10018. Changes the Auditbeat system module documentation to say `dataset` rather than `metricset` in all places. No Go code changes. --- auditbeat/_meta/common.reference.yml | 2 +- auditbeat/auditbeat.reference.yml | 2 +- auditbeat/scripts/docs_collector.py | 64 +++++++++---------- x-pack/auditbeat/auditbeat.reference.yml | 2 +- x-pack/auditbeat/docs/modules/system.asciidoc | 45 ++++++------- .../docs/modules/system/host.asciidoc | 8 +-- .../docs/modules/system/process.asciidoc | 8 +-- .../docs/modules/system/socket.asciidoc | 8 +-- .../docs/modules/system/user.asciidoc | 8 +-- .../module/system/_meta/docs.asciidoc | 33 +++++----- .../module/system/host/_meta/docs.asciidoc | 2 +- .../module/system/process/_meta/docs.asciidoc | 2 +- .../module/system/socket/_meta/docs.asciidoc | 2 +- .../module/system/user/_meta/docs.asciidoc | 2 +- 14 files changed, 95 insertions(+), 93 deletions(-) diff --git a/auditbeat/_meta/common.reference.yml b/auditbeat/_meta/common.reference.yml index b8728c0be6e3..9e57b9634f36 100644 --- a/auditbeat/_meta/common.reference.yml +++ b/auditbeat/_meta/common.reference.yml @@ -22,7 +22,7 @@ auditbeat.config.modules: # Set to true to enable config reloading reload.enabled: false -# Maximum amount of time to randomly delay the start of a metricset. Use 0 to +# Maximum amount of time to randomly delay the start of a dataset. Use 0 to # disable startup delay. auditbeat.max_start_delay: 10s diff --git a/auditbeat/auditbeat.reference.yml b/auditbeat/auditbeat.reference.yml index 2f67e3c7b101..f54e322e72bb 100644 --- a/auditbeat/auditbeat.reference.yml +++ b/auditbeat/auditbeat.reference.yml @@ -22,7 +22,7 @@ auditbeat.config.modules: # Set to true to enable config reloading reload.enabled: false -# Maximum amount of time to randomly delay the start of a metricset. Use 0 to +# Maximum amount of time to randomly delay the start of a dataset. Use 0 to # disable startup delay. auditbeat.max_start_delay: 10s diff --git a/auditbeat/scripts/docs_collector.py b/auditbeat/scripts/docs_collector.py index 87e1d3104aa2..0a3cff5e7b3d 100644 --- a/auditbeat/scripts/docs_collector.py +++ b/auditbeat/scripts/docs_collector.py @@ -3,7 +3,7 @@ import yaml import six -# Collects docs for all modules and metricset +# Collects docs for all modules and datasets def collect(base_paths): @@ -60,7 +60,7 @@ def collect(base_paths): config_file = beat_path + "/config.yml" # Add example config file - if os.path.isfile(config_file) == True: + if os.path.isfile(config_file): module_file += """ @@ -75,7 +75,7 @@ def collect(base_paths): ---- """ + beat_name + ".modules:\n" - # Load metricset yaml + # Load dataset yaml with open(config_file) as f: # Add 2 spaces for indentation in front of each line for line in f: @@ -86,63 +86,63 @@ def collect(base_paths): module_links = "" module_includes = "" - # Iterate over all metricsets - for metricset in sorted(os.listdir(module_dir)): + # Iterate over all datasets + for dataset in sorted(os.listdir(module_dir)): - metricset_docs = os.path.join(module_dir, metricset, "_meta/docs.asciidoc") + dataset_docs = os.path.join(module_dir, dataset, "_meta/docs.asciidoc") # Only check folders where fields.yml exists - if os.path.isfile(metricset_docs) == False: + if not os.path.isfile(dataset_docs): continue - link_name = "{beatname_lc}-metricset-" + module + "-" + metricset - link = "<<" + link_name + "," + metricset + ">>" + link_name = "{beatname_lc}-dataset-" + module + "-" + dataset + link = "<<" + link_name + "," + dataset + ">>" reference = "[id=\"" + link_name + "\"]" module_links += "* " + link + "\n\n" - module_includes += "include::" + module + "/" + metricset + ".asciidoc[]\n\n" + module_includes += "include::" + module + "/" + dataset + ".asciidoc[]\n\n" - metricset_file = generated_note + dataset_file = generated_note - # Add reference to metricset file and include file - metricset_file += reference + "\n" + # Add reference to dataset file and include file + dataset_file += reference + "\n" - # Create title out of module and metricset set name - metricset_file += "=== {} {} metricset\n\n".format(title, metricset) + # Create title out of module and dataset set name + dataset_file += "=== {} {} dataset\n\n".format(title, dataset) - metricset_file += 'include::../../../module/' + module + '/' + metricset + '/_meta/docs.asciidoc[]' + "\n" + dataset_file += 'include::../../../module/' + module + '/' + dataset + '/_meta/docs.asciidoc[]' + "\n" - # TODO: This should point directly to the exported fields of the metricset, not the whole module - metricset_file += """ + # TODO: This should point directly to the exported fields of the dataset, not the whole module + dataset_file += """ ==== Fields -For a description of each field in the metricset, see the +For a description of each field in the dataset, see the <> section. """ - data_file = os.path.join(module_dir, metricset, "_meta/data.json") + data_file = os.path.join(module_dir, dataset, "_meta/data.json") # Add data.json example json document - if os.path.isfile(data_file) == True: - metricset_file += "Here is an example document generated by this metricset:" - metricset_file += "\n\n" + if os.path.isfile(data_file): + dataset_file += "Here is an example document generated by this dataset:" + dataset_file += "\n\n" - metricset_file += "[source,json]\n" - metricset_file += "----\n" - metricset_file += "include::../../../module/" + module + "/" + metricset + "/_meta/data.json[]\n" - metricset_file += "----\n" + dataset_file += "[source,json]\n" + dataset_file += "----\n" + dataset_file += "include::../../../module/" + module + "/" + dataset + "/_meta/data.json[]\n" + dataset_file += "----\n" - # Write metricset docs - with open(os.path.join(module_docs_path(module_dir), "modules", module, metricset + ".asciidoc"), 'w') as f: - f.write(metricset_file) + # Write dataset docs + with open(os.path.join(module_docs_path(module_dir), "modules", module, dataset + ".asciidoc"), 'w') as f: + f.write(dataset_file) if len(module_links) > 0: module_file += "[float]\n" - module_file += "=== Metricsets\n\n" - module_file += "The following metricsets are available:\n\n" + module_file += "=== Datasets\n\n" + module_file += "The following datasets are available:\n\n" module_file += module_links module_file += module_includes diff --git a/x-pack/auditbeat/auditbeat.reference.yml b/x-pack/auditbeat/auditbeat.reference.yml index 0d8eb825efcb..08c2f4fa99ce 100644 --- a/x-pack/auditbeat/auditbeat.reference.yml +++ b/x-pack/auditbeat/auditbeat.reference.yml @@ -22,7 +22,7 @@ auditbeat.config.modules: # Set to true to enable config reloading reload.enabled: false -# Maximum amount of time to randomly delay the start of a metricset. Use 0 to +# Maximum amount of time to randomly delay the start of a dataset. Use 0 to # disable startup delay. auditbeat.max_start_delay: 10s diff --git a/x-pack/auditbeat/docs/modules/system.asciidoc b/x-pack/auditbeat/docs/modules/system.asciidoc index 35deb7acb820..64198c06d27d 100644 --- a/x-pack/auditbeat/docs/modules/system.asciidoc +++ b/x-pack/auditbeat/docs/modules/system.asciidoc @@ -10,30 +10,30 @@ This file is generated! See scripts/docs_collector.py experimental[] The `system` module collects various security related information about -a system. All metricsets send both periodic state information (e.g. all currently +a system. All datasets send both periodic state information (e.g. all currently running processes) and real-time changes (e.g. when a new process starts or stops). -The module is fully implemented for Linux. Some metricsets are also available +The module is fully implemented for Linux. Some datasets are also available for macOS (Darwin) and Windows. [float] === How it works -Each metricset sends two kinds of information: state and events. +Each dataset sends two kinds of information: state and events. -State information is sent periodically and on startup (for some metricsets). +State information is sent periodically and (for some datasets) on startup. A state update will consist of one event per object that is currently active on the system (e.g. a process). All events belonging to the same state update will share the same UUID in `event.id`. -The frequency of state updates can be controlled for all metricsets using the -`state.period` configuration option. Overrides are available per metricset. +The frequency of state updates can be controlled for all datasets using the +`state.period` configuration option. Overrides are available per dataset. The default is `12h`. Event information is sent as the events occur (e.g. a process starts or stops). -All metricsets are currently using a poll model to retrieve their data. -The frequency of these polls is controlled using the `period` configuration +All datasets are currently using a poll model to retrieve their data. +The frequency of these polls is controlled by the `period` configuration parameter. [float] @@ -43,13 +43,13 @@ This module has some configuration options for controlling its behavior. The following example shows all configuration options with their default values for Linux. -NOTE: It is recommended to configure some metricsets separately. See below for a +NOTE: It is recommended to configure some datasets separately. See below for a sample suggested configuration. [source,yaml] ---- - module: system - metricsets: + datasets: - host - process - socket @@ -59,13 +59,13 @@ sample suggested configuration. user.detect_password_changes: true ---- -*`period`*:: The frequency at which the metricsets check for changes. For most -metricsets - esp. `process` and `socket` - a shorter period is recommended. +*`period`*:: The frequency at which the datasets check for changes. For most +datasets - esp. `process` and `socket` - a shorter period is recommended. -*`state.period`*:: The frequency at which the metricsets send full state information. -This option can be overridden per metricset using `{metricset}.state.period`. +*`state.period`*:: The frequency at which the datasets send full state information. +This option can be overridden per dataset using `{dataset}.state.period`. -*`user.detect_password_changes`*:: If the `user` metricset is configured and +*`user.detect_password_changes`*:: If the `user` dataset is configured and this option is set to `true`, Auditbeat will read password information in `/etc/passwd` and `/etc/shadow` to detect password changes. A hash will be kept locally in the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` file @@ -84,13 +84,14 @@ so a longer polling interval can be used. [source,yaml] ---- - module: system - metricsets: + datasets: - host - user period: 1m user.detect_password_changes: true - module: system + datasets: - process - socket period: 1s @@ -126,17 +127,17 @@ auditbeat.modules: ---- [float] -=== Metricsets +=== Datasets -The following metricsets are available: +The following datasets are available: -* <<{beatname_lc}-metricset-system-host,host>> +* <<{beatname_lc}-dataset-system-host,host>> -* <<{beatname_lc}-metricset-system-process,process>> +* <<{beatname_lc}-dataset-system-process,process>> -* <<{beatname_lc}-metricset-system-socket,socket>> +* <<{beatname_lc}-dataset-system-socket,socket>> -* <<{beatname_lc}-metricset-system-user,user>> +* <<{beatname_lc}-dataset-system-user,user>> include::system/host.asciidoc[] diff --git a/x-pack/auditbeat/docs/modules/system/host.asciidoc b/x-pack/auditbeat/docs/modules/system/host.asciidoc index 484702d801b0..9c36068927f5 100644 --- a/x-pack/auditbeat/docs/modules/system/host.asciidoc +++ b/x-pack/auditbeat/docs/modules/system/host.asciidoc @@ -2,18 +2,18 @@ This file is generated! See scripts/docs_collector.py //// -[id="{beatname_lc}-metricset-system-host"] -=== System host metricset +[id="{beatname_lc}-dataset-system-host"] +=== System host dataset include::../../../module/system/host/_meta/docs.asciidoc[] ==== Fields -For a description of each field in the metricset, see the +For a description of each field in the dataset, see the <> section. -Here is an example document generated by this metricset: +Here is an example document generated by this dataset: [source,json] ---- diff --git a/x-pack/auditbeat/docs/modules/system/process.asciidoc b/x-pack/auditbeat/docs/modules/system/process.asciidoc index 605d20d055ca..a015dfc29af6 100644 --- a/x-pack/auditbeat/docs/modules/system/process.asciidoc +++ b/x-pack/auditbeat/docs/modules/system/process.asciidoc @@ -2,18 +2,18 @@ This file is generated! See scripts/docs_collector.py //// -[id="{beatname_lc}-metricset-system-process"] -=== System process metricset +[id="{beatname_lc}-dataset-system-process"] +=== System process dataset include::../../../module/system/process/_meta/docs.asciidoc[] ==== Fields -For a description of each field in the metricset, see the +For a description of each field in the dataset, see the <> section. -Here is an example document generated by this metricset: +Here is an example document generated by this dataset: [source,json] ---- diff --git a/x-pack/auditbeat/docs/modules/system/socket.asciidoc b/x-pack/auditbeat/docs/modules/system/socket.asciidoc index 9c63d7bbb2d4..387756c1ca9c 100644 --- a/x-pack/auditbeat/docs/modules/system/socket.asciidoc +++ b/x-pack/auditbeat/docs/modules/system/socket.asciidoc @@ -2,18 +2,18 @@ This file is generated! See scripts/docs_collector.py //// -[id="{beatname_lc}-metricset-system-socket"] -=== System socket metricset +[id="{beatname_lc}-dataset-system-socket"] +=== System socket dataset include::../../../module/system/socket/_meta/docs.asciidoc[] ==== Fields -For a description of each field in the metricset, see the +For a description of each field in the dataset, see the <> section. -Here is an example document generated by this metricset: +Here is an example document generated by this dataset: [source,json] ---- diff --git a/x-pack/auditbeat/docs/modules/system/user.asciidoc b/x-pack/auditbeat/docs/modules/system/user.asciidoc index 6d64e9884885..58b3a07e3afb 100644 --- a/x-pack/auditbeat/docs/modules/system/user.asciidoc +++ b/x-pack/auditbeat/docs/modules/system/user.asciidoc @@ -2,18 +2,18 @@ This file is generated! See scripts/docs_collector.py //// -[id="{beatname_lc}-metricset-system-user"] -=== System user metricset +[id="{beatname_lc}-dataset-system-user"] +=== System user dataset include::../../../module/system/user/_meta/docs.asciidoc[] ==== Fields -For a description of each field in the metricset, see the +For a description of each field in the dataset, see the <> section. -Here is an example document generated by this metricset: +Here is an example document generated by this dataset: [source,json] ---- diff --git a/x-pack/auditbeat/module/system/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/_meta/docs.asciidoc index 02e163f78483..4dc42e8c17d1 100644 --- a/x-pack/auditbeat/module/system/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/_meta/docs.asciidoc @@ -5,30 +5,30 @@ experimental[] The `system` module collects various security related information about -a system. All metricsets send both periodic state information (e.g. all currently +a system. All datasets send both periodic state information (e.g. all currently running processes) and real-time changes (e.g. when a new process starts or stops). -The module is fully implemented for Linux. Some metricsets are also available +The module is fully implemented for Linux. Some datasets are also available for macOS (Darwin) and Windows. [float] === How it works -Each metricset sends two kinds of information: state and events. +Each dataset sends two kinds of information: state and events. -State information is sent periodically and on startup (for some metricsets). +State information is sent periodically and (for some datasets) on startup. A state update will consist of one event per object that is currently active on the system (e.g. a process). All events belonging to the same state update will share the same UUID in `event.id`. -The frequency of state updates can be controlled for all metricsets using the -`state.period` configuration option. Overrides are available per metricset. +The frequency of state updates can be controlled for all datasets using the +`state.period` configuration option. Overrides are available per dataset. The default is `12h`. Event information is sent as the events occur (e.g. a process starts or stops). -All metricsets are currently using a poll model to retrieve their data. -The frequency of these polls is controlled using the `period` configuration +All datasets are currently using a poll model to retrieve their data. +The frequency of these polls is controlled by the `period` configuration parameter. [float] @@ -38,13 +38,13 @@ This module has some configuration options for controlling its behavior. The following example shows all configuration options with their default values for Linux. -NOTE: It is recommended to configure some metricsets separately. See below for a +NOTE: It is recommended to configure some datasets separately. See below for a sample suggested configuration. [source,yaml] ---- - module: system - metricsets: + datasets: - host - process - socket @@ -54,13 +54,13 @@ sample suggested configuration. user.detect_password_changes: true ---- -*`period`*:: The frequency at which the metricsets check for changes. For most -metricsets - esp. `process` and `socket` - a shorter period is recommended. +*`period`*:: The frequency at which the datasets check for changes. For most +datasets - esp. `process` and `socket` - a shorter period is recommended. -*`state.period`*:: The frequency at which the metricsets send full state information. -This option can be overridden per metricset using `{metricset}.state.period`. +*`state.period`*:: The frequency at which the datasets send full state information. +This option can be overridden per dataset using `{dataset}.state.period`. -*`user.detect_password_changes`*:: If the `user` metricset is configured and +*`user.detect_password_changes`*:: If the `user` dataset is configured and this option is set to `true`, Auditbeat will read password information in `/etc/passwd` and `/etc/shadow` to detect password changes. A hash will be kept locally in the `beat.db` file to detect changes between Auditbeat restarts. The `beat.db` file @@ -79,13 +79,14 @@ so a longer polling interval can be used. [source,yaml] ---- - module: system - metricsets: + datasets: - host - user period: 1m user.detect_password_changes: true - module: system + datasets: - process - socket period: 1s diff --git a/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc index da154c35ad76..a0baab22b267 100644 --- a/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/host/_meta/docs.asciidoc @@ -2,6 +2,6 @@ experimental[] -This is the `host` metricset of the system module. +This is the `host` dataset of the system module. It is implemented for Linux, macOS (Darwin), and Windows. diff --git a/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc index bf702544c3e8..2ae6d7943db6 100644 --- a/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/process/_meta/docs.asciidoc @@ -2,6 +2,6 @@ experimental[] -This is the `process` metricset of the system module. +This is the `process` dataset of the system module. It is implemented for Linux, macOS (Darwin), and Windows. diff --git a/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc index 61e98483311e..4a81754e1e85 100644 --- a/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/socket/_meta/docs.asciidoc @@ -2,6 +2,6 @@ experimental[] -This is the `process` metricset of the system module. +This is the `socket` dataset of the system module. It is implemented for Linux only. diff --git a/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc b/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc index dd5af6ead89f..6f777bba92c9 100644 --- a/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc +++ b/x-pack/auditbeat/module/system/user/_meta/docs.asciidoc @@ -2,6 +2,6 @@ experimental[] -This is the `user` metricset of the system module. +This is the `user` dataset of the system module. It is implemented for Linux only.