Issue #418 - Metrics provider documentation

README.rst

@@ -101,6 +101,7 @@ What It Does
   an optional maximum time limit). See
   `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.
 
 Requirements
 ------------

docs/build_generated_docs.py

@@ -51,10 +51,12 @@
 sys.path.insert(0, os.path.join(my_dir, '..'))
 
 from awslimitchecker.checker import AwsLimitChecker
+from awslimitchecker.metrics import MetricsProvider
 
 logger = logging.getLogger()
 logging.basicConfig(level=logging.INFO)
 
+
 def build_iam_policy(checker):
     logger.info("Beginning build of iam_policy.rst")
     # get the policy dict
@@ -77,6 +79,13 @@ def build_iam_policy(checker):
     Required IAM Permissions
     ========================
 
+    .. important::
+       The required IAM policy output by awslimitchecker includes only the permissions
+       required to check limits and usage. If you are loading
+       :ref:`limit overrides <cli_usage.limit_overrides>` and/or
+       :ref:`threshold overrides <cli_usage.threshold_overrides>` from S3, you will
+       need to run awslimitchecker with additional permissions to access those objects.
+
     Below is the sample IAM policy from this version of awslimitchecker, listing the IAM
     permissions required for it to function correctly. Please note that in some cases
     awslimitchecker may cause AWS services to make additional API calls on your behalf
@@ -97,6 +106,7 @@ def build_iam_policy(checker):
     with open(fname, 'w') as fh:
         fh.write(doc)
 
+
 def build_limits(checker):
     logger.info("Beginning build of limits.rst")
     logger.info("Getting Limits")
@@ -202,6 +212,7 @@ def build_limits(checker):
     with open(fname, 'w') as fh:
         fh.write(doc)
 
+
 def build_runner_examples():
     logger.info("Beginning build of runner examples")
     # read in the template file
@@ -225,7 +236,8 @@ def build_runner_examples():
         'check_thresholds': ['awslimitchecker', '--no-color'],
         'check_thresholds_custom': ['awslimitchecker', '-W', '97',
                                     '--critical=98', '--no-color'],
-        'iam_policy': ['awslimitchecker', '--iam-policy']
+        'iam_policy': ['awslimitchecker', '--iam-policy'],
+        'list_metrics': ['awslimitchecker', '--list-metrics-providers'],
     }
     results = {}
     # run the commands
@@ -238,13 +250,66 @@ def build_runner_examples():
             output = e.output
         results[name] = format_cmd_output(cmd_str, output, name)
         results['%s-output-only' % name] = format_cmd_output(None, output, name)
+    results['metrics-providers'] = ''
+    for m in MetricsProvider.providers_by_name().keys():
+        results['metrics-providers'] += '* :py:class:`~.%s`\n' % m
+    results['limit-override-json'] = dedent("""
+        {
+            "AutoScaling": {
+                "Auto Scaling groups": 321,
+                "Launch configurations": 456
+            }
+        }
+    """)
+    results['threshold-override-json'] = dedent("""
+        {
+            "S3": {
+                "Buckets": {
+                    "warning": {
+                        "percent": 97
+                    },
+                    "critical": {
+                        "percent": 99
+                    }
+                }
+            },
+            "EC2": {
+                "Security groups per VPC": {
+                    "warning": {
+                        "percent": 80,
+                        "count": 800
+                    },
+                    "critical": {
+                        "percent": 90,
+                        "count": 900
+                    }
+                },
+                "VPC security groups per elastic network interface": {
+                    "warning": {
+                        "percent": 101
+                    },
+                    "critical": {
+                        "percent": 101
+                    }
+                }
+            }
+        }
+    """)
+    for x in ['limit-override-json', 'threshold-override-json']:
+        tmp = ''
+        for line in results[x].split('\n'):
+            if line.strip() == '':
+                continue
+            tmp += '    %s\n' % line
+        results[x] = tmp
     tmpl = tmpl.format(**results)
 
     # write out the final .rst
     with open(os.path.join(my_dir, 'source', 'cli_usage.rst'), 'w') as fh:
         fh.write(tmpl)
     logger.critical("WARNING - some output may need to be fixed to provide good examples")
 
+
 def format_cmd_output(cmd, output, name):
     """format command output for docs"""
     if cmd is None:
@@ -259,7 +324,7 @@ def format_cmd_output(cmd, output, name):
                 lines[idx] = line[:100] + ' (...)'
         if len(lines) > 12:
             tmp_lines = lines[:5] + ['(...)'] + lines[-5:]
-            if ' -l' in cmd or ' --list-defaults' in cmd:
+            if cmd is not None and (' -l' in cmd or ' --list-defaults' in cmd):
                 # find a line that uses a limit from the API,
                 #  and a line with None (unlimited)
                 api_line = None
@@ -291,6 +356,7 @@ def format_cmd_output(cmd, output, name):
     formatted += '\n'
     return formatted
 
+
 def build_docs():
     """
     Trigger rebuild of all documentation that is dynamically generated
@@ -309,5 +375,6 @@ def build_docs():
     build_limits(c)
     build_runner_examples()
 
+
 if __name__ == "__main__":
     build_docs()

docs/source/awslimitchecker.metrics.datadog.rst

@@ -0,0 +1,7 @@
+awslimitchecker.metrics.datadog module
+======================================
+
+.. automodule:: awslimitchecker.metrics.datadog
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/awslimitchecker.metrics.rst

@@ -12,5 +12,6 @@ Submodules
 .. toctree::
 
    awslimitchecker.metrics.base
+   awslimitchecker.metrics.datadog
    awslimitchecker.metrics.dummy
 

docs/source/cli_usage.rst

@@ -26,15 +26,20 @@ use as a Nagios-compatible plugin).
    (venv)$ awslimitchecker --help
    usage: awslimitchecker [-h] [-S [SERVICE [SERVICE ...]]]
                           [--skip-service SKIP_SERVICE] [--skip-check SKIP_CHECK]
-                          [-s] [-l] [--list-defaults] [-L LIMIT] [-u]
-                          [--iam-policy] [-W WARNING_THRESHOLD]
+                          [-s] [-l] [--list-defaults] [-L LIMIT]
+                          [--limit-override-json LIMIT_OVERRIDE_JSON]
+                          [--threshold-override-json THRESHOLD_OVERRIDE_JSON]
+                          [-u] [--iam-policy] [-W WARNING_THRESHOLD]
                           [-C CRITICAL_THRESHOLD] [-P PROFILE_NAME]
                           [-A STS_ACCOUNT_ID] [-R STS_ACCOUNT_ROLE]
                           [-E EXTERNAL_ID] [-M MFA_SERIAL_NUMBER] [-T MFA_TOKEN]
                           [-r REGION] [--skip-ta]
                           [--ta-refresh-wait | --ta-refresh-trigger | --ta-refresh-older TA_REFRESH_OLDER]
                           [--ta-refresh-timeout TA_REFRESH_TIMEOUT] [--no-color]
                           [--no-check-version] [-v] [-V]
+                          [--list-metrics-providers]
+                          [--metrics-provider METRICS_PROVIDER]
+                          [--metrics-config METRICS_CONFIG]
    Report on AWS service limits and usage via boto3, optionally warn about any
    services with usage nearing or exceeding their limits. For further help, see
    <http://awslimitchecker.readthedocs.org/>
@@ -58,6 +63,14 @@ use as a Nagios-compatible plugin).
                            override a single AWS limit, specified in
                            "service_name/limit_name=value" format; can be
                            specified multiple times.
+     --limit-override-json LIMIT_OVERRIDE_JSON
+                           Absolute or relative path, or s3:// URL, to a JSON
+                           file specifying limit overrides. See docs for expected
+                           format.
+     --threshold-override-json THRESHOLD_OVERRIDE_JSON
+                           Absolute or relative path, or s3:// URL, to a JSON
+                           file specifying threshold overrides. See docs for
+                           expected format.
      -u, --show-usage      find and print the current usage of all AWS services
                            with known limits
      --iam-policy          output a JSON serialized IAM Policy listing the
@@ -108,6 +121,14 @@ use as a Nagios-compatible plugin).
      --no-check-version    do not check latest version at startup
      -v, --verbose         verbose output. specify twice for debug-level output.
      -V, --version         print version number and exit.
+     --list-metrics-providers
+                           List available metrics providers and exit
+     --metrics-provider METRICS_PROVIDER
+                           Metrics provider class name, to enable sending metrics
+     --metrics-config METRICS_CONFIG
+                           Specify key/value parameters for the metrics provider
+                           constructor. See documentation for further
+                           information.
    awslimitchecker is AGPLv3-licensed Free Software. Anyone using this program,
    even remotely over a network, is entitled to a copy of the source code. Use
    `--version` for information on the source code location.
@@ -445,6 +466,7 @@ You can also set custom thresholds on a per-limit basis using the
         }
     }
 
+
 Using a command like:
 
 .. code-block:: console
@@ -460,6 +482,48 @@ Using a command like:
    VPC/NAT Gateways per AZ                                (limit 5) CRITICAL: us-east-1d=7, us-east-1c= (...)
    VPC/Virtual private gateways                           (limit 5) CRITICAL: 5
 
+
+
+.. _cli_usage.metrics:
+
+Enable Metrics Provider
++++++++++++++++++++++++
+
+awslimitchecker is capable of sending metrics for the overall runtime of checking
+thresholds, as well as the current limit values and current usage, to various metrics
+stores. The list of metrics providers supported by your version of awslimitchecker
+can be seen with the ``--list-metrics-providers`` option:
+
+.. code-block:: console
+
+   (venv)$ awslimitchecker --list-metrics-providers
+   Available metrics providers:
+   Datadog
+   Dummy
+
+
+
+The configuration options required by each metrics provider are specified in the
+providers' documentation:
+
+* :py:class:`~.Dummy`
+* :py:class:`~.Datadog`
+
+
+For example, to use the :py:class:`~awslimitchecker.metrics.datadog.Datadog`
+metrics provider which requires an ``api_key`` paramater (also accepted as an
+environment variable) and an optional ``extra_tags`` parameter:
+
+.. code-block:: console
+
+    (venv)$ awslimitchecker \
+        --metrics-provider=Datadog \
+        --metrics-config=api_key=123456 \
+        --metrics-config=extra_tags=foo,bar,baz:blam
+
+Metrics will be pushed to the provider only when awslimitchecker is done checking
+all limits.
+
 Required IAM Policy
 +++++++++++++++++++
 
@@ -474,13 +538,15 @@ permissions for it to perform all limit checks. This can be viewed with the
      "Statement": [
        {
          "Action": [
-           "apigateway:GET", 
+           "apigateway:GET",
    (...)
        }
-     ], 
+     ],
      "Version": "2012-10-17"
    }
 
+
+
 For the current IAM Policy required by this version of awslimitchecker,
 see :ref:`IAM Policy <iam_policy>`.
 

docs/source/cli_usage.rst.template

@@ -144,12 +144,7 @@ You could also set the same limit overrides using a JSON file stored at ``limit_
 
 .. code-block:: json
 
-    {
-        "AutoScaling": {
-            "Auto Scaling groups": 321,
-            "Launch configurations": 456
-        }
-    }
+{limit-override-json}
 
 Using a command like:
 
@@ -199,38 +194,7 @@ You can also set custom thresholds on a per-limit basis using the
 
 .. code-block:: json
 
-    {
-        "S3": {
-            "Buckets": {
-                "warning": {
-                    "percent": 97
-                },
-                "critical": {
-                    "percent": 99
-                }
-            }
-        },
-        "EC2": {
-            "Security groups per VPC": {
-                "warning": {
-                    "percent": 80,
-                    "count": 800
-                },
-                "critical": {
-                    "percent": 90,
-                    "count": 900
-                }
-            },
-            "VPC security groups per elastic network interface": {
-                "warning": {
-                    "percent": 101
-                },
-                "critical": {
-                    "percent": 101
-                }
-            }
-        }
-    }
+{threshold-override-json}
 
 Using a command like:
 
@@ -239,6 +203,37 @@ Using a command like:
    (venv)$ awslimitchecker -W 97 --critical=98 --no-color --threshold-overrides-json=s3://bucketname/path/overrides.json
 {check_thresholds_custom-output-only}
 
+.. _cli_usage.metrics:
+
+Enable Metrics Provider
++++++++++++++++++++++++
+
+awslimitchecker is capable of sending metrics for the overall runtime of checking
+thresholds, as well as the current limit values and current usage, to various metrics
+stores. The list of metrics providers supported by your version of awslimitchecker
+can be seen with the ``--list-metrics-providers`` option:
+
+{list_metrics}
+
+The configuration options required by each metrics provider are specified in the
+providers' documentation:
+
+{metrics-providers}
+
+For example, to use the :py:class:`~awslimitchecker.metrics.datadog.Datadog`
+metrics provider which requires an ``api_key`` paramater (also accepted as an
+environment variable) and an optional ``extra_tags`` parameter:
+
+.. code-block:: console
+
+    (venv)$ awslimitchecker \
+        --metrics-provider=Datadog \
+        --metrics-config=api_key=123456 \
+        --metrics-config=extra_tags=foo,bar,baz:blam
+
+Metrics will be pushed to the provider only when awslimitchecker is done checking
+all limits.
+
 Required IAM Policy
 +++++++++++++++++++