chore: update docs for resource-level customisations

fourTheorem · Dec 5, 2023 · a764fa8 · a764fa8
1 parent 9d7e152
commit a764fa8
Show file tree

Hide file tree

Showing 12 changed files with 335 additions and 161 deletions.
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)
@@ -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:
@@ -385,11 +385,54 @@ 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
 
+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
+```
 For each function, add the `slicWatch` property to configure specific overrides for alarms and dashboards relating to the AWS Lambda Function resource. 
 
+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:
+
 ```yaml
 functions:
   hello:
@@ -447,6 +490,7 @@ Resources:
           Lambda:
             enabled: false
 ```
+
 #### CDK function-level configuration
 ```typescript
 const hello: lambda.Function;

diff --git a/cdk-test-project/source/general-stack.ts b/cdk-test-project/source/general-stack.ts
@@ -128,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/tests/snapshot/fixtures/CdkGeneralStackTest-Europe.template.json b/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-Europe.template.json
@@ -853,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": {

diff --git a/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-US.template.json b/cdk-test-project/tests/snapshot/fixtures/CdkGeneralStackTest-US.template.json
@@ -853,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": {

diff --git a/sam-test-project/template.yaml b/sam-test-project/template.yaml
@@ -131,6 +131,17 @@ Resources:
       ShardCount: 1
   regularQueue:
     Type: AWS::SQS::Queue
+    Metadata:
+      slicWatch:
+        alarms:
+          InFlightMessagesPc:
+            Threshold: 95
+        dashboard:
+          ApproximateAgeOfOldestMessage:
+            yAxis: right
+          NumberOfMessagesReceived:
+            enabled: false
+
   fifoQueue:
     Type: AWS::SQS::Queue
     Properties:

diff --git a/sam-test-project/tests/snapshot/fixtures/sam-test-project-transformed-template.json b/sam-test-project/tests/snapshot/fixtures/sam-test-project-transformed-template.json
@@ -60,6 +60,21 @@
     "regularQueue": {
       "Type": "AWS::SQS::Queue",
       "Metadata": {
+        "slicWatch": {
+          "alarms": {
+            "InFlightMessagesPc": {
+              "Threshold": 95
+            }
+          },
+          "dashboard": {
+            "ApproximateAgeOfOldestMessage": {
+              "yAxis": "right"
+            },
+            "NumberOfMessagesReceived": {
+              "enabled": false
+            }
+          }
+        },
         "SamResourceId": "regularQueue"
       }
     },
@@ -272,7 +287,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "basic-handler.hello",
         "Role": {
@@ -333,7 +348,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "basic-handler.hello",
         "Role": {
@@ -389,7 +404,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "basic-handler.hello",
         "Role": {
@@ -446,7 +461,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "stream-test-handler.handleDrive",
         "Role": {
@@ -502,7 +517,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "basic-handler.hello",
         "Role": {
@@ -558,7 +573,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "basic-handler.hello",
         "Role": {
@@ -614,7 +629,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "basic-handler.hello",
         "Role": {
@@ -687,7 +702,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "apigw-handler.handleGet",
         "Role": {
@@ -770,7 +785,7 @@
       "Properties": {
         "Code": {
           "S3Bucket": "aws-sam-cli-managed-default-samclisourcebucket-167xnalzxxva4",
-          "S3Key": "sam-test-project/810e2a73503f0ee11a4a06f488e12d55"
+          "S3Key": "sam-test-project/41c0564f2b084a83461942c11a0c2e07"
         },
         "Handler": "rule-handler.handleRule",
         "Role": {

diff --git a/serverless-plugin/serverless-plugin.ts b/serverless-plugin/serverless-plugin.ts
@@ -63,11 +63,12 @@ class ServerlessPlugin {
       // Each Lambda Function declared in serverless.yml may have a slicWatch configuration
       // to set configuration overrides for the specific function. We transform those into
       // CloudFormation Metadata on the generate AWS::Lambda::Function resource
-      for (const funcName of this.serverless.service.getAllFunctions()) {
+      const allFunctions = this.serverless.service.getAllFunctions() as string[]
+      this.serverless.cli.log(`Setting SLIC Watch configuration for ${allFunctions}`)
+      for (const funcName of allFunctions) {
         const func = this.serverless.service.getFunction(funcName) as any
         const funcConfig = func.slicWatch ?? {}
         const functionLogicalId = awsProvider.naming.getLambdaLogicalId(funcName)
-
         const templateResources = compiledTemplate.Resources as Record<string, Resource>
         templateResources[functionLogicalId].Metadata = {
           ...templateResources[functionLogicalId].Metadata ?? {},

diff --git a/serverless-test-project/sls-resources.yml b/serverless-test-project/sls-resources.yml
@@ -59,6 +59,16 @@ Resources:
             NonKeyAttributes:
               - name
             ProjectionType: INCLUDE
+    Metadata:
+      slicWatch:
+        alarms:
+          UserErrors:
+            Threshold: 20
+        dashboard:
+          ReadThrottleEvents:
+            yAxis: right
+          WriteThrottleEvents:
+            yAxis: right
 
   regularQueue:
     Type: "AWS::SQS::Queue"