@renovosolutions/cdk-library-cloudwatch-alarms/lib/sqs.d.ts

AWS CDK Construct Library to automatically create CloudWatch Alarms for resources in a CDK app based on resource type.

import { IAspect, aws_sqs as sqs, aws_cloudwatch as cloudwatch, Duration } from 'aws-cdk-lib';
import { IConstruct, Construct } from 'constructs';
import { AlarmBaseProps } from './common';
/**
 * The recommended metrics for SQS queue alarms.
 */
export declare enum SqsRecommendedAlarmsMetrics {
    APPROXIMATE_AGE_OF_OLDEST_MESSAGE = "ApproximateAgeOfOldestMessage",
    APPROXIMATE_NUMBER_OF_MESSAGES_NOT_VISIBLE = "ApproximateNumberOfMessagesNotVisible",
    APPROXIMATE_NUMBER_OF_MESSAGES_VISIBLE = "ApproximateNumberOfMessagesVisible",
    NUMBER_OF_MESSAGES_SENT = "NumberOfMessagesSent"
}
export interface SqsAlarmBaseConfig extends AlarmBaseProps {
    /**
     * The period over which the specified statistic is applied.
     *
     * @default Duration.minutes(1)
     */
    readonly period?: Duration;
    /**
     * The number of periods over which data is compared to the specified threshold.
     *
     * @default 15
     */
    readonly evaluationPeriods?: number;
    /**
     * The number of data points that must be breaching to trigger the alarm.
     *
     * @default 15
     */
    readonly datapointsToAlarm?: number;
}
/**
 * Configuration for the ApproximateAgeOfOldestMessage alarm.
 */
export interface SqsApproximateAgeOfOldestMessageAlarmConfig extends SqsAlarmBaseConfig {
    /**
     * The value against which the specified statistic is compared.
     *
     * The recommended threshold value for this alarm is highly dependent on the expected message
     * processing time. You can use historical data to calculate the average message processing time,
     * and then set the threshold to 50% higher than the maximum expected SQS message processing
     * time by queue consumers.
     */
    readonly threshold: number;
    /**
     * The alarm name.
     *
     * @default - queue.queueName + ' - ApproximateAgeOfOldestMessage'
     */
    readonly alarmName?: string;
    /**
     * The description of the alarm.
     *
     * @default -  This alarm watches the age of the oldest message in the queue. You can use this alarm
     * to monitor if your consumers are processing SQS messages at the desired speed. Consider increasing
     * the consumer count or consumer throughput to reduce message age. This metric can be used in
     * combination with ApproximateNumberOfMessagesVisible to determine how big the queue backlog is
     * and how quickly messages are being processed. To prevent messages from being deleted before processed,
     * consider configuring the dead-letter queue to sideline potential poison pill messages.
     */
    readonly alarmDescription?: string;
}
/**
 * Properties for the SqsApproximateAgeOfOldestMessageAlarm construct.
 */
export interface SqsApproximateAgeOfOldestMessageAlarmProps extends SqsApproximateAgeOfOldestMessageAlarmConfig {
    /**
     * The SQS queue for which to create the alarm.
     */
    readonly queue: sqs.IQueue;
}
/**
 * An alarm that watches the age of the oldest message in the queue.
 *
 * This alarm is used to detect whether the age of the oldest message
 * in the QueueName queue is too high. High age can be an indication
 * that messages are not processed quickly enough or that there are
 * some poison-pill messages that are stuck in the queue and can't
 * be processed.
 *
 * This alarm is triggered when the age of the oldest message in the
 * queue exceeds or is equal to the specified threshold.
 */
export declare class SqsApproximateAgeOfOldestMessageAlarm extends cloudwatch.Alarm {
    constructor(scope: IConstruct, id: string, props: SqsApproximateAgeOfOldestMessageAlarmProps);
}
/**
 * Configuration for the ApproximateNumberOfMessagesNotVisible alarm.
 */
export interface SqsApproximateNumberOfMessagesNotVisibleAlarmConfig extends SqsAlarmBaseConfig {
    /**
     * The value against which the specified statistic is compared.
     *
     * The recommended threshold value for this alarm is highly dependent on the expected number
     * of messages in flight. You can use historical data to calculate the maximum expected
     * number of messages in flight and set the threshold to 50% over this value. If consumers
     * of the queue are processing but not deleting messages from the queue, this number will
     * suddenly increase.
     */
    readonly threshold: number;
    /**
     * The alarm name.
     *
     * @default - queue.queueName + ' - ApproximateNumberOfMessagesNotVisible'
     */
    readonly alarmName?: string;
    /**
     * The description of the alarm.
     *
     * @default - This alarm helps to detect a high number of in-flight messages with respect to QueueName.
     * For troubleshooting, check message backlog decreasing (https://repost.aws/knowledge-center/sqs-message-backlog).
     */
    readonly alarmDescription?: string;
}
/**
 * Properties for the SqsApproximateNumberOfMessagesNotVisibleAlarm construct.
 */
export interface SqsApproximateNumberOfMessagesNotVisibleAlarmProps extends SqsApproximateNumberOfMessagesNotVisibleAlarmConfig {
    /**
     * The SQS queue for which to create the alarm.
     */
    readonly queue: sqs.IQueue;
}
/**
 * An alarm that watches the number of messages that are in flight.
 *
 * This alarm is used to detect a high number of in-flight messages
 * in the queue. If consumers do not delete messages within the
 * visibility timeout period, when the queue is polled, messages
 * reappear in the queue. For FIFO queues, there can be a maximum
 * of 20,000 in-flight messages. If you reach this quota, SQS returns
 * no error messages. A FIFO queue looks through the first 20k
 * messages to determine available message groups. This means that
 * if you have a backlog of messages in a single message group,
 * you cannot consume messages from other message groups that were
 * sent to the queue at a later time until you successfully
 * consume the messages from the backlog.
 *
 * This alarm is triggered when the number of messages that are in
 * flight exceeds or is equal to the specified threshold.
 */
export declare class SqsApproximateNumberOfMessagesNotVisibleAlarm extends cloudwatch.Alarm {
    constructor(scope: IConstruct, id: string, props: SqsApproximateNumberOfMessagesNotVisibleAlarmProps);
}
/**
 * Configuration for the ApproximateNumberOfMessagesVisible alarm.
 */
export interface SqsApproximateNumberOfMessagesVisibleAlarmConfig extends SqsAlarmBaseConfig {
    /**
     * The value against which the specified statistic is compared.
     *
     * An unexpectedly high number of messages visible indicates that messages are not being
     * processed by a consumer at the expected rate. You should consider historical data when
     * you set this threshold.
     */
    readonly threshold: number;
    /**
     * The alarm name.
     *
     * @default - queue.queueName + ' - ApproximateNumberOfMessagesVisible'
     */
    readonly alarmName?: string;
    /**
     * The description of the alarm.
     *
     * @default - This alarm helps to detect a high number of in-flight messages with respect to QueueName.
     * For troubleshooting, check message backlog decreasing (https://repost.aws/knowledge-center/sqs-message-backlog).
     */
    readonly alarmDescription?: string;
}
/**
 * Properties for the SqsApproximateNumberOfMessagesVisibleAlarm construct.
 */
export interface SqsApproximateNumberOfMessagesVisibleAlarmProps extends SqsApproximateNumberOfMessagesVisibleAlarmConfig {
    /**
     * The SQS queue for which to create the alarm.
     */
    readonly queue: sqs.IQueue;
}
/**
 * An alarm that watches the number of messages that
 * are visible in the queue.
 *
 * This alarm is used to detect whether the message
 * count of the active queue is too high and consumers
 * are slow to process the messages or there are not
 * enough consumers to process them.
 *
 * This alarm is triggered when the number of messages
 * that are visible in the queue exceeds or is equal to
 * the specified threshold.
 */
