255 lines
9.7 KiB
TypeScript
255 lines
9.7 KiB
TypeScript
import type { Construct } from 'constructs';
|
|
import type { IAlarmAction } from './alarm-action';
|
|
import type { IAlarm } from './alarm-base';
|
|
import { AlarmBase } from './alarm-base';
|
|
import type { HorizontalAnnotation } from './graph';
|
|
import type { CreateAlarmOptions } from './metric';
|
|
import type { IMetric } from './metric-types';
|
|
import type { 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;
|
|
/**
|
|
* The metric object this alarm was based on
|
|
*/
|
|
readonly metric: IMetric;
|
|
/**
|
|
* This metric as an annotation
|
|
*/
|
|
private readonly annotation;
|
|
private readonly alarm;
|
|
constructor(scope: Construct, id: string, props: AlarmProps);
|
|
/**
|
|
* ARN of this alarm
|
|
*
|
|
* @attribute
|
|
*/
|
|
get alarmArn(): string;
|
|
/**
|
|
* Name of this alarm.
|
|
*
|
|
* @attribute
|
|
*/
|
|
get alarmName(): string;
|
|
/**
|
|
* 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);
|
|
}
|