From 99300358caa1c7b02669e1b94d02096ee3a00e1d Mon Sep 17 00:00:00 2001 From: Jason Antman Date: Wed, 4 Sep 2019 13:58:46 -0400 Subject: [PATCH] Issue #419 - WIP docs --- README.rst | 1 + docs/source/cli_usage.rst | 7 +++++++ docs/source/cli_usage.rst.template | 7 +++++++ docs/source/development.rst | 29 ++++++++++++++++++++++++++++- docs/source/getting_started.rst | 1 + 5 files changed, 44 insertions(+), 1 deletion(-) diff --git a/README.rst b/README.rst index a7d72d76..ce8b6325 100644 --- a/README.rst +++ b/README.rst @@ -102,6 +102,7 @@ What It Does `Getting Started - 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 ------------ diff --git a/docs/source/cli_usage.rst b/docs/source/cli_usage.rst index 132d63a9..bb5e4698 100644 --- a/docs/source/cli_usage.rst +++ b/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 +++++++++++++++++++ diff --git a/docs/source/cli_usage.rst.template b/docs/source/cli_usage.rst.template index 1060daf2..397b7378 100644 --- a/docs/source/cli_usage.rst.template +++ b/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 +++++++++++++++++++ diff --git a/docs/source/development.rst b/docs/source/development.rst index 1bd22a04..202bf87d 100644 --- a/docs/source/development.rst +++ b/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 diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst index 5ef597b4..a9ea82a7 100644 --- a/docs/source/getting_started.rst +++ b/docs/source/getting_started.rst @@ -24,6 +24,7 @@ What It Does :ref:`Getting Started - Trusted Advisor ` for more information. - Optionally send current usage and limit metrics to a :ref:`metrics store ` such as Datadog. +- Optionally send warning/critical alerts to an :ref:`alert provider `, such as PagerDuty. .. _getting_started.nomenclature: