From e2cd2f22ebd0defe263da2bf739e3e1fac3a2cb5 Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Sun, 13 Jun 2021 07:45:48 +0100 Subject: [PATCH 1/2] Tidy example files into a single folder This reduces clutter in the root directory and gives us a place to put all sample files in the future. Also updates the documentation to point to the new file locations. --- CONTRIBUTING.md | 2 +- README.md | 2 +- docs/source/elastalert.rst | 2 +- docs/source/recipes/adding_rules.rst | 2 +- docs/source/ruletypes.rst | 8 ++++---- docs/source/running_elastalert.rst | 16 ++++++++-------- .../config.yaml.example | 2 +- .../rules}/example_cardinality.yaml | 0 .../rules}/example_change.yaml | 0 .../rules}/example_frequency.yaml | 0 .../rules}/example_new_term.yaml | 0 .../rules}/example_opsgenie_frequency.yaml | 0 .../rules}/example_percentage_match.yaml | 0 .../rules}/example_single_metric_agg.yaml | 0 .../rules}/example_spike.yaml | 0 .../rules}/example_spike_single_metric_agg.yaml | 0 .../rules}/exemple_discord_any.yaml | 0 {example_rules => examples/rules}/jira_acct.txt | 0 .../rules}/ssh-repeat-offender.yaml | 0 {example_rules => examples/rules}/ssh.yaml | 0 .../supervisord.conf.example | 0 21 files changed, 17 insertions(+), 17 deletions(-) rename config.yaml.example => examples/config.yaml.example (99%) rename {example_rules => examples/rules}/example_cardinality.yaml (100%) rename {example_rules => examples/rules}/example_change.yaml (100%) rename {example_rules => examples/rules}/example_frequency.yaml (100%) rename {example_rules => examples/rules}/example_new_term.yaml (100%) rename {example_rules => examples/rules}/example_opsgenie_frequency.yaml (100%) rename {example_rules => examples/rules}/example_percentage_match.yaml (100%) rename {example_rules => examples/rules}/example_single_metric_agg.yaml (100%) rename {example_rules => examples/rules}/example_spike.yaml (100%) rename {example_rules => examples/rules}/example_spike_single_metric_agg.yaml (100%) rename {example_rules => examples/rules}/exemple_discord_any.yaml (100%) rename {example_rules => examples/rules}/jira_acct.txt (100%) rename {example_rules => examples/rules}/ssh-repeat-offender.yaml (100%) rename {example_rules => examples/rules}/ssh.yaml (100%) rename supervisord.conf.example => examples/supervisord.conf.example (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 429d51da..f4f310e6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ running on your machine). Before submitting the PR review that you have included the following changes, where applicable: - Documentation: If you're adding new functionality, any new configuration options should be documented appropriately in the docs/ folder. - Helm Chart: If your new feature introduces settings consider adding those to the Helm chart [README.md](chart/elastalert2/README.md) and [values.yaml](chart/elastalert2/values.yaml) -- Examples: If your new feature includes new configuration options, review the [Example config file](config.yaml.example) to see if they should be added there for consistency with other configuration options. +- Examples: If your new feature includes new configuration options, review the [Example config file](examples/config.yaml.example) to see if they should be added there for consistency with other configuration options. - Change log: Describe your contribution to the appropriate section(s) for the _Upcoming release_, in the [CHANGELOG.md](CHANGELOG.md) file. ## Releases diff --git a/README.md b/README.md index 985c1685..0e107021 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ Please see our [contributing guidelines][6]. ElastAlert 2 is licensed under the [Apache License, Version 2.0][5]. [0]: https://github.com/yelp/elastalert -[1]: https://github.com/jertel/elastalert2/blob/master/config.yaml.example +[1]: https://github.com/jertel/elastalert2/blob/master/examples/config.yaml.example [2]: https://hub.docker.com/r/jertel/elastalert2 [3]: https://elastalert2.readthedocs.io/ [4]: https://elastalert2.readthedocs.io/en/latest/ruletypes.html#alerts diff --git a/docs/source/elastalert.rst b/docs/source/elastalert.rst index bb942be1..3cf1ec24 100755 --- a/docs/source/elastalert.rst +++ b/docs/source/elastalert.rst @@ -242,5 +242,5 @@ If you need a more sophisticated logging configuration, you can provide a full l in the config file. This way you can also configure logging to a file, to Logstash and adjust the logging format. -For details, see the end of ``config.yaml.example`` where you can find an example logging +For details, see the end of ``examples/config.yaml.example`` where you can find an example logging configuration. diff --git a/docs/source/recipes/adding_rules.rst b/docs/source/recipes/adding_rules.rst index 1ea2be6f..296b0d67 100644 --- a/docs/source/recipes/adding_rules.rst +++ b/docs/source/recipes/adding_rules.rst @@ -130,7 +130,7 @@ Now, in a file named ``my_rules.py``, add pass -In the rule configuration file, ``example_rules/example_login_rule.yaml``, we are going to specify this rule by writing +In the rule configuration file, ``examples/rules/example_login_rule.yaml``, we are going to specify this rule by writing .. code-block:: yaml diff --git a/docs/source/ruletypes.rst b/docs/source/ruletypes.rst index ac23307d..c3ad96eb 100644 --- a/docs/source/ruletypes.rst +++ b/docs/source/ruletypes.rst @@ -1,7 +1,7 @@ Rule Types and Configuration Options ************************************ -Examples of several types of rule configuration can be found in the example_rules folder. +Examples of several types of rule configuration can be found in the ``examples/rules`` folder. .. _commonconfig: @@ -913,7 +913,7 @@ It is possible to mix between whitelisted value definitions, or use either one. Change ~~~~~~ -For an example configuration file using this rule type, look at ``example_rules/example_change.yaml``. +For an example configuration file using this rule type, look at ``examples/rules/example_change.yaml``. ``change``: This rule will monitor a certain field and match if that field changes. The field must change with respect to the last event with the same ``query_key``. @@ -936,7 +936,7 @@ of the ``compare_key`` field. Frequency ~~~~~~~~~ -For an example configuration file using this rule type, look at ``example_rules/example_frequency.yaml``. +For an example configuration file using this rule type, look at ``example/rules/example_frequency.yaml``. ``frequency``: This rule matches when there are at least a certain number of events in a given time frame. This may be counted on a per-``query_key`` basis. @@ -2062,7 +2062,7 @@ This alert requires four additional options: ``jira_account_file``: The path to the file which contains JIRA account credentials. -For an example JIRA account file, see ``example_rules/jira_acct.yaml``. The account file is also yaml formatted and must contain two fields: +For an example JIRA account file, see ``examples/rules/jira_acct.yaml``. The account file is also yaml formatted and must contain two fields: ``user``: The username. diff --git a/docs/source/running_elastalert.rst b/docs/source/running_elastalert.rst index 1fb1a389..cf78f108 100644 --- a/docs/source/running_elastalert.rst +++ b/docs/source/running_elastalert.rst @@ -82,7 +82,7 @@ always using the latest released version of ElastAlert 2. A properly configured config.yaml file must be mounted into the container during startup of the container. Use the `example file -`_ +`_ provided as a template, and once saved locally to a file such as ``/tmp/elastalert.yaml``, run the container as follows: @@ -146,14 +146,14 @@ Elasticsearch 5.0+:: $ pip install "elasticsearch>=5.0.0" -Next, open up config.yaml.example. In it, you will find several configuration +Next, open up ``examples/config.yaml.example``. In it, you will find several configuration options. ElastAlert may be run without changing any of these settings. ``rules_folder`` is where ElastAlert will load rule configuration files from. It will attempt to load every .yaml file in the folder. Without any valid rules, ElastAlert will not start. ElastAlert will also load new rules, stop running missing rules, and restart modified rules as the files in this folder change. -For this tutorial, we will use the example_rules folder. +For this tutorial, we will use the ``examples/rules`` folder. ``run_every`` is how often ElastAlert will query Elasticsearch. @@ -232,9 +232,9 @@ Creating a Rule Each rule defines a query to perform, parameters on what triggers a match, and a list of alerts to fire for each match. We are going to use -``example_rules/example_frequency.yaml`` as a template:: +``examples/rules/example_frequency.yaml`` as a template:: - # From example_rules/example_frequency.yaml + # From examples/rules/example_frequency.yaml es_host: elasticsearch.example.com es_port: 14900 name: Example rule @@ -300,12 +300,12 @@ Testing Your Rule Running the ``elastalert-test-rule`` tool will test that your config file successfully loads and run it in debug mode over the last 24 hours:: - $ elastalert-test-rule example_rules/example_frequency.yaml + $ elastalert-test-rule examples/rules/example_frequency.yaml If you want to specify a configuration file to use, you can run it with the config flag:: - $ elastalert-test-rule --config example_rules/example_frequency.yaml + $ elastalert-test-rule --config examples/rules/example_frequency.yaml The configuration preferences will be loaded as follows: 1. Configurations specified in the yaml file. @@ -331,7 +331,7 @@ purposes in this tutorial, we will invoke it directly:: ElastAlert uses the python logging system and ``--verbose`` sets it to display INFO level messages. ``--rule example_frequency.yaml`` specifies the rule to run, otherwise ElastAlert will attempt to load the other rules in the -example_rules folder. +``examples/rules`` folder. Let's break down the response to see what's happening. diff --git a/config.yaml.example b/examples/config.yaml.example similarity index 99% rename from config.yaml.example rename to examples/config.yaml.example index d0e6299b..a80a48f8 100644 --- a/config.yaml.example +++ b/examples/config.yaml.example @@ -1,7 +1,7 @@ # This is the folder that contains the rule yaml files # This can also be a list of directories # Any .yaml file will be loaded as a rule -rules_folder: example_rules +rules_folder: examples/rules # How often ElastAlert will query Elasticsearch # The unit can be anything from weeks to seconds diff --git a/example_rules/example_cardinality.yaml b/examples/rules/example_cardinality.yaml similarity index 100% rename from example_rules/example_cardinality.yaml rename to examples/rules/example_cardinality.yaml diff --git a/example_rules/example_change.yaml b/examples/rules/example_change.yaml similarity index 100% rename from example_rules/example_change.yaml rename to examples/rules/example_change.yaml diff --git a/example_rules/example_frequency.yaml b/examples/rules/example_frequency.yaml similarity index 100% rename from example_rules/example_frequency.yaml rename to examples/rules/example_frequency.yaml diff --git a/example_rules/example_new_term.yaml b/examples/rules/example_new_term.yaml similarity index 100% rename from example_rules/example_new_term.yaml rename to examples/rules/example_new_term.yaml diff --git a/example_rules/example_opsgenie_frequency.yaml b/examples/rules/example_opsgenie_frequency.yaml similarity index 100% rename from example_rules/example_opsgenie_frequency.yaml rename to examples/rules/example_opsgenie_frequency.yaml diff --git a/example_rules/example_percentage_match.yaml b/examples/rules/example_percentage_match.yaml similarity index 100% rename from example_rules/example_percentage_match.yaml rename to examples/rules/example_percentage_match.yaml diff --git a/example_rules/example_single_metric_agg.yaml b/examples/rules/example_single_metric_agg.yaml similarity index 100% rename from example_rules/example_single_metric_agg.yaml rename to examples/rules/example_single_metric_agg.yaml diff --git a/example_rules/example_spike.yaml b/examples/rules/example_spike.yaml similarity index 100% rename from example_rules/example_spike.yaml rename to examples/rules/example_spike.yaml diff --git a/example_rules/example_spike_single_metric_agg.yaml b/examples/rules/example_spike_single_metric_agg.yaml similarity index 100% rename from example_rules/example_spike_single_metric_agg.yaml rename to examples/rules/example_spike_single_metric_agg.yaml diff --git a/example_rules/exemple_discord_any.yaml b/examples/rules/exemple_discord_any.yaml similarity index 100% rename from example_rules/exemple_discord_any.yaml rename to examples/rules/exemple_discord_any.yaml diff --git a/example_rules/jira_acct.txt b/examples/rules/jira_acct.txt similarity index 100% rename from example_rules/jira_acct.txt rename to examples/rules/jira_acct.txt diff --git a/example_rules/ssh-repeat-offender.yaml b/examples/rules/ssh-repeat-offender.yaml similarity index 100% rename from example_rules/ssh-repeat-offender.yaml rename to examples/rules/ssh-repeat-offender.yaml diff --git a/example_rules/ssh.yaml b/examples/rules/ssh.yaml similarity index 100% rename from example_rules/ssh.yaml rename to examples/rules/ssh.yaml diff --git a/supervisord.conf.example b/examples/supervisord.conf.example similarity index 100% rename from supervisord.conf.example rename to examples/supervisord.conf.example From 4500f28468ed8f3c42701bb7acb12fa0d6326dee Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Mon, 14 Jun 2021 21:15:53 +0100 Subject: [PATCH 2/2] Fix typo Also tweak gitignore to only look for `/rules` folders under the root directory --- .gitignore | 2 +- docs/source/ruletypes.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 70251410..c58f29bc 100644 --- a/.gitignore +++ b/.gitignore @@ -16,4 +16,4 @@ build/ my_rules *.swp *~ -rules/ +/rules/ diff --git a/docs/source/ruletypes.rst b/docs/source/ruletypes.rst index c3ad96eb..2b2a95f9 100644 --- a/docs/source/ruletypes.rst +++ b/docs/source/ruletypes.rst @@ -936,7 +936,7 @@ of the ``compare_key`` field. Frequency ~~~~~~~~~ -For an example configuration file using this rule type, look at ``example/rules/example_frequency.yaml``. +For an example configuration file using this rule type, look at ``examples/rules/example_frequency.yaml``. ``frequency``: This rule matches when there are at least a certain number of events in a given time frame. This may be counted on a per-``query_key`` basis.