feat: support OK actions for alarms

.gitignore

@@ -260,3 +260,5 @@ lerna-debug*
 
 samconfig.toml
 packaged.yaml
+.tgz
+*.tar.gz

README.md

@@ -65,7 +65,9 @@ so you can receive alarm notifications via email, Slack, etc.
 ```yaml
 custom:
  slicWatch:
- topicArn: {'Fn::Ref': myTopic}
+ alarmActionsConfig: {
+ alarmActions: [{'Fn::Ref': myTopic}]
+ }
 ```
 See the [Configuration](#configuration) section below for more detailed instructions on fine tuning SLIC Watch to your needs.
 
@@ -125,7 +127,9 @@ so you can receive alarm notifications via email, Slack, etc.
 Metadata:
  slicWatch:
  enabled: true
- topicArn: !Ref MonitoringTopic
+ alarmActionsConfig:
+ alarmActions:
+ - !Ref MonitoringTopic
 ```
 See the [Configuration](#configuration) section below for more detailed instructions on fine tuning SLIC Watch to your needs.
 
@@ -166,7 +170,11 @@ this.addTransform("SlicWatch-v3");
 this.templateOptions.metadata = {
  slicWatch: {
  enabled: true,
- topicArn: "arn:aws:sns:eu-west-1:xxxxxxx:topic",
+ alarmActionsConfig: {
+ alarmActions: ["arn:aws:sns:eu-west-1:xxxxxxx:topic"],
+ okActions: ["arn:aws:sns:eu-west-1:xxxxxxx:topic"],
+ actionsEnabled: true
+ }
  }
 }
 ```
@@ -358,7 +366,17 @@ this.templateOptions.metadata = {
 }
 ```
 
-- The `topicArn` may be optionally provided as an SNS Topic destination for all alarms. If you omit the topic, alarms are still created but are not sent to any destination.
+- 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:
+```yaml
+slicWatch:
+ alarmActionsConfig:
+ alarmActions: # Default to no actions
+ - arn:aws:sns:eu-west-1:123456789012
+ okActions: # Defaults to no actions
+ - arn:aws:sns:eu-west-1:123456789012
+ actionsEnabled: 
+ - true # Defaults to true
+```
 - Alarms or dashboards can be disabled at any level in the configuration by adding `enabled: false`. You can even disable all plugin functionality by specifying `enabled: false` at the top-level plugin configuration.
 
 A complete set of supported options along with their defaults are shown in [default-config.js](./core/default-config.js)

cdk-test-project/source/ecs-stack.ts

@@ -10,7 +10,7 @@ export class CdkECSStack extends cdk.Stack {
  this.templateOptions.metadata = {
  slicWatch: {
  enabled: true,
- // "topicArn": "arn:aws:xxxxxx:mytopic",
+ // alarmActionsConfig: { alarmActions: ["arn:aws:xxxxxx:mytopic"] },
  alarms: {
  Lambda: {
  Invocations: {

cdk-test-project/source/general-stack.ts

@@ -40,7 +40,9 @@ export class CdkTestGeneralStack extends cdk.Stack {
  }
 
  const topic = new sns.Topic(this, 'MyTopic')
- this.templateOptions.metadata.slicWatch.topicArn = topic.topicArn
+ this.templateOptions.metadata.slicWatch.alarmActionsConfig = {
+ alarmActions: topic.topicArn
+ }
 
  const helloFunction = new lambda.Function(this, 'HelloHandler',
  {

cf-macro/index.ts

@@ -1,9 +1,9 @@
 import _ from 'lodash'
-import Ajv from 'ajv'
 import pino from 'pino'
 
-import { addAlarms, addDashboard, defaultConfig, slicWatchSchema, getResourcesByType } from '../core/index'
+import { addAlarms, addDashboard, getResourcesByType } from '../core/index'
 import { setLogger } from 'slic-watch-core/logging'
+import { type SlicWatchConfig, resolveSlicWatchConfig } from 'slic-watch-core/inputs/general-config'
 
 const logger = pino({ name: 'macroHandler' })
 setLogger(logger)
@@ -14,65 +14,44 @@ interface Event {
  fragment
 }
 
-interface SlicWatchConfig {
- topicArn?: string
- enabled?: boolean
-}
-
 // macro requires handler to be async
 export async function handler (event: Event) {
  let status = 'success'
+ let errorMessage: string | undefined
+
  logger.info({ event })
  const outputFragment = event.fragment
  try {
  const slicWatchConfig: SlicWatchConfig = outputFragment.Metadata?.slicWatch ?? {}
- if (slicWatchConfig.enabled !== false) {
- const ajv = new Ajv({
- unicodeRegExp: false
- })
- const config = _.merge(defaultConfig, slicWatchConfig)
-
- const slicWatchValidate = ajv.compile(slicWatchSchema)
- const slicWatchValid = slicWatchValidate(slicWatchConfig)
-
- if (!slicWatchValid) {
- throw new Error('SLIC Watch configuration is invalid: ' + ajv.errorsText(slicWatchValidate.errors))
- }
 
- const alarmActions: string[] = []
- slicWatchConfig?.topicArn != null && alarmActions.push(slicWatchConfig.topicArn)
- process.env.ALARM_SNS_TOPIC != null && alarmActions.push(process.env.ALARM_SNS_TOPIC)
+ const config = resolveSlicWatchConfig(slicWatchConfig)
 
- const context = {
- alarmActions
- }
- const functionAlarmConfigs = {}
- const functionDashboardConfigs = {}
+ const functionAlarmConfigs = {}
+ const functionDashboardConfigs = {}
 
- const lambdaResources = getResourcesByType(
- 'AWS::Lambda::Function',
- outputFragment
- )
+ const lambdaResources = getResourcesByType('AWS::Lambda::Function', outputFragment)
 
- for (const [funcResourceName, funcResource] of Object.entries(lambdaResources)) {
- const funcConfig = funcResource.Metadata?.slicWatch ?? {}
- functionAlarmConfigs[funcResourceName] = funcConfig.alarms ?? {}
- functionDashboardConfigs[funcResourceName] = funcConfig.dashboard
- }
-
- _.merge(outputFragment)
- addAlarms(config.alarms, functionAlarmConfigs, context, outputFragment)
- addDashboard(config.dashboard, functionDashboardConfigs, outputFragment)
+ for (const [funcResourceName, funcResource] of Object.entries(lambdaResources)) {
+ const funcConfig = funcResource.Metadata?.slicWatch ?? {}
+ functionAlarmConfigs[funcResourceName] = funcConfig.alarms ?? {}
+ functionDashboardConfigs[funcResourceName] = funcConfig.dashboard
  }
+
+ _.merge(outputFragment)
+ addAlarms(config.alarms, functionAlarmConfigs, config.alarmActionsConfig, outputFragment)
+ addDashboard(config.dashboard, functionDashboardConfigs, outputFragment)
  } catch (err) {
  logger.error(err)
+ errorMessage = (err as Error).message
  status = 'fail'
  }
+
  logger.info({ outputFragment })
 
  return {
- requestId: event.requestId,
  status,
+ errorMessage,
+ requestId: event.requestId,
  fragment: outputFragment
  }
 }

cf-macro/tests/index.test.ts

@@ -15,18 +15,9 @@ test('macro returns success', async t => {
  t.end()
 })
 
-test('macro uses SNS Topic environment variable if specified', async t => {
- process.env.ALARM_SNS_TOPIC = 'arn:aws:sns:eu-west-1:123456789123:TestTopic'
- try {
- const result = await handler(event)
- t.equal(result.status, 'success')
- } finally {
- delete process.env.ALARM_SNS_TOPIC
- }
- t.end()
-})
-
 test('macro uses topicArn if specified', async t => {
+ const topicArn = 'arn:aws:sns:eu-west-1:123456789123:TestTopic'
+
  const eventWithTopic = {
  ...event,
  fragment: {
@@ -35,13 +26,18 @@ test('macro uses topicArn if specified', async t => {
  ...event.fragment.Metadata,
  slicWatch: {
  ...event.fragment.Metadata?.slicWatch,
- topicArn: 'arn:aws:sns:eu-west-1:123456789123:TestTopic'
+ alarmActionsConfig: {
+ alarmActions: [topicArn],
+ okActions: [topicArn]
+ }
  }
  }
  }
  }
  const result = await handler(eventWithTopic)
  t.equal(result.status, 'success')
+ t.notOk(result.errorMessage)
+ t.same(result.fragment.Resources.slicWatchLambdaDurationAlarmHelloLambdaFunction.Properties.AlarmActions, [topicArn])
  t.end()
 })
 
@@ -78,6 +74,7 @@ test('Macro execution fails if an invalid SLIC Watch config is provided', async
  testevent.fragment.Metadata = { slicWatch: { topicArrrrn: 'pirateTopic' } }
  const result = await handler(testevent)
  t.equal(result.status, 'fail')
+ t.ok(result.errorMessage)
  t.end()
 })
 
@@ -91,6 +88,7 @@ test('Macro execution succeeds with no slicWatch config', t => {
 test('Macro execution succeeds if no SNS Topic is provided', t => {
  const testevent = _.cloneDeep(event)
  delete testevent.fragment.Metadata?.slicWatch.topicArn
+ delete testevent.fragment.Metadata?.slicWatch.alarmActionsConfig
  handler(testevent)
  t.end()
 })

core/alarms/alarm-types.ts

@@ -40,7 +40,9 @@ export interface ReturnAlarm {
 }
 
 export interface AlarmActionsConfig {
- alarmActions: string[]
+ actionsEnabled?: boolean
+ okActions?: string[]
+ alarmActions?: string[]
 }
 
 export interface SlicWatchCascadedAlarmsConfig<T extends InputOutput> extends AlarmProperties {

core/alarms/alarm-utils.ts

@@ -70,17 +70,18 @@ export function createCfAlarms (
  * Create a CloudFormation Alarm resourc
  *
  * @param alarmProperties The alarm configuration for this specific resource type
- * @param context Alarm actions
+ * @param alarmActionsConfig Alarm actions
  *
  * @returns An template object for the Cloudformation alarm
  */
 
-export function createAlarm (alarmProperties: AlarmProperties, context?: AlarmActionsConfig): AlarmTemplate {
+export function createAlarm (alarmProperties: AlarmProperties, alarmActionsConfig?: AlarmActionsConfig): AlarmTemplate {
  return {
  Type: 'AWS::CloudWatch::Alarm',
  Properties: {
- ActionsEnabled: true,
- AlarmActions: context?.alarmActions,
+ ActionsEnabled: alarmActionsConfig?.actionsEnabled,
+ AlarmActions: alarmActionsConfig?.alarmActions,
+ OKActions: alarmActionsConfig?.okActions,
  ...alarmProperties
  }
  }

core/alarms/alb-target-group.ts

@@ -81,7 +81,7 @@ export function findLoadBalancersForTargetGroup (targetGroupLogicalId: string, c
  * @param metrics The Target Group metric names
  * @param loadBalancerLogicalIds The CloudFormation Logical IDs of the ALB resource
  * @param albTargetAlarmsConfig The fully resolved alarm configuration
- * @param alarmActionsConfig Deployment context (alarmActions)
+ * @param alarmActionsConfig Notification configuration for alarm status change events
  *
  * @returns ALB Target Group-specific CloudFormation Alarm resources
  */
@@ -120,23 +120,23 @@ function createAlbTargetCfAlarm (
  * based on the resources found within
  *
  * @param albTargetAlarmsConfig The fully resolved alarm configuration
- * @param context Deployment context (alarmActions)
+ * @param alarmActionsConfig Notification configuration for alarm status change events
  * @param compiledTemplate A CloudFormation template object
  *
  * @returns ALB Target Group-specific CloudFormation Alarm resources
  */
 export default function createAlbTargetAlarms (
- albTargetAlarmsConfig: SlicWatchAlbTargetAlarmsConfig<SlicWatchMergedConfig>, context: AlarmActionsConfig, compiledTemplate: Template
+ albTargetAlarmsConfig: SlicWatchAlbTargetAlarmsConfig<SlicWatchMergedConfig>, alarmActionsConfig: AlarmActionsConfig, compiledTemplate: Template
 ): CloudFormationResources {
  const targetGroupResources = getResourcesByType('AWS::ElasticLoadBalancingV2::TargetGroup', compiledTemplate)
  const resources: CloudFormationResources = {}
  for (const [targetGroupResourceName, targetGroupResource] of Object.entries(targetGroupResources)) {
  const loadBalancerLogicalIds = findLoadBalancersForTargetGroup(targetGroupResourceName, compiledTemplate)
- Object.assign(resources, createAlbTargetCfAlarm(targetGroupResourceName, executionMetrics, loadBalancerLogicalIds, albTargetAlarmsConfig, context))
+ Object.assign(resources, createAlbTargetCfAlarm(targetGroupResourceName, executionMetrics, loadBalancerLogicalIds, albTargetAlarmsConfig, alarmActionsConfig))
 
  if (targetGroupResource.Properties?.TargetType === 'lambda') {
  // Create additional alarms for Lambda-specific ALB metrics
- Object.assign(resources, createAlbTargetCfAlarm(targetGroupResourceName, executionMetricsLambda, loadBalancerLogicalIds, albTargetAlarmsConfig, context))
+ Object.assign(resources, createAlbTargetCfAlarm(targetGroupResourceName, executionMetricsLambda, loadBalancerLogicalIds, albTargetAlarmsConfig, alarmActionsConfig))
  }
  }
  return resources

core/alarms/alb.ts

@@ -34,20 +34,20 @@ function createAlbAlarmCfProperties (metric: string, albLogicalId: string, confi
  * based on the resources found within
  *
  * @param albAlarmsConfig The fully resolved alarm configuration
- * @param context Deployment context (alarmActions)
+ * @param alarmActionsConfig Notification configuration for alarm status change events
  * @param compiledTemplate A CloudFormation template object
  *
  * @returns ALB-specific CloudFormation Alarm resources
  */
 export default function createAlbAlarms (
- albAlarmsConfig: SlicWatchAlbAlarmsConfig<SlicWatchMergedConfig>, context: AlarmActionsConfig, compiledTemplate: Template
+ albAlarmsConfig: SlicWatchAlbAlarmsConfig<SlicWatchMergedConfig>, alarmActionsConfig: AlarmActionsConfig, compiledTemplate: Template
 ): CloudFormationResources {
  return createCfAlarms(
  'AWS::ElasticLoadBalancingV2::LoadBalancer',
  'LoadBalancer',
  executionMetrics,
  albAlarmsConfig,
- context,
+ alarmActionsConfig,
  compiledTemplate,
  createAlbAlarmCfProperties
  )

core/alarms/api-gateway.ts

@@ -74,7 +74,7 @@ const executionMetrics = ['5XXError', '4XXError', 'Latency']
  * Add all required API Gateway REST API alarms to the provided CloudFormation template based on the resources found within
  *
  * @param apiGwAlarmsConfig The fully resolved alarm configuration
- * @param alarmActionsConfig Deployment context (alarmActions)
+ * @param alarmActionsConfig Notification configuration for alarm status change events
  * @param compiledTemplate A CloudFormation template object
  *
  * @returns API Gateway-specific CloudFormation Alarm resources

core/alarms/appsync.ts

@@ -18,7 +18,7 @@ const executionMetrics = ['5XXError', 'Latency']
  * based on the AppSync resources found within
  *
  * @param appSyncAlarmsConfig The fully resolved alarm configuration
- * @param alarmActionsConfig Deployment context (alarmActions)
+ * @param alarmActionsConfig Notification configuration for alarm status change events
  * @param compiledTemplate A CloudFormation template object
  *
  * @returns AppSync-specific CloudFormation Alarm resources

core/alarms/dynamodb.ts

@@ -21,13 +21,13 @@ const dynamoDbGsiMetrics = ['ReadThrottleEvents', 'WriteThrottleEvents']
  * based on the tables and any global secondary indices (GSIs).
  *
  * @param dynamoDbAlarmsConfig The fully resolved alarm configuration
- * @param context Deployment context (alarmActions)
+ * @param alarmActionsConfig Notification configuration for alarm status change events
  * @param compiledTemplate A CloudFormation template object
  *
  * @returns DynamoDB-specific CloudFormation Alarm resources
  */
 export default function createDynamoDbAlarms (
- dynamoDbAlarmsConfig: SlicWatchDynamoDbAlarmsConfig<SlicWatchMergedConfig>, context: AlarmActionsConfig, compiledTemplate: Template
+ dynamoDbAlarmsConfig: SlicWatchDynamoDbAlarmsConfig<SlicWatchMergedConfig>, alarmActionsConfig: AlarmActionsConfig, compiledTemplate: Template
 ): CloudFormationResources {
  const resources: CloudFormationResources = {}
  const tableResources = getResourcesByType('AWS::DynamoDB::Table', compiledTemplate)
@@ -46,7 +46,7 @@ export default function createDynamoDbAlarms (
  ...rest
  }
  const alarmLogicalId = makeAlarmLogicalId('Table', tableLogicalId, metric)
- const resource = createAlarm(dynamoDbAlarmProperties, context)
+ const resource = createAlarm(dynamoDbAlarmProperties, alarmActionsConfig)
  resources[alarmLogicalId] = resource
  }
  }
@@ -66,7 +66,7 @@ export default function createDynamoDbAlarms (
  ...rest
  }
  const alarmLogicalId = makeAlarmLogicalId('GSI', `${tableLogicalId}${gsiName}`, metric)
- const resource = createAlarm(dynamoDbAlarmsConfig, context)
+ const resource = createAlarm(dynamoDbAlarmsConfig, alarmActionsConfig)
  resources[alarmLogicalId] = resource
  }
  }