export declare class SqsApproximateNumberOfMessagesVisibleAlarm extends cloudwatch.Alarm {
    constructor(scope: IConstruct, id: string, props: SqsApproximateNumberOfMessagesVisibleAlarmProps);
}
/**
 * Configuration for the NumberOfMessagesSent alarm.
 */
export interface SqsNumberOfMessagesSentAlarmConfig extends SqsAlarmBaseConfig {
    /**
     * The value against which the specified statistic is compared.
     *
     * If the number of messages sent is 0, the producer is not sending any messages.
     * If this queue has a low TPS, increase the number of EvaluationPeriods accordingly.
     *
     * @default 0
     */
    readonly threshold?: number;
    /**
     * The alarm name.
     *
     * @default - queue.queueName + ' - NumberOfMessagesSent'
     */
    readonly alarmName?: string;
    /**
     * The description of the alarm.
     *
     * @default - This alarm helps to detect a high number of in-flight messages with respect
     * to QueueName. For troubleshooting, check message backlog decreasing (https://repost.aws/knowledge-center/sqs-message-backlog).
     */
    readonly alarmDescription?: string;
}
/**
 * Properties for the SqsNumberOfMessagesSentAlarm construct.
 */
export interface SqsNumberOfMessagesSentAlarmProps extends SqsNumberOfMessagesSentAlarmConfig {
    /**
     * The SQS queue for which to create the alarm.
     */
    readonly queue: sqs.IQueue;
}
/**
 * An alarm that watches the number of messages that are sent.
 *
 * This alarm is used to detect when a producer stops sending messages.
 *
 * This alarm is triggered when the number of messages sent is less than
 * or equal to the specified threshold. By default, 0.
 */
export declare class SqsNumberOfMessagesSentAlarm extends cloudwatch.Alarm {
    constructor(scope: IConstruct, id: string, props: SqsNumberOfMessagesSentAlarmProps);
}
/**
 * Configuration for the recommended alarms for an SQS queue.
 */
export interface SqsRecommendedAlarmsConfig {
    /**
     * The default action to take when an alarm is triggered.
     *
     * @default - None
     */
    readonly defaultAlarmAction?: cloudwatch.IAlarmAction;
    /**
     * The default action to take when an alarm enters the ok state.
     *
     * @default - None
     */
    readonly defaultOkAction?: cloudwatch.IAlarmAction;
    /**
     * The default action to take when an alarm has insufficient data.
     *
     * @default - None
     */
    readonly defaultInsufficientDataAction?: cloudwatch.IAlarmAction;
    /**
     * How to handle missing data for this alarm.
     *
     * @default TreatMissingData.MISSING
     */
    readonly treatMissingData?: cloudwatch.TreatMissingData;
    /**
     * Alarm metrics to exclude from the recommended alarms.
     *
     * @default - None
     */
    readonly excludeAlarms?: SqsRecommendedAlarmsMetrics[];
    /**
     * The resources to exclude from the recommended alarms.
     *
     * Use a resources id to exclude a specific resource.
     */
    readonly excludeResources?: string[];
    /**
     * The configuration for the approximate age of oldest message alarm.
     */
    readonly configApproximateAgeOfOldestMessageAlarm: SqsApproximateAgeOfOldestMessageAlarmConfig;
    /**
     * The configuration for the approximate number of messages not visible alarm.
     */
    readonly configApproximateNumberOfMessagesNotVisibleAlarm: SqsApproximateNumberOfMessagesNotVisibleAlarmConfig;
    /**
     * The configuration for the approximate number of messages visible alarm.
     */
    readonly configApproximateNumberOfMessagesVisibleAlarm: SqsApproximateNumberOfMessagesVisibleAlarmConfig;
    /**
     * The configuration for the number of messages sent alarm.
     */
    readonly configNumberOfMessagesSentAlarm?: SqsNumberOfMessagesSentAlarmConfig;
    /**
     * Whether to apply the usual recommended alarms to dead letter queues.
     *
     * If true, the dead letter queues will have the same alarms as normal queues.
     * If false, the dead letter queues will only have the ApproximateNumberOfMessagesVisible
     * alarm with a default threshold of 0.
     *
     * @default false
     */
    readonly dlqsGetFullRecommendedAlarms?: boolean;
    /**
     * The configuration for the approximate number of messages visible alarm for DLQs.
     *
     * This is used for dead letter queues only. The threshold is set to 0 by default.
     */
    readonly configDlqApproximateNumberOfMessagesVisibleAlarm?: SqsApproximateNumberOfMessagesVisibleAlarmConfig;
}
/**
 * Properties for the SqsRecommendedAlarms construct.
 */
