Alarms and Composite Alarms

/**
 * A CloudWatch alarm
 */
class Alarm extends AlarmBase {
  /**
   * Create a new alarm
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param props - Alarm configuration properties
   */
  constructor(scope: Construct, id: string, props: AlarmProps);

  /**
   * Import an existing alarm by ARN
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param alarmArn - The ARN of the alarm to import
   * @returns Imported alarm instance
   */
  static fromAlarmArn(scope: Construct, id: string, alarmArn: string): IAlarm;

  /**
   * Turn this alarm into a horizontal annotation for graphs
   * @returns Horizontal annotation configuration
   */
  toAnnotation(): HorizontalAnnotation;

  readonly alarmArn: string;
  readonly alarmName: string;
  readonly metric: IMetric;
}

interface AlarmProps extends CreateAlarmOptions {
  /** The metric to add the alarm on */
  readonly metric: IMetric;
}

interface CreateAlarmOptions {
  /** Name of the alarm */
  readonly alarmName?: string;
  /** Description for the alarm */
  readonly alarmDescription?: string;
  /** Comparison to use to check if metric is breaching */
  readonly comparisonOperator?: ComparisonOperator;
  /** The value against which the specified statistic is compared */
  readonly threshold: number;
  /** The number of periods over which data is compared to the specified threshold */
  readonly evaluationPeriods: number;
  /** Specifies whether to evaluate the data and potentially change the alarm state if there are too few data points */
  readonly evaluateLowSampleCountPercentile?: string;
  /** Sets how this alarm is to handle missing data points */
  readonly treatMissingData?: TreatMissingData;
  /** Whether the actions for this alarm are enabled */
  readonly actionsEnabled?: boolean;
  /** The number of datapoints that must be breaching to trigger the alarm */
  readonly datapointsToAlarm?: number;
}

enum ComparisonOperator {
  GREATER_THAN_OR_EQUAL_TO_THRESHOLD = 'GreaterThanOrEqualToThreshold',
  GREATER_THAN_THRESHOLD = 'GreaterThanThreshold',
  LESS_THAN_THRESHOLD = 'LessThanThreshold',
  LESS_THAN_OR_EQUAL_TO_THRESHOLD = 'LessThanOrEqualToThreshold',
  LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD = 'LessThanLowerOrGreaterThanUpperThreshold',
  GREATER_THAN_UPPER_THRESHOLD = 'GreaterThanUpperThreshold',
  LESS_THAN_LOWER_THRESHOLD = 'LessThanLowerThreshold'
}

enum TreatMissingData {
  /** Missing data points are treated as "bad" and will cause the alarm to go to ALARM state */
  BREACHING = 'breaching',
  /** Missing data points are treated as "good" and within the threshold */
  NOT_BREACHING = 'notBreaching',
  /** Current alarm state is maintained */
  IGNORE = 'ignore',
  /** Missing data points are treated as missing */
  MISSING = 'missing'
}

import * as cloudwatch from '@aws-cdk/aws-cloudwatch';
import * as cdk from '@aws-cdk/core';

// Create a basic alarm
const metric = new cloudwatch.Metric({
  namespace: 'AWS/EC2',
  metricName: 'CPUUtilization',
  dimensionsMap: {
    InstanceId: 'i-1234567890abcdef0'
  }
});

const highCpuAlarm = new cloudwatch.Alarm(this, 'HighCPU', {
  metric: metric,
  threshold: 80,
  evaluationPeriods: 2,
  comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD,
  treatMissingData: cloudwatch.TreatMissingData.NOT_BREACHING,
  alarmDescription: 'Alert when CPU exceeds 80%'
});

// Alarm with datapoints to alarm (M out of N)
const intermittentErrorAlarm = new cloudwatch.Alarm(this, 'IntermittentErrors', {
  metric: errorMetric,
  threshold: 5,
  evaluationPeriods: 10,
  datapointsToAlarm: 3, // 3 out of 10 datapoints must breach
  comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD
});

