Merge pull request #113 from fourTheorem/resource-customisation

Allow resource alarm customisation
fourTheorem · Jan 22, 2024 · e73dd0f · e73dd0f
2 parents 2a063f0 + 66e5077
commit e73dd0f
Show file tree

Hide file tree

Showing 92 changed files with 17,334 additions and 14,685 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -17,8 +17,8 @@ jobs:
         node-version: [18, 20]
 
     steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-node@v3
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}.x
           cache: 'npm'

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -19,9 +19,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@master
+        uses: actions/checkout@v4
       - name: Set up Node.js
-        uses: actions/setup-node@v2
+        uses: actions/setup-node@v4
         with:
           node-version: 18.x
           registry-url: "https://registry.npmjs.org"

diff --git a/README.md b/README.md
@@ -36,7 +36,7 @@ Supported tools include:
     - [AppSync](#appsync)
   - [Configuration](#configuration)
     - [Top-level configuration](#top-level-configuration)
-    - [Function-level configuration](#function-level-configuration)
+    - [Resource-level configuration](#resource-level-configuration)
       - [Serverless Framework function-level configuration](#serverless-framework-function-level-configuration)
       - [SAM/CloudFormation function-level configuration](#samcloudformation-function-level-configuration)
       - [CDK function-level configuration](#cdk-function-level-configuration)
@@ -133,7 +133,7 @@ Metadata:
 ```
 See the [Configuration](#configuration) section below for more detailed instructions on fine tuning SLIC Watch to your needs.
 
-If you want to override the default alarm and dashboard settings for each Lambda Functino resource, add the `slicWatch` property to the `Metadata` section.
+If you want to override the default alarm and dashboard settings for each Lambda Function resource, add the `slicWatch` property to the `Metadata` section.
 
 ### Adding the SLIC Watch Transform to CDK Apps
 Once you have deployed the macro, add it to CDK Stack in the constructor of the class that extends Stack. It should be done for every Stack in the CDK App.
@@ -181,7 +181,7 @@ this.templateOptions.metadata = {
 
 ## Features
 
-CloudWatch Alarms and Dashboard widgets are created for all supported resources in the CloudFormation stack generated by The Serverless Framework. This includes generated resources as well as resources specifed explicitly in the `resources` section.
+CloudWatch Alarms and Dashboard widgets are created for all supported resources in the CloudFormation stack generated by The Serverless Framework. This includes generated resources as well as resources specified explicitly in the `resources` section.
 Any feature can be configured or disabled completely - see the section on [configuration](#configuration) to see how.
 
 ### Lambda Functions
@@ -337,10 +337,10 @@ Configuration is entirely optional - SLIC Watch provides defaults that work out
 
 You can customize the configuration:
 - at the top level, for all resources in each service, and/or
-- at the level of individual functions.
+- at the level of individual resources
 
 ### Top-level configuration
-SLIC Watch configuration can be specified:
+Top-level SLIC Watch configuration can be specified for all resources of each type:
 - For *Serverless Framework applications*, in the `custom` → `slicWatch` section of `serverless.yml`:
 ```yaml
 custom:
@@ -366,7 +366,7 @@ this.templateOptions.metadata = {
 }
 ```
 
-- The `alarmActionsConfig` may be optionally added to specifc one or more SNS Topic destinations for all alarm status changes to `ALARM` and `OK`.  If you omit destination topics, alarms are still created but are not sent to any destination. For example:
+- The `alarmActionsConfig` may be optionally added to specific one or more SNS Topic destinations for all alarm status changes to `ALARM` and `OK`.  If you omit destination topics, alarms are still created but are not sent to any destination. For example:
 ```yaml
 slicWatch:
   alarmActionsConfig:
@@ -385,11 +385,53 @@ Example projects are also provided for reference:
 - [serverless-test-project](./serverless-test-project)
 - [sam-test-project](./sam-test-project)
 
-### Function-level configuration
+### Resource-level configuration
 
-For each function, add the `slicWatch` property to configure specific overrides for alarms and dashboards relating to the AWS Lambda Function resource. 
+Alarms and dashboards for each resource can be customised using CloudFormation metadata. This configuration will take precedence over the top-level configuration.
+
+```yaml
+Resources:
+  regularQueue:
+    Type: AWS::SQS::Queue
+    Metadata:
+      slicWatch:
+        alarms:
+          InFlightMessagesPc:
+            Threshold: 95
+        dashboard:
+          ApproximateAgeOfOldestMessage:
+            yAxis: right
+          NumberOfMessagesReceived:
+            enabled: false
+```
+
+This can be done for any CloudFormation, AWS and SAM resource. It can also be done for CDK with the following syntax.
+
+```typescript
+const dlq = new sqs.Queue(this, 'DeadLetterQueue')
+const cfnDlq = dlq.node.defaultChild as CfnResource
+cfnDlq.cfnOptions.metadata = {
+  slicWatch: {
+    alarms: {
+      InFlightMessagesPc: {
+        Threshold: 95
+      }
+    },
+    dashboard: {
+      ApproximateAgeOfOldestMessage: {
+        yAxis: 'right'
+      },
+      NumberOfMessagesReceived: {
+        enabled: false
+      }
+    }
+  }
+}
+```
 
 #### Serverless Framework function-level configuration
+Function-level configuration works a bit differently for Serverless Framework functions. Here, the `slicWatch` configuration parameter is set directly on the function: For each function, add the `slicWatch` property to configure specific overrides for alarms and dashboards relating to the AWS Lambda Function resource. 
+
 ```yaml
 functions:
   hello:
@@ -398,10 +440,9 @@ functions:
       dashboard:
         enabled: false    # No Lambda widgets will be created for this function
       alarms:
-        Lambda:
-          Invocations:
-            Threshold: 2  # The invocation threshold is specific to
-                          # this function's expected invocation count
+        Invocations:
+          Threshold: 2  # The invocation threshold is specific to
+                        # this function's expected invocation count
 ```
 
 To disable all alarms for any given function, use:
@@ -412,8 +453,7 @@ functions:
     handler: basic-handler.hello
     slicWatch:
       alarms:
-        Lambda:
-          enabled: false
+        enabled: false
 ```
 
 #### SAM/CloudFormation function-level configuration
@@ -426,9 +466,8 @@ Resources:
     Metadata:
       slicWatch:
         alarms:
-          Lambda:
-            Invocations:
-              Threshold: 3
+          Invocations:
+            Threshold: 3
         dashboard:
           enabled: true
 ```
@@ -444,20 +483,18 @@ Resources:
     Metadata:
       slicWatch:
         alarms:
-          Lambda:
-            enabled: false
+          enabled: false
 ```
+
 #### CDK function-level configuration
 ```typescript
 const hello: lambda.Function;
 const cfnFuncHello = hello.node.defaultChild as CfnResource;
 cfnFuncHello.cfnOptions.metadata = {
   slicWatch: {
     alarms: {
-      Lambda: {
-        Invocations: {
-          Threshold: 2
-        }
+      Invocations: {
+        Threshold: 2
       }
     }
   }

diff --git a/cdk-test-project/package.json b/cdk-test-project/package.json
@@ -1,6 +1,6 @@
 {
   "name": "cdk-test-project",
-  "version": "3.1.0",
+  "version": "3.2.0-rc2",
   "scripts": {
     "build": "tsc",
     "watch": "tsc -w",

diff --git a/cdk-test-project/source/general-stack.ts b/cdk-test-project/source/general-stack.ts
@@ -55,10 +55,8 @@ export class CdkTestGeneralStack extends cdk.Stack {
     cfnFuncHello.cfnOptions.metadata = {
       slicWatch: {
         alarms: {
-          Lambda: {
-            Invocations: {
-              Threshold: 4
-            }
+          Invocations: {
+            Threshold: 4
           }
         }
       }
@@ -130,5 +128,23 @@ export class CdkTestGeneralStack extends cdk.Stack {
       maxEventAge: cdk.Duration.hours(2), // Optional: set the maxEventAge retry policy
       retryAttempts: 2 // Optional: set the max number of retry attempts
     }))
+    const cfnDlq = dlq.node.defaultChild as CfnResource
+    cfnDlq.cfnOptions.metadata = {
+      slicWatch: {
+        alarms: {
+          InFlightMessagesPc: {
+            Threshold: 95
+          }
+        },
+        dashboard: {
+          ApproximateAgeOfOldestMessage: {
+            yAxis: 'right'
+          },
+          NumberOfMessagesReceived: {
+            enabled: false
+          }
+        }
+      }
+    }
   }
 }
diff --git a/cdk-test-project/source/sfn-stack.ts b/cdk-test-project/source/sfn-stack.ts
@@ -51,10 +51,8 @@ export class CdkSFNStack extends cdk.Stack {
     cfnFuncHello.cfnOptions.metadata = {
       slicWatch: {
         alarms: {
-          Lambda: {
-            Invocations: {
-              Threshold: 4
-            }
+          Invocations: {
+            Threshold: 4
           }
         }
       }

diff --git a/cdk-test-project/tests/snapshot/fixtures/CdkECSStackTest-Europe.template.json b/cdk-test-project/tests/snapshot/fixtures/CdkECSStackTest-Europe.template.json
@@ -853,7 +853,7 @@
   "CDKMetadata": {
    "Type": "AWS::CDK::Metadata",
    "Properties": {
-    "Analytics": "v2:deflate64:H4sIAAAAAAAA/31Ry27CMBD8Fu7GbTlUXCmlCAm1UYK4IsfZpgvBjux1EIry73WepLSqFGlnx+PsembG58/8cSIudiqT0zTDmJcRCXlinjqUIO0hF0RglOWLPM9QCkKttlokLyITSkLyJkwqCCIwBUpgkAlLKDOviBsFqrSY8fLv24YtP3/2Yx1aAtVpejw63/nJQGujXV5LRm3FQPqZEUhnkK6D5H9ilRqw9he9US2/z2V9tg+WLHCxXyJysQJq9AMKtSPYiTiDG3/jFtZqic3yg7gGq01Ql3dBa2/lRVxZYLCoXR1+vFF1CjAI2k26bkE+s68zKKpfbnnZhbIT9vQKn6iwH3nPaEUCva8j7i7Qxo4OZs6n0OTRwYqhOPMy1O17mxpo702zYIsqlunU77TV6eB7j6uq7j4c5Y5YCFY7047sccWUToAf7UPxNOf+m02OFnFqnCI8Aw/b+g3+NWTOyAIAAA=="
+    "Analytics": "v2:deflate64:H4sIAAAAAAAA/31RTU8CMRD9LdxLRQ7GKyISEqMbIF7JbHdcR0q76UwhZrP/3ewHy4rG07x589r5eFN9f6cnIzjx2GT7saVUlxsBs1dw4l2JhncFiGBwrGdFYcmAkHfPHrIHsOAMZk8QchDcYDiSQYUWWMhYD1naKMjlx6ku/34d1Pz9Zz7UEQu6TnPGg/oWQo6yDD4WtWSQVgrNVJcbNDGQfPWS/4lFHpD5F71yLf9WmLr2lsxVElNLZhNTh9Loe7T2UXALqcULf+FmzN5QM3wvrsFildThBWQJgif4UkmgY33V/uOVq13AXtBO0mUzETAfB3RSb8667EzZAu8f8Z0cnVteM94JkMMw4K4Mbc7RQRtZWj86WCmCgy7Xvt23iYm3ZJoBW1Qp63PW5bPP+7ufcVXV2WuUIopaI/sY2pZnXCnnM9SffHOcTvTtRE9Gn0w0DtEJHVCv2/gNbRFl8sgCAAA="
    },
    "Metadata": {
     "aws:cdk:path": "CdkECSStackTest-Europe/CDKMetadata/Default"

diff --git a/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-Europe.template.json b/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-Europe.template.json
@@ -97,10 +97,8 @@
    "Metadata": {
     "slicWatch": {
      "alarms": {
-      "Lambda": {
-       "Invocations": {
-        "Threshold": 4
-       }
+      "Invocations": {
+       "Threshold": 4
       }
      }
     }
@@ -855,7 +853,21 @@
    "UpdateReplacePolicy": "Delete",
    "DeletionPolicy": "Delete",
    "Metadata": {
-    "aws:cdk:path": "CdkGeneralStackTest-Europe/DeadLetterQueue/Resource"
+    "slicWatch": {
+     "alarms": {
+      "InFlightMessagesPc": {
+       "Threshold": 95
+      }
+     },
+     "dashboard": {
+      "ApproximateAgeOfOldestMessage": {
+       "yAxis": "right"
+      },
+      "NumberOfMessagesReceived": {
+       "enabled": false
+      }
+     }
+    }
    }
   },
   "DeadLetterQueuePolicyB1FB890C": {
@@ -903,7 +915,7 @@
   "CDKMetadata": {
    "Type": "AWS::CDK::Metadata",
    "Properties": {
-    "Analytics": "v2:deflate64:H4sIAAAAAAAA/02Q30/DIBDH/5a9M9SZmL12Gp801rr3hdKzshaoPdhsGv53D5izCeE+9z24Xxu+feC3K3HGtWy6da9qPn84ITtG0mFGg3ze20FJ9vhpEgTWC103gs/P3kinrImhJZcwaoVIXmBKaD5XtocYiDYwvD8IRHDIi2jI5zsvO3A7gcDEoFrh4CwmPr+kQhWgKwaVEvxjIaX1xrEnGHo7aSAkdeHRFG2qmoG+Wj9KSEXK0f5Mf8olceZXcF+2iVKmwJrJCG0b2ste1HmOBIHBierQfip/Gc+n8b5Jevfgk5Yh3aXtlZyuYnZDuHbG0jpit8q08dmbd4N3y/YCM7YBfsSb092W09msjqjUeqRNKA28yvYXs0P/r9UBAAA="
+    "Analytics": "v2:deflate64:H4sIAAAAAAAA/02QTU/DMAyGf8vumSmbhLhuIE4gRrf75KamZGuTUjsbVZT/jpKOsUvex68jfy3g8QGKGZ55ruvjvDUVhK2gPio88z6wZQg71xutnj5thqha7KoaIbx4q8U4m1K3vKGhM8zG2agMdhBK11JKJI2Kl3tkJmFYJVG8hLXXR5I1MinsTYNCZxwhvOZGJbGsepML/ONKa+etqGfqWzd2ZCW5N9FWsMldJyiJnR805Sabwf2Mf86l8MRvJF+uTtZEUdWjxc7VFYQdVtMeGaKiE1lhCKW/rOfzet8M4cOTz94E+d241ujxak5hjNfJVD5HmtbYJn1799J7uR0vKutqggPfnRYF3BdQzA5szHzwVkxHUE76CyBn/pPVAQAA"
    },
    "Metadata": {
     "aws:cdk:path": "CdkGeneralStackTest-Europe/CDKMetadata/Default"

diff --git a/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-US.template.json b/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-US.template.json
@@ -97,10 +97,8 @@
    "Metadata": {
     "slicWatch": {
      "alarms": {
-      "Lambda": {
-       "Invocations": {
-        "Threshold": 4
-       }
+      "Invocations": {
+       "Threshold": 4
       }
      }
     }
@@ -855,7 +853,21 @@
    "UpdateReplacePolicy": "Delete",
    "DeletionPolicy": "Delete",
    "Metadata": {
-    "aws:cdk:path": "CdkGeneralStackTest-US/DeadLetterQueue/Resource"
+    "slicWatch": {
+     "alarms": {
+      "InFlightMessagesPc": {
+       "Threshold": 95
+      }
+     },
+     "dashboard": {
+      "ApproximateAgeOfOldestMessage": {
+       "yAxis": "right"
+      },
+      "NumberOfMessagesReceived": {
+       "enabled": false
+      }
+     }
+    }
    }
   },
   "DeadLetterQueuePolicyB1FB890C": {
@@ -903,7 +915,7 @@
   "CDKMetadata": {
    "Type": "AWS::CDK::Metadata",
    "Properties": {
-    "Analytics": "v2:deflate64:H4sIAAAAAAAA/02Q30/DIBDH/5a9M9SZmL12Gp801rr3hdKzshaoPdhsGv53D5izCeE+9z24Xxu+feC3K3HGtWy6da9qPn84ITtG0mFGg3ze20FJ9vhpEgTWC103gs/P3kinrImhJZcwaoVIXmBKaD5XtocYiDYwvD8IRHDIi2jI5zsvO3A7gcDEoFrh4CwmPr+kQhWgKwaVEvxjIaX1xrEnGHo7aSAkdeHRFG2qmoG+Wj9KSEXK0f5Mf8olceZXcF+2iVKmwJrJCG0b2ste1HmOBIHBierQfip/Gc+n8b5Jevfgk5Yh3aXtlZyuYnZDuHbG0jpit8q08dmbd4N3y/YCM7YBfsSb092W09msjqjUeqRNKA28yvYXs0P/r9UBAAA="
+    "Analytics": "v2:deflate64:H4sIAAAAAAAA/02QTU/DMAyGf8vumSmbhLhuIE4gRrf75KamZGuTUjsbVZT/jpKOsUvex68jfy3g8QGKGZ55ruvjvDUVhK2gPio88z6wZQg71xutnj5thqha7KoaIbx4q8U4m1K3vKGhM8zG2agMdhBK11JKJI2Kl3tkJmFYJVG8hLXXR5I1MinsTYNCZxwhvOZGJbGsepML/ONKa+etqGfqWzd2ZCW5N9FWsMldJyiJnR805Sabwf2Mf86l8MRvJF+uTtZEUdWjxc7VFYQdVtMeGaKiE1lhCKW/rOfzet8M4cOTz94E+d241ujxak5hjNfJVD5HmtbYJn1799J7uR0vKutqggPfnRYF3BdQzA5szHzwVkxHUE76CyBn/pPVAQAA"
    },
    "Metadata": {
     "aws:cdk:path": "CdkGeneralStackTest-US/CDKMetadata/Default"

diff --git a/cdk-test-project/tests/snapshot/fixtures/CdkSFNStackTest-Europe.template.json b/cdk-test-project/tests/snapshot/fixtures/CdkSFNStackTest-Europe.template.json
@@ -92,10 +92,8 @@
    "Metadata": {
     "slicWatch": {
      "alarms": {
-      "Lambda": {
-       "Invocations": {
-        "Threshold": 4
-       }
+      "Invocations": {
+       "Threshold": 4
       }
      }
     }
@@ -230,7 +228,7 @@
   "CDKMetadata": {
    "Type": "AWS::CDK::Metadata",
    "Properties": {
-    "Analytics": "v2:deflate64:H4sIAAAAAAAA/11P0UoDQQz8lr7nolaQvtpCoaAgp+Djke6lbbp7u6XZq8iy/+7etoIIgZnJhEwyx8UT3s/oSxvT28bJFtN7JGOhtLqkXjF9hJMYWO18JRkcDdueMK1Hb6IEP1m/PIPQgKkNjqd2xbfgxHxP8soy6GNHqhwVnycoGpejsRyXpAwa+bS77dMuklrFl5q58Zdg/w1g+iSJsCZxsDoEMQzlgcivZA7i6xV/dc7QsobxXOZqeDH34vf12puRwYee8ah3l4cFlprPjirSnEcfZWBsr/gDsE52pTwBAAA="
+    "Analytics": "v2:deflate64:H4sIAAAAAAAA/11OTWvCQBD9Ld4n01RBeq2CUGihJEKPYdyMOibZFWeilGX/e8lqofT0voZ5b44vSyxndNPCtV3Ryw5jbeQ6oJs2Ub1i3IazOFjvfSYJehp2LWHcjN6ZBD9FvzyB0ICxCj1PdsbP0Iv7nuSdJdBFQ6psiq8TgC5wNbqObUXKoMbn/eOfNkbaKb7nzjd/Dd2/A4xfJAYbkh7WxyCOoTYy/iB3FJ9X/NUpQcUaxotjyOW10UH8Ia99BAl8aBlP+nSdl/hcYjk7qUhxGb3JwFjd8QcjaneZPAEAAA=="
    },
    "Metadata": {
     "aws:cdk:path": "CdkSFNStackTest-Europe/CDKMetadata/Default"