export interface SqsRecommendedAlarmsProps extends SqsRecommendedAlarmsConfig {
    /**
     * The SQS queue for which to create the alarms.
     */
    readonly queue: sqs.IQueue;
}
export declare class SqsRecommendedAlarms extends Construct {
    /**
     * The approximate age of oldest message alarm.
     */
    readonly alarmApproximateAgeOfOldestMessage?: SqsApproximateAgeOfOldestMessageAlarm;
    /**
     * The approximate number of messages not visible alarm.
     */
    readonly alarmApproximateNumberOfMessagesNotVisible?: SqsApproximateNumberOfMessagesNotVisibleAlarm;
    /**
     * The approximate number of messages visible alarm.
     */
    readonly alarmApproximateNumberOfMessagesVisible?: SqsApproximateNumberOfMessagesVisibleAlarm;
    /**
     * The number of messages sent alarm.
     */
    readonly alarmNumberOfMessagesSent?: SqsNumberOfMessagesSentAlarm;
    constructor(scope: Construct, id: string, props: SqsRecommendedAlarmsProps);
}
/**
 * An extension of the SQS Queue construct that adds methods to create recommended alarms.
 */
export declare class Queue extends sqs.Queue {
    constructor(scope: Construct, id: string, props?: sqs.QueueProps);
    /**
     * Creates an alarm that watches the age of the oldest message in the queue.
     */
    alarmApproximateAgeOfOldestMessage(props: SqsApproximateAgeOfOldestMessageAlarmConfig): SqsApproximateAgeOfOldestMessageAlarm;
    /**
     * Creates an alarm that watches the number of messages that are in flight.
     */
    alarmApproximateNumberOfMessagesNotVisible(props: SqsApproximateNumberOfMessagesNotVisibleAlarmConfig): SqsApproximateNumberOfMessagesNotVisibleAlarm;
    /**
     * Creates an alarm that watches the number of messages that are visible in the queue.
     */
    alarmApproximateNumberOfMessagesVisible(props: SqsApproximateNumberOfMessagesVisibleAlarmConfig): SqsApproximateNumberOfMessagesVisibleAlarm;
    /**
     * Creates an alarm that watches the number of messages that are sent.
     */
    alarmNumberOfMessagesSent(props?: SqsNumberOfMessagesSentAlarmConfig): SqsNumberOfMessagesSentAlarm;
    /**
     * Creates the recommended alarms for an SQS queue.
     */
    applyRecommendedAlarms(props: SqsRecommendedAlarmsConfig): void;
}
/**
 * Configured the recommended alarms for an SQS queue. Requires defining thresholds for some alarms.
 *
 * @see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html#SQS
 */
export declare class SqsRecommendedAlarmsAspect implements IAspect {
    private readonly props;
    /**
     * A list of dead letter queues discovered in the scope.
     * We exclude these from the recommended alarms
     * because they don't make sense.
     */
    deadLetterQueues: string[];
    /**
     * A flag to indicate whether dead letter queues have been discovered.
     * This is used to prevent running the discovery logic on every call to `visit`.
     */
    deadLetterQueuesDiscovered: boolean;
    constructor(props: SqsRecommendedAlarmsConfig);
    visit(node: IConstruct): void;
}