From 801885acd9ac4449d3198a48599a0e9826ae3806 Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Sat, 5 Jun 2021 08:06:14 +0100 Subject: [PATCH 1/5] Refactor running instructions Centralise all the documentation on how to run ElastAlert in one page. - Move the ElastAlert invocation arguments to the 'Running ElastAlert' page - Move the Docker and Helm chart instructions to the 'Running ElastAlert' page - Tidy the 'Running ElastAlert' page --- README.md | 28 +-- docs/source/elastalert.rst | 47 ----- docs/source/running_elastalert.rst | 271 ++++++++++++++++++++++++----- 3 files changed, 230 insertions(+), 116 deletions(-) diff --git a/README.md b/README.md index de285660..cd9971af 100644 --- a/README.md +++ b/README.md @@ -17,27 +17,12 @@ The full list of platforms that ElastAlert 2 can fire alerts into can be found [ Please see our [contributing guidelines][6]. -## Docker +## Docker and Kubernetes -If you're interested in a pre-built Docker image check out the [elastalert2][2] project on Docker Hub. - -Be aware that the `latest` tag of the image represents the latest commit into the master branch. If you prefer to upgrade more slowly you will need utilize a versioned tag, such as `2.1.0` instead, or `2` if you are comfortable with 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][1] provided as a template, and once saved locally to a file such as `/tmp/elastalert.yaml`, run the container as follows: - -```bash -docker run -d -v /tmp/elastalert.yaml:/opt/elastalert/config.yaml jertel/elastalert2 -``` - -To build the image locally run the following command: - -```bash -docker build . -t elastalert2 -``` - -## Kubernetes - -See the Helm chart [README.md][7] for information on installing this application into an existing Kubernetes cluster. +ElastAlert 2 is well-suited to being run as a microservice, and is available +as a [Docker container][2]. A [Helm chart ][7] is also maintained for easy +configuration as a Kubernetes deployment. For more instructions on how to +configure and run ElastAlert 2 in this way, see [here][8]. ## License @@ -50,4 +35,5 @@ ElastAlert 2 is licensed under the [Apache License, Version 2.0][5]. [4]: https://elastalert2.readthedocs.io/en/latest/ruletypes.html#alerts [5]: https://www.apache.org/licenses/LICENSE-2.0 [6]: https://github.com/jertel/elastalert2/blob/master/CONTRIBUTING.md -[7]: https://github.com/jertel/elastalert2/tree/master/chart/elastalert2 \ No newline at end of file +[7]: https://github.com/jertel/elastalert2/tree/master/chart/elastalert2 +[8]: https://elastalert2.readthedocs.io/en/latest/running_elastalert.html diff --git a/docs/source/elastalert.rst b/docs/source/elastalert.rst index 625ae229..bb942be1 100755 --- a/docs/source/elastalert.rst +++ b/docs/source/elastalert.rst @@ -244,50 +244,3 @@ adjust the logging format. For details, see the end of ``config.yaml.example`` where you can find an example logging configuration. - - -.. _runningelastalert: - -Running ElastAlert -================== - -``$ python elastalert/elastalert.py`` - -Several arguments are available when running ElastAlert: - -``--config`` will specify the configuration file to use. The default is ``config.yaml``. - -``--debug`` will run ElastAlert in debug mode. This will increase the logging verboseness, change -all alerts to ``DebugAlerter``, which prints alerts and suppresses their normal action, and skips writing -search and alert metadata back to Elasticsearch. Not compatible with `--verbose`. - -``--verbose`` will increase the logging verboseness, which allows you to see information about the state -of queries. Not compatible with `--debug`. - -``--start `` will force ElastAlert to begin querying from the given time, instead of the default, -querying from the present. The timestamp should be ISO8601, e.g. ``YYYY-MM-DDTHH:MM:SS`` (UTC) or with timezone -``YYYY-MM-DDTHH:MM:SS-08:00`` (PST). Note that if querying over a large date range, no alerts will be -sent until that rule has finished querying over the entire time period. To force querying from the current time, use "NOW". - -``--end `` will cause ElastAlert to stop querying at the specified timestamp. By default, ElastAlert -will periodically query until the present indefinitely. - -``--rule `` will only run the given rule. The rule file may be a complete file path or a filename in ``rules_folder`` -or its subdirectories. - -``--silence =`` will silence the alerts for a given rule for a period of time. The rule must be specified using -``--rule``. is one of days, weeks, hours, minutes or seconds. is an integer. For example, -``--rule noisy_rule.yaml --silence hours=4`` will stop noisy_rule from generating any alerts for 4 hours. - -``--es_debug`` will enable logging for all queries made to Elasticsearch. - -``--es_debug_trace `` will enable logging curl commands for all queries made to Elasticsearch to the -specified log file. ``--es_debug_trace`` is passed through to `elasticsearch.py -`_ which logs `localhost:9200` -instead of the actual ``es_host``:``es_port``. - -``--end `` will force ElastAlert to stop querying after the given time, instead of the default, -querying to the present time. This really only makes sense when running standalone. The timestamp is formatted -as ``YYYY-MM-DDTHH:MM:SS`` (UTC) or with timezone ``YYYY-MM-DDTHH:MM:SS-XX:00`` (UTC-XX). - -``--pin_rules`` will stop ElastAlert from loading, reloading or removing rules based on changes to their config files. diff --git a/docs/source/running_elastalert.rst b/docs/source/running_elastalert.rst index 268abfcc..f2015406 100644 --- a/docs/source/running_elastalert.rst +++ b/docs/source/running_elastalert.rst @@ -1,7 +1,114 @@ .. _tutorial: -Running ElastAlert for the First Time -===================================== +Running ElastAlert 2 +******************** + +ElastAlert 2 can easily be run as :ref:`a Docker container` +or directly on your machine as :ref:`a Python package`. +If you are not interested in modifying the internals of ElastAlert, the Docker +container is recommended for ease of use. + +Configuration flags +=================== + +However you choose to run ElastAlert, the ElastAlert process is started by invoking +``python elastalert/elastalert.py``. + +This command accepts several configuration flags: + +``--config`` will specify the configuration file to use. The default is +``config.yaml``. + +``--debug`` will run ElastAlert in debug mode. This will increase the logging +verboseness, change all alerts to ``DebugAlerter``, which prints alerts and +suppresses their normal action, and skips writing search and alert metadata back +to Elasticsearch. Not compatible with `--verbose`. + +``--verbose`` will increase the logging verboseness, which allows you to see +information about the state of queries. Not compatible with `--debug`. + +``--start `` will force ElastAlert to begin querying from the given +time, instead of the default, querying from the present. The timestamp should be +ISO8601, e.g. ``YYYY-MM-DDTHH:MM:SS`` (UTC) or with timezone +``YYYY-MM-DDTHH:MM:SS-08:00`` (PST). Note that if querying over a large date +range, no alerts will be sent until that rule has finished querying over the +entire time period. To force querying from the current time, use "NOW". + +``--end `` will cause ElastAlert to stop querying at the specified +timestamp. By default, ElastAlert will periodically query until the present +indefinitely. + +``--rule `` will only run the given rule. The rule file may be a +complete file path or a filename in ``rules_folder`` or its subdirectories. + +``--silence =`` will silence the alerts for a given rule for a +period of time. The rule must be specified using ``--rule``. is one of +days, weeks, hours, minutes or seconds. is an integer. For example, +``--rule noisy_rule.yaml --silence hours=4`` will stop noisy_rule from +generating any alerts for 4 hours. + +``--es_debug`` will enable logging for all queries made to Elasticsearch. + +``--es_debug_trace `` will enable logging curl commands for all +queries made to Elasticsearch to the specified log file. ``--es_debug_trace`` is +passed through to `elasticsearch.py +`_ which +logs `localhost:9200` instead of the actual ``es_host``:``es_port``. + +``--end `` will force ElastAlert to stop querying after the given +time, instead of the default, querying to the present time. This really only +makes sense when running standalone. The timestamp is formatted as +``YYYY-MM-DDTHH:MM:SS`` (UTC) or with timezone ``YYYY-MM-DDTHH:MM:SS-XX:00`` +(UTC-XX). + +``--pin_rules`` will stop ElastAlert from loading, reloading or removing rules +based on changes to their config files. + +.. _docker-instructions: + +As a Docker container +===================== + +If you're interested in a pre-built Docker image check out the +`elastalert2 +`_ project on Docker Hub. + +Be aware that the ``latest`` tag of the image represents the latest commit into +the master branch. If you prefer to upgrade more slowly you will need utilize a +versioned tag, such as ``2.1.0`` instead, or ``2`` if you are comfortable with +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: + +.. code-block:: + + docker run -d -v /tmp/elastalert.yaml:/opt/elastalert/config.yaml jertel/elastalert2 + +To build the image locally run the following command: + +.. code-block:: + + docker build . -t elastalert2 + +.. _kubernetes-instructions: + +As a Kubernetes deployment +========================== + +The Docker container for ElastAlert 2 can be used directly as a Kubernetes +deployment, but for convenience, a Helm chart is also available. See the +instructions provided `on Github +`_ for more information on +how to install, configure, and run the chart. + +.. _python-instructions: + +As a Python package +=================== Requirements ------------ @@ -31,45 +138,57 @@ Install the module:: $ pip install "setuptools>=11.3" $ python setup.py install -Depending on the version of Elasticsearch, you may need to manually install the correct version of elasticsearch-py. +Depending on the version of Elasticsearch, you may need to manually install the +correct version of elasticsearch-py. Elasticsearch 5.0+:: $ pip install "elasticsearch>=5.0.0" -Elasticsearch 2.X:: - - $ pip install "elasticsearch<3.0.0" - -Next, open up config.yaml.example. In it, you will find several configuration options. ElastAlert may be run without changing any of these settings. +Next, open up 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. +``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. ``run_every`` is how often ElastAlert will query Elasticsearch. -``buffer_time`` is the size of the query window, stretching backwards from the time each query is run. This value is ignored for rules where ``use_count_query`` or ``use_terms_query`` is set to true. +``buffer_time`` is the size of the query window, stretching backwards from the +time each query is run. This value is ignored for rules where +``use_count_query`` or ``use_terms_query`` is set to true. -``es_host`` is the address of an Elasticsearch cluster where ElastAlert will store data about its state, queries run, alerts, and errors. Each rule may also use a different Elasticsearch host to query against. +``es_host`` is the address of an Elasticsearch cluster where ElastAlert will +store data about its state, queries run, alerts, and errors. Each rule may also +use a different Elasticsearch host to query against. ``es_port`` is the port corresponding to ``es_host``. -``use_ssl``: Optional; whether or not to connect to ``es_host`` using TLS; set to ``True`` or ``False``. +``use_ssl``: Optional; whether or not to connect to ``es_host`` using TLS; set +to ``True`` or ``False``. -``verify_certs``: Optional; whether or not to verify TLS certificates; set to ``True`` or ``False``. The default is ``True`` +``verify_certs``: Optional; whether or not to verify TLS certificates; set to +``True`` or ``False``. The default is ``True`` -``ssl_show_warn``: Optional; suppress TLS and certificate related warnings; set to ``True`` or ``False``. The default is ``True``. +``ssl_show_warn``: Optional; suppress TLS and certificate related warnings; set +to ``True`` or ``False``. The default is ``True``. -``client_cert``: Optional; path to a PEM certificate to use as the client certificate +``client_cert``: Optional; path to a PEM certificate to use as the client +certificate ``client_key``: Optional; path to a private key file to use as the client key -``ca_certs``: Optional; path to a CA cert bundle to use to verify SSL connections +``ca_certs``: Optional; path to a CA cert bundle to use to verify SSL +connections ``es_username``: Optional; basic-auth username for connecting to ``es_host``. ``es_password``: Optional; basic-auth password for connecting to ``es_host``. -``es_bearer``: Optional; bearer token authorization for connecting to ``es_host``. If bearer token is specified, login and password are ignored. +``es_bearer``: Optional; bearer token authorization for connecting to +``es_host``. If bearer token is specified, login and password are ignored. ``es_url_prefix``: Optional; URL prefix for the Elasticsearch endpoint. @@ -77,9 +196,11 @@ Next, open up config.yaml.example. In it, you will find several configuration op ``statsd_host``: Optional; statsd host. -``es_send_get_body_as``: Optional; Method for querying Elasticsearch - ``GET``, ``POST`` or ``source``. The default is ``GET`` +``es_send_get_body_as``: Optional; Method for querying Elasticsearch - ``GET``, +``POST`` or ``source``. The default is ``GET`` -``writeback_index`` is the name of the index in which ElastAlert will store data. We will create this index later. +``writeback_index`` is the name of the index in which ElastAlert will store +data. We will create this index later. ``alert_time_limit`` is the retry window for failed alerts. @@ -88,9 +209,13 @@ Save the file as ``config.yaml`` Setting Up Elasticsearch ------------------------ -ElastAlert saves information and metadata about its queries and its alerts back to Elasticsearch. This is useful for auditing, debugging, and it allows ElastAlert to restart and resume exactly where it left off. This is not required for ElastAlert to run, but highly recommended. +ElastAlert saves information and metadata about its queries and its alerts back +to Elasticsearch. This is useful for auditing, debugging, and it allows +ElastAlert to restart and resume exactly where it left off. This is not required +for ElastAlert to run, but highly recommended. -First, we need to create an index for ElastAlert to write to by running ``elastalert-create-index`` and following the instructions:: +First, we need to create an index for ElastAlert to write to by running +``elastalert-create-index`` and following the instructions:: $ elastalert-create-index New index name (Default elastalert_status) @@ -98,12 +223,15 @@ First, we need to create an index for ElastAlert to write to by running ``elasta New index elastalert_status created Done! -For information about what data will go here, see :ref:`ElastAlert Metadata Index `. +For information about what data will go here, see :ref:`ElastAlert Metadata +Index `. 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:: +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:: # From example_rules/example_frequency.yaml es_host: elasticsearch.example.com @@ -113,7 +241,7 @@ Each rule defines a query to perform, parameters on what triggers a match, and a index: logstash-* num_events: 50 timeframe: - hours: 4 + hours: 4 filter: - term: some_field: "some_value" @@ -122,38 +250,59 @@ Each rule defines a query to perform, parameters on what triggers a match, and a email: - "elastalert@example.com" -``es_host`` and ``es_port`` should point to the Elasticsearch cluster we want to query. +``es_host`` and ``es_port`` should point to the Elasticsearch cluster we want to +query. -``name`` is the unique name for this rule. ElastAlert will not start if two rules share the same name. +``name`` is the unique name for this rule. ElastAlert will not start if two +rules share the same name. -``type``: Each rule has a different type which may take different parameters. The ``frequency`` type means "Alert when more than ``num_events`` occur within ``timeframe``." For information other types, see :ref:`Rule types `. +``type``: Each rule has a different type which may take different parameters. +The ``frequency`` type means "Alert when more than ``num_events`` occur within +``timeframe``." For information other types, see :ref:`Rule types `. -``index``: The name of the index(es) to query. If you are using Logstash, by default the indexes will match ``"logstash-*"``. +``index``: The name of the index(es) to query. If you are using Logstash, by +default the indexes will match ``"logstash-*"``. -``num_events``: This parameter is specific to ``frequency`` type and is the threshold for when an alert is triggered. +``num_events``: This parameter is specific to ``frequency`` type and is the +threshold for when an alert is triggered. ``timeframe`` is the time period in which ``num_events`` must occur. -``filter`` is a list of Elasticsearch filters that are used to filter results. Here we have a single term filter for documents with ``some_field`` matching ``some_value``. See :ref:`Writing Filters For Rules ` for more information. If no filters are desired, it should be specified as an empty list: ``filter: []`` +``filter`` is a list of Elasticsearch filters that are used to filter results. +Here we have a single term filter for documents with ``some_field`` matching +``some_value``. See :ref:`Writing Filters For Rules ` for more +information. If no filters are desired, it should be specified as an empty list: +``filter: []`` -``alert`` is a list of alerts to run on each match. For more information on alert types, see :ref:`Alerts `. The email alert requires an SMTP server for sending mail. By default, it will attempt to use localhost. This can be changed with the ``smtp_host`` option. +``alert`` is a list of alerts to run on each match. For more information on +alert types, see :ref:`Alerts `. The email alert requires an SMTP server +for sending mail. By default, it will attempt to use localhost. This can be +changed with the ``smtp_host`` option. ``email`` is a list of addresses to which alerts will be sent. -There are many other optional configuration options, see :ref:`Common configuration options `. +There are many other optional configuration options, see :ref:`Common +configuration options `. -All documents must have a timestamp field. ElastAlert will try to use ``@timestamp`` by default, but this can be changed with the ``timestamp_field`` option. By default, ElastAlert uses ISO8601 timestamps, though unix timestamps are supported by setting ``timestamp_type``. +All documents must have a timestamp field. ElastAlert will try to use +``@timestamp`` by default, but this can be changed with the ``timestamp_field`` +option. By default, ElastAlert uses ISO8601 timestamps, though unix timestamps +are supported by setting ``timestamp_type``. -As is, this rule means "Send an email to elastalert@example.com when there are more than 50 documents with ``some_field == some_value`` within a 4 hour period." +As is, this rule means "Send an email to elastalert@example.com when there are +more than 50 documents with ``some_field == some_value`` within a 4 hour +period." 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:: +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 -If you want to specify a configuration file to use, you can run it with the config flag:: +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 @@ -167,7 +316,9 @@ See :ref:`the testing section for more details ` Running ElastAlert ------------------ -There are two ways of invoking ElastAlert. As a daemon, through Supervisor (http://supervisord.org/), or directly with Python. For easier debugging purposes in this tutorial, we will invoke it directly:: +There are two ways of invoking ElastAlert. As a daemon, through Supervisor +(http://supervisord.org/), or directly with Python. For easier debugging +purposes in this tutorial, we will invoke it directly:: $ python -m elastalert.elastalert --verbose --rule example_frequency.yaml # or use the entry point: elastalert --verbose --rule ... No handlers could be found for logger "Elasticsearch" @@ -176,31 +327,46 @@ There are two ways of invoking ElastAlert. As a daemon, through Supervisor (http INFO:root:Ran Example rule from 1-15 14:22 PST to 1-15 15:07 PST: 5 query hits (0 already seen), 0 matches, 0 alerts sent INFO:root:Sleeping for 297 seconds -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. +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. Let's break down the response to see what's happening. ``Queried rule Example rule from 1-15 14:22 PST to 1-15 15:07 PST: 5 hits`` -ElastAlert periodically queries the most recent ``buffer_time`` (default 45 minutes) for data matching the filters. Here we see that it matched 5 hits: +ElastAlert periodically queries the most recent ``buffer_time`` (default 45 +minutes) for data matching the filters. Here we see that it matched 5 hits: .. code-block:: POST http://elasticsearch.example.com:14900/elastalert_status/elastalert_status?op_type=create [status:201 request:0.025s] -This line showing that ElastAlert uploaded a document to the elastalert_status index with information about the query it just made: +This line showing that ElastAlert uploaded a document to the elastalert_status +index with information about the query it just made: .. code-block:: Ran Example rule from 1-15 14:22 PST to 1-15 15:07 PST: 5 query hits (0 already seen), 0 matches, 0 alerts sent -The line means ElastAlert has finished processing the rule. For large time periods, sometimes multiple queries may be run, but their data will be processed together. ``query hits`` is the number of documents that are downloaded from Elasticsearch, ``already seen`` refers to documents that were already counted in a previous overlapping query and will be ignored, ``matches`` is the number of matches the rule type outputted, and ``alerts sent`` is the number of alerts actually sent. This may differ from ``matches`` because of options like ``realert`` and ``aggregation`` or because of an error. +The line means ElastAlert has finished processing the rule. For large time +periods, sometimes multiple queries may be run, but their data will be processed +together. ``query hits`` is the number of documents that are downloaded from +Elasticsearch, ``already seen`` refers to documents that were already counted in +a previous overlapping query and will be ignored, ``matches`` is the number of +matches the rule type outputted, and ``alerts sent`` is the number of alerts +actually sent. This may differ from ``matches`` because of options like +``realert`` and ``aggregation`` or because of an error. ``Sleeping for 297 seconds`` -The default ``run_every`` is 5 minutes, meaning ElastAlert will sleep until 5 minutes have elapsed from the last cycle before running queries for each rule again with time ranges shifted forward 5 minutes. +The default ``run_every`` is 5 minutes, meaning ElastAlert will sleep until 5 +minutes have elapsed from the last cycle before running queries for each rule +again with time ranges shifted forward 5 minutes. -Say, over the next 297 seconds, 46 more matching documents were added to Elasticsearch:: +Say, over the next 297 seconds, 46 more matching documents were added to +Elasticsearch:: INFO:root:Queried rule Example rule from 1-15 14:27 PST to 1-15 15:12 PST: 51 hits @@ -224,15 +390,24 @@ If an error occurred, such as an unreachable SMTP server, you may see: ERROR:root:Error while running alert email: Error connecting to SMTP host: [Errno 61] Connection refused -Note that if you stop ElastAlert and then run it again later, it will look up ``elastalert_status`` and begin querying -at the end time of the last query. This is to prevent duplication or skipping of alerts if ElastAlert is restarted. +Note that if you stop ElastAlert and then run it again later, it will look up +``elastalert_status`` and begin querying at the end time of the last query. This +is to prevent duplication or skipping of alerts if ElastAlert is restarted. -By using the ``--debug`` flag instead of ``--verbose``, the body of email will instead be logged and the email will not be sent. In addition, the queries will not be saved to ``elastalert_status``. +By using the ``--debug`` flag instead of ``--verbose``, the body of email will +instead be logged and the email will not be sent. In addition, the queries will +not be saved to ``elastalert_status``. Disabling a Rule ---------------- -To stop a rule from executing, add or adjust the `is_enabled` option inside the rule's YAML file to `false`. When ElastAlert reloads the rules it will detect that the rule has been disabled and prevent it from executing. The rule reload interval defaults to 5 minutes but can be adjusted via the `run_every` configuration option. +To stop a rule from executing, add or adjust the `is_enabled` option inside the +rule's YAML file to `false`. When ElastAlert reloads the rules it will detect +that the rule has been disabled and prevent it from executing. The rule reload +interval defaults to 5 minutes but can be adjusted via the `run_every` +configuration option. -Optionally, once a rule has been disabled it is safe to remove the rule file, if there is no intention of re-activating the rule. However, be aware that removing a rule file without first disabling it will _not_ disable the rule! +Optionally, once a rule has been disabled it is safe to remove the rule file, if +there is no intention of re-activating the rule. However, be aware that removing +a rule file without first disabling it will _not_ disable the rule! From b92be422864205cae275957477760502abb5b06a Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Sat, 5 Jun 2021 08:12:52 +0100 Subject: [PATCH 2/5] Add explanatory link to --config documentation --- docs/source/running_elastalert.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/source/running_elastalert.rst b/docs/source/running_elastalert.rst index f2015406..e1c58a7b 100644 --- a/docs/source/running_elastalert.rst +++ b/docs/source/running_elastalert.rst @@ -17,7 +17,8 @@ However you choose to run ElastAlert, the ElastAlert process is started by invok This command accepts several configuration flags: ``--config`` will specify the configuration file to use. The default is -``config.yaml``. +``config.yaml``. See :ref:`here` to understand what behaviour +can be configured in this file. ``--debug`` will run ElastAlert in debug mode. This will increase the logging verboseness, change all alerts to ``DebugAlerter``, which prints alerts and From 6c981f8aa19ce21a5bbf68031dc882f2fc707c5a Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Sat, 5 Jun 2021 08:15:19 +0100 Subject: [PATCH 3/5] Make Docker and k8s instructions more prominent --- README.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index cd9971af..f4156f5f 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,13 @@ ElastAlert 2 is backwards compatible with the original ElastAlert rules. ![CI Workflow](https://github.com/jertel/elastalert/workflows/master_build_test/badge.svg) +## Docker and Kubernetes + +ElastAlert 2 is well-suited to being run as a microservice, and is available +as a [Docker container][2]. A [Helm chart ][7] is also maintained for easy +configuration as a Kubernetes deployment. For more instructions on how to +configure and run ElastAlert 2 in this way, see [here][8]. + ## Documentation Documentation, including an FAQ, for ElastAlert 2 can be found on [readthedocs.com][3]. This is the place to start if you're not familiar with ElastAlert 2 at all. @@ -17,13 +24,6 @@ The full list of platforms that ElastAlert 2 can fire alerts into can be found [ Please see our [contributing guidelines][6]. -## Docker and Kubernetes - -ElastAlert 2 is well-suited to being run as a microservice, and is available -as a [Docker container][2]. A [Helm chart ][7] is also maintained for easy -configuration as a Kubernetes deployment. For more instructions on how to -configure and run ElastAlert 2 in this way, see [here][8]. - ## License ElastAlert 2 is licensed under the [Apache License, Version 2.0][5]. From 8bc734fc5fde2bb7f3bcc8bd3955c2ab69758e73 Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Sat, 5 Jun 2021 08:38:24 +0100 Subject: [PATCH 4/5] Fix missing reference --- docs/source/elastalert_status.rst | 2 +- docs/source/running_elastalert.rst | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/source/elastalert_status.rst b/docs/source/elastalert_status.rst index 99f26101..a5685624 100644 --- a/docs/source/elastalert_status.rst +++ b/docs/source/elastalert_status.rst @@ -67,4 +67,4 @@ an alert with ``realert`` is triggered, a ``silence`` record will be written wit be 0 unless ``exponential_realert`` is set. Whenever an alert is triggered, ElastAlert will check for a matching ``silence`` document, and if the ``until`` timestamp is in the future, it will ignore -the alert completely. See the :ref:`Running ElastAlert ` section for information on how to silence an alert. +the alert completely. See the :ref:`Running ElastAlert ` section for information on how to silence an alert. diff --git a/docs/source/running_elastalert.rst b/docs/source/running_elastalert.rst index e1c58a7b..784c4123 100644 --- a/docs/source/running_elastalert.rst +++ b/docs/source/running_elastalert.rst @@ -8,6 +8,8 @@ or directly on your machine as :ref:`a Python package`. If you are not interested in modifying the internals of ElastAlert, the Docker container is recommended for ease of use. +.. _elastalert-arguments: + Configuration flags =================== From 1fc21d467d08a635fd36312de49f9f627508fe77 Mon Sep 17 00:00:00 2001 From: Feroz Salam Date: Sat, 5 Jun 2021 08:43:54 +0100 Subject: [PATCH 5/5] Fix hyperlinked whitespace --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index f4156f5f..2b6de51b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ ElastAlert 2 is backwards compatible with the original ElastAlert rules. ## Docker and Kubernetes ElastAlert 2 is well-suited to being run as a microservice, and is available -as a [Docker container][2]. A [Helm chart ][7] is also maintained for easy +as a [Docker container][2]. A [Helm chart][7] is also maintained for easy configuration as a Kubernetes deployment. For more instructions on how to configure and run ElastAlert 2 in this way, see [here][8].