aws-cdk-lib/aws-cloudwatch/lib/alarm.d.ts

Version 2 of the AWS Cloud Development Kit library

import { Construct } from 'constructs';
import { IAlarmAction } from './alarm-action';
import { AlarmBase, IAlarm } from './alarm-base';
import { HorizontalAnnotation } from './graph';
import { CreateAlarmOptions } from './metric';
import { IMetric } from './metric-types';
import { CreateAlarmOptionsBase } from './private/alarm-options';
/**
 * Properties for Alarms
 */
export interface AlarmProps extends CreateAlarmOptions {
    /**
     * The metric to add the alarm on
     *
     * Metric objects can be obtained from most resources, or you can construct
     * custom Metric objects by instantiating one.
     */
    readonly metric: IMetric;
}
/**
 * Properties for Anomaly Detection Alarms
 */
export interface AnomalyDetectionAlarmProps extends CreateAlarmOptionsBase {
    /**
     * The metric to add the alarm on
     *
     * Metric objects can be obtained from most resources, or you can construct
     * custom Metric objects by instantiating one.
     */
    readonly metric: IMetric;
    /**
     * The number of standard deviations to use for the anomaly detection band. The higher the value, the wider the band.
     *
     * - Must be greater than 0. A value of 0 or negative values would not make sense in the context of calculating standard deviations.
     * - There is no strict maximum value defined, as standard deviations can theoretically extend infinitely. However, in practice, values beyond 5 or 6 standard deviations are rarely used, as they would result in an extremely wide anomaly detection band, potentially missing significant anomalies.
     *
     * @default 2
     */
    readonly stdDevs?: number;
    /**
     * Comparison operator to use to check if metric is breaching.
     * Must be one of the anomaly detection operators:
     * - LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD
     * - GREATER_THAN_UPPER_THRESHOLD
     * - LESS_THAN_LOWER_THRESHOLD
     *
     * @default LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD
     */
    readonly comparisonOperator?: ComparisonOperator;
}
/**
 * Comparison operator for evaluating alarms
 */
export declare enum ComparisonOperator {
    /**
     * Specified statistic is greater than or equal to the threshold
     */
    GREATER_THAN_OR_EQUAL_TO_THRESHOLD = "GreaterThanOrEqualToThreshold",
    /**
     * Specified statistic is strictly greater than the threshold
     */
    GREATER_THAN_THRESHOLD = "GreaterThanThreshold",
    /**
     * Specified statistic is strictly less than the threshold
     */
    LESS_THAN_THRESHOLD = "LessThanThreshold",
    /**
     * Specified statistic is less than or equal to the threshold.
     */
    LESS_THAN_OR_EQUAL_TO_THRESHOLD = "LessThanOrEqualToThreshold",
    /**
     * Specified statistic is lower than or greater than the anomaly model band.
     * Used only for alarms based on anomaly detection models
     */
    LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD = "LessThanLowerOrGreaterThanUpperThreshold",
    /**
     * Specified statistic is greater than the anomaly model band.
     * Used only for alarms based on anomaly detection models
     */
    GREATER_THAN_UPPER_THRESHOLD = "GreaterThanUpperThreshold",
    /**
     * Specified statistic is lower than the anomaly model band.
     * Used only for alarms based on anomaly detection models
     */
    LESS_THAN_LOWER_THRESHOLD = "LessThanLowerThreshold"
}
/**
 * Specify how missing data points are treated during alarm evaluation
 */
export declare enum TreatMissingData {
    /**
     * Missing data points are treated as breaching the threshold
     */
    BREACHING = "breaching",
    /**
     * Missing data points are treated as being within the threshold
     */
    NOT_BREACHING = "notBreaching",
    /**
     * The current alarm state is maintained
     */
    IGNORE = "ignore",
    /**
     * The alarm does not consider missing data points when evaluating whether to change state
     */
    MISSING = "missing"
}
/**
 * An alarm on a CloudWatch metric
 */
export declare class Alarm extends AlarmBase {
    /** Uniquely identifies this class. */
    static readonly PROPERTY_INJECTION_ID: string;
    /**
     * Conventional value for the threshold property when creating anomaly detection alarms.
     *
     * Anomaly detection alarms don't have numbered threshold. Instead, they have a dynamically
     * calculated threshold based on the metric math expression that contains a metric expression.
     *
     * The `threshold` property is required, but the value is ignored. This
     * constant has the value 0, and has a symbolic name to indicate why the
     * threshold is 0. You can use `new AnomalyDetectionAlarm()` to avoid having to pass
     * the `threshold` property at all.
     */
    static readonly ANOMALY_DETECTION_NO_THRESHOLD = 0;
    /**
     * Import an existing CloudWatch alarm provided an Name.
     *
     * @param scope The parent creating construct (usually `this`)
     * @param id The construct's name
     * @param alarmName Alarm Name
     */
    static fromAlarmName(scope: Construct, id: string, alarmName: string): IAlarm;
    /**
     * Import an existing CloudWatch alarm provided an ARN
     *
     * @param scope The parent creating construct (usually `this`).
     * @param id The construct's name
     * @param alarmArn Alarm ARN (i.e. arn:aws:cloudwatch:<region>:<account-id>:alarm:Foo)
     */
    static fromAlarmArn(scope: Construct, id: string, alarmArn: string): IAlarm;
    /**
     * ARN of this alarm
     *
     * @attribute
     */
    readonly alarmArn: string;
    /**
     * Name of this alarm.
     *
     * @attribute
     */
    readonly alarmName: string;
    /**
     * The metric object this alarm was based on
     */
    readonly metric: IMetric;
    /**
     * This metric as an annotation
     */
    private readonly annotation;
    constructor(scope: Construct, id: string, props: AlarmProps);
    /**
     * Turn this alarm into a horizontal annotation
     *
     * This is useful if you want to represent an Alarm in a non-AlarmWidget.
     * An `AlarmWidget` can directly show an alarm, but it can only show a
     * single alarm and no other metrics. Instead, you can convert the alarm to
     * a HorizontalAnnotation and add it as an annotation to another graph.
     *
     * This might be useful if:
     *
     * - You want to show multiple alarms inside a single graph, for example if
     *   you have both a "small margin/long period" alarm as well as a
     *   "large margin/short period" alarm.
     *
     * - You want to show an Alarm line in a graph with multiple metrics in it.
     */
    toAnnotation(): HorizontalAnnotation;
    /**
     * Trigger this action if the alarm fires
     *
     * Typically SnsAction or AutoScalingAction.
     */
    addAlarmAction(...actions: IAlarmAction[]): void;
    private validateActionArn;
    /**
     * Render the given metric to properties of CfnAlarmProps
     *
     * - Tries to render to the legacy fields if possible (to not unduly change
     *   existing templates from before the modern fields were added).
     * - If the metric is a math expression that depends on other metrics, recursively
     *   render all of them to the `metrics[]` array.
     *
     * Returns the alarm fields, as well as the 'id' that was assigned to the primary metric
     * (if rendering to the modern fields, because the legacy fields don't have an id).
     *
     * The metric we are trying to render (potentially) forms a tree that looks like this
     * (the example doesn't make sense but it shows the data structures)
     *
     * ```
     *    +-- MathExpression('m1 + m2')
     *          |
     *          +--- m1: MetricStat('AWS/DynamoDB', 'Errors', 'SUM')
     *          +--- m2: MathExpression('m3 * m4')
     *                     |
     *                     +--- m3: MetricStat('AWS/DynamoDB', 'BytesWritten', 'AVG')
     *                     +--- m4: MetricStat('AWS/SQS', 'MessagesReceived', 'MIN')
     * ```
     *
     * `metric` is the root of this metric tree, and we need to render this to a
     * flat list of 5 `MetricData` objects where we make sure that all metrics
     * have a (unique) identifier assigned and only the root one has `ReturnData:
     * true` set.
     *
     * ## doubleReturnData
     *
     * Normally, exactly one metric in the list needs to have `ReturnData: true` set, and it's
     * the "primary" metric, i.e., the metric that the actual alarm should trigger on. There is
     * an exception to this rule: for anomaly detection alarms, both the anomaly detection
     * math expression *AND* the metric that the expression is based on must have `ReturnData: true`
     * set.
     *
     * This flag controls whether we set `ReturnData: true` only on the top-level math expression, or
     * on both the top-level and the second-level expression.
     */
    private renderMetric;
    /**
     * Validate that if a region is in the given stat config, they match the Alarm
     */
    private validateMetricStat;
    /**
     * Validates that the expression config does not specify searchAccount or searchRegion props
     * as search expressions are not supported by Alarms.
     */
    private validateMetricExpression;
    /**
     * Determine if the accountId property should be included in the metric.
     */
    private requiresAccountId;
}
/**
 * CloudWatch Alarm that uses anomaly detection to trigger alarms
 *
 * This alarm type is specifically designed for use with anomaly detection operators
 * like LESS_THAN_LOWER_OR_GREATER_THAN_UPPER_THRESHOLD.
 */
export declare class AnomalyDetectionAlarm extends Alarm {
    /** Uniquely identifies this class. */
    static readonly PROPERTY_INJECTION_ID: string;
    constructor(scope: Construct, id: string, props: AnomalyDetectionAlarmProps);
}