// Import existing alarm
const existingAlarm = cloudwatch.Alarm.fromAlarmArn(
  this, 
  'ImportedAlarm',
  'arn:aws:cloudwatch:us-east-1:123456789012:alarm:MyAlarm'
);

/**
 * A CloudWatch composite alarm
 */
class CompositeAlarm extends AlarmBase {
  /**
   * Create a new composite alarm
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param props - Composite alarm configuration properties
   */
  constructor(scope: Construct, id: string, props: CompositeAlarmProps);

  /**
   * Import an existing composite alarm by name
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param compositeAlarmName - Name of the composite alarm
   * @returns Imported composite alarm instance
   */
  static fromCompositeAlarmName(scope: Construct, id: string, compositeAlarmName: string): IAlarm;

  /**
   * Import an existing composite alarm by ARN
   * @param scope - Construct scope
   * @param id - Construct ID
   * @param compositeAlarmArn - ARN of the composite alarm
   * @returns Imported composite alarm instance
   */
  static fromCompositeAlarmArn(scope: Construct, id: string, compositeAlarmArn: string): IAlarm;

  readonly alarmArn: string;
  readonly alarmName: string;
}

interface CompositeAlarmProps {
  /** Whether the actions for this alarm are enabled */
  readonly actionsEnabled?: boolean;
  /** Description for the alarm */
  readonly alarmDescription?: string;
  /** Name of the alarm */
  readonly compositeAlarmName?: string;
  /** Expression that specifies which other alarms are to be evaluated */
  readonly alarmRule: IAlarmRule;
}

import * as cloudwatch from '@aws-cdk/aws-cloudwatch';

// Create individual alarms
const highCpuAlarm = new cloudwatch.Alarm(this, 'HighCPU', {
  metric: cpuMetric,
  threshold: 80,
  evaluationPeriods: 2
});

const highMemoryAlarm = new cloudwatch.Alarm(this, 'HighMemory', {
  metric: memoryMetric,
  threshold: 85,
  evaluationPeriods: 2
});

const diskSpaceAlarm = new cloudwatch.Alarm(this, 'LowDiskSpace', {
  metric: diskMetric,
  threshold: 90,
  evaluationPeriods: 1,
  comparisonOperator: cloudwatch.ComparisonOperator.GREATER_THAN_THRESHOLD
});

// Create composite alarm with boolean logic
const systemHealthAlarm = new cloudwatch.CompositeAlarm(this, 'SystemHealth', {
  alarmRule: cloudwatch.AlarmRule.anyOf(
    cloudwatch.AlarmRule.allOf(
      cloudwatch.AlarmRule.fromAlarm(highCpuAlarm, cloudwatch.AlarmState.ALARM),
      cloudwatch.AlarmRule.fromAlarm(highMemoryAlarm, cloudwatch.AlarmState.ALARM)
    ),
    cloudwatch.AlarmRule.fromAlarm(diskSpaceAlarm, cloudwatch.AlarmState.ALARM)
  ),
  compositeAlarmName: 'SystemHealthComposite',
  alarmDescription: 'System health degraded'
});

/**
 * Interface for alarm rules used in composite alarms
 */
interface IAlarmRule {
  /** Render the alarm rule as a CloudWatch expression */
  renderAlarmRule(): string;
}

/**
 * Utility class for building alarm rules
 */
class AlarmRule {
  /**
   * Create a rule that is true when ALL of the given rules are true
   * @param operands - Alarm rules to combine with AND logic
   * @returns Combined alarm rule
   */
  static allOf(...operands: IAlarmRule[]): IAlarmRule;

  /**
   * Create a rule that is true when ANY of the given rules are true
   * @param operands - Alarm rules to combine with OR logic  
   * @returns Combined alarm rule
   */
  static anyOf(...operands: IAlarmRule[]): IAlarmRule;

  /**
   * Create a rule that is the NOT of the given rule
   * @param operand - Alarm rule to negate
   * @returns Negated alarm rule
   */
  static not(operand: IAlarmRule): IAlarmRule;

  /**
   * Create a rule from a boolean value
   * @param value - Boolean value for the rule
   * @returns Alarm rule representing the boolean
   */
  static fromBoolean(value: boolean): IAlarmRule;

  /**
   * Create a rule from an alarm and alarm state
   * @param alarm - The alarm to reference
   * @param alarmState - The state to check for
   * @returns Alarm rule for the alarm state
   */
  static fromAlarm(alarm: IAlarm, alarmState: AlarmState): IAlarmRule;

  /**
   * Create a rule from a raw alarm rule string
   * @param alarmRule - Raw CloudWatch alarm rule expression
   * @returns Alarm rule from the string
   */
  static fromString(alarmRule: string): IAlarmRule;
}

enum AlarmState {
  /** Alarm is in ALARM state */
  ALARM = 'ALARM',
  /** Alarm is in OK state */
  OK = 'OK', 
  /** Alarm is in INSUFFICIENT_DATA state */
  INSUFFICIENT_DATA = 'INSUFFICIENT_DATA'
}

/**
 * Interface for all alarms
 */
interface IAlarm extends IAlarmRule, IResource {
  /** ARN of this alarm */
  readonly alarmArn: string;
  /** Name of this alarm */ 
  readonly alarmName: string;
}

/**
 * Abstract base class for alarms
 */
abstract class AlarmBase extends Resource implements IAlarm {
  /**
   * Render the alarm rule for composite alarms
   * @returns Alarm rule string
   */
  renderAlarmRule(): string;

  /**
   * Trigger this action if the alarm fires
   * @param actions - Actions to add
   */
  addAlarmAction(...actions: IAlarmAction[]): void;

  /**
   * Trigger this action if the alarm goes into insufficient data mode
   * @param actions - Actions to add
   */
  addInsufficientDataAction(...actions: IAlarmAction[]): void;

  /**
   * Trigger this action if the alarm goes into ok mode
   * @param actions - Actions to add
   */
  addOkAction(...actions: IAlarmAction[]): void;

  abstract readonly alarmArn: string;
  abstract readonly alarmName: string;
}

/**
 * Interface for alarm actions
 */
interface IAlarmAction {
  /**
   * Bind this action to an alarm
   * @param scope - Construct scope
   * @param alarm - The alarm to bind to
   * @returns Action configuration
   */
  bind(scope: Construct, alarm: IAlarm): AlarmActionConfig;
}

interface AlarmActionConfig {
  /** ARN of the action to trigger */
  readonly alarmActionArn: string;
}

// Complex composite alarm logic
const webServerHealthRule = cloudwatch.AlarmRule.allOf(
  cloudwatch.AlarmRule.fromAlarm(highCpuAlarm, cloudwatch.AlarmState.OK),
  cloudwatch.AlarmRule.fromAlarm(highMemoryAlarm, cloudwatch.AlarmState.OK),
  cloudwatch.AlarmRule.not(
    cloudwatch.AlarmRule.fromAlarm(diskSpaceAlarm, cloudwatch.AlarmState.ALARM)
  )
);

const databaseHealthRule = cloudwatch.AlarmRule.anyOf(
  cloudwatch.AlarmRule.fromAlarm(dbConnectionAlarm, cloudwatch.AlarmState.OK),
  cloudwatch.AlarmRule.fromAlarm(dbSlowQueryAlarm, cloudwatch.AlarmState.OK)
);

const applicationHealthAlarm = new cloudwatch.CompositeAlarm(this, 'AppHealth', {
  alarmRule: cloudwatch.AlarmRule.allOf(webServerHealthRule, databaseHealthRule),
  alarmDescription: 'Overall application health status'
});