Issue #419 - WIP docs

README.rst

@@ -102,6 +102,7 @@ What It Does
   `Getting Started - Trusted Advisor <http://awslimitchecker.readthedocs.io/en/latest/getting_started.html#trusted-advisor>`_
   for more information.
 - Optionally send current usage and limit metrics to a metrics store, such as Datadog.
+- Optionally send warning/critical alerts to notification providers, such as PagerDuty.
 
 Requirements
 ------------

docs/source/cli_usage.rst

@@ -524,6 +524,13 @@ environment variable) and an optional ``extra_tags`` parameter:
 Metrics will be pushed to the provider only when awslimitchecker is done checking
 all limits.
 
+.. _cli_usage.alerts:
+
+Enable Alerts Provider
++++++++++++++++++++++++
+
+TBD.
+
 Required IAM Policy
 +++++++++++++++++++
 

docs/source/cli_usage.rst.template

@@ -234,6 +234,13 @@ environment variable) and an optional ``extra_tags`` parameter:
 Metrics will be pushed to the provider only when awslimitchecker is done checking
 all limits.
 
+.. _cli_usage.alerts:
+
+Enable Alerts Provider
++++++++++++++++++++++++
+
+TBD.
+
 Required IAM Policy
 +++++++++++++++++++
 

docs/source/development.rst

@@ -215,7 +215,7 @@ configuration items via constructor keyword arguments and implement a
 It is probably easiest to look at the other existing providers for an example of how to
 implement a new one, but there are a few important things to keep in mind:
 
-* All configuration must be able to be bassed as keyword arguments to the class
+* All configuration must be able to be passed as keyword arguments to the class
   constructor (which come from ``--metrics-config=key=value`` CLI arguments).
   It is recommended that any secrets/API keys also be able to be set via
   environment variables, but the CLI arguments should have precedence.
@@ -227,6 +227,33 @@ implement a new one, but there are a few important things to keep in mind:
   possible.
 * Metrics provider classes should be in a module with the same name.
 
+.. _development.alert_providers:
+
+Adding Alert Providers
+------------------------
+
+Alert providers are subclasses of :py:class:`~.AlertProvider` that take key/value
+configuration items via constructor keyword arguments and implement three methods
+for sending alerts depending on the type of situation: :py:meth:`~.AlertProvider.on_warning`
+for runs that resulted in warning thresholds crossed, :py:meth:`~.AlertProvider.on_critical`
+for runs that resulted in critical thresholds crossed or raised an exception, or
+:py:meth:`~.AlertProvider.on_success` for successful runs with no thresholds crossed
+(mainly for automatically resolving incidents, when supported).
+It is probably easiest to look at the other existing providers for an example of how to
+implement a new one, but there are a few important things to keep in mind:
+
+* All configuration must be able to be passed as keyword arguments to the class
+  constructor (which come from ``--alert-config=key=value`` CLI arguments).
+  It is recommended that any secrets/API keys also be able to be set via
+  environment variables, but the CLI arguments should have precedence.
+* All dependency imports must be made inside the constructor, not at the module
+  level.
+* If the provider requires additional dependencies, they should be added as
+  extras but installed in the Docker image.
+* The constructor should do as much validation (i.e. authentication test) as
+  possible.
+* Alert provider classes should be in a module with the same name.
+
 .. _development.tests:
 
 Unit Testing

docs/source/getting_started.rst

@@ -24,6 +24,7 @@ What It Does
   :ref:`Getting Started - Trusted Advisor <getting_started.trusted_advisor>`
   for more information.
 - Optionally send current usage and limit metrics to a :ref:`metrics store <cli_usage.metrics>` such as Datadog.
+- Optionally send warning/critical alerts to an :ref:`alert provider <cli_usage.alerts>`, such as PagerDuty.
 
 .. _getting_started.nomenclature: