Skip to content

Commit

Permalink
chore: update docs for resource-level customisations
Browse files Browse the repository at this point in the history
  • Loading branch information
eoinsha committed Dec 5, 2023
1 parent e1f3b0d commit 2c216eb
Show file tree
Hide file tree
Showing 12 changed files with 335 additions and 162 deletions.
53 changes: 48 additions & 5 deletions README.md
Expand Up @@ -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)
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -447,6 +489,7 @@ Resources:
Lambda:
enabled: false
```

#### CDK function-level configuration
```typescript
const hello: lambda.Function;
Expand Down
18 changes: 18 additions & 0 deletions cdk-test-project/source/general-stack.ts
Expand Up @@ -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
}
}
}
}
}
}
Expand Up @@ -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": {
Expand Down
Expand Up @@ -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": {
Expand Down
11 changes: 11 additions & 0 deletions sam-test-project/template.yaml
Expand Up @@ -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:
Expand Down
Expand Up @@ -60,6 +60,21 @@
"regularQueue": {
"Type": "AWS::SQS::Queue",
"Metadata": {
"slicWatch": {
"alarms": {
"InFlightMessagesPc": {
"Threshold": 95
}
},
"dashboard": {
"ApproximateAgeOfOldestMessage": {
"yAxis": "right"
},
"NumberOfMessagesReceived": {
"enabled": false
}
}
},
"SamResourceId": "regularQueue"
}
},
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down
5 changes: 3 additions & 2 deletions serverless-plugin/serverless-plugin.ts
Expand Up @@ -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 ?? {},
Expand Down
10 changes: 10 additions & 0 deletions serverless-test-project/sls-resources.yml
Expand Up @@ -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"
Expand Down

0 comments on commit 2c216eb

Please sign in to comment.