633 lines
21 KiB
TypeScript
633 lines
21 KiB
TypeScript
import type { Construct, IConstruct } from 'constructs';
|
|
import type { ComparisonOperator } from './alarm';
|
|
import { Alarm } from './alarm';
|
|
import type { IMetric, MetricConfig, Unit } from './metric-types';
|
|
import type { CreateAlarmOptionsBase } from './private/alarm-options';
|
|
import * as iam from '../../aws-iam';
|
|
import * as cdk from '../../core';
|
|
export type DimensionHash = {
|
|
[dim: string]: any;
|
|
};
|
|
export type DimensionsMap = {
|
|
[dim: string]: string;
|
|
};
|
|
/**
|
|
* Options shared by most methods accepting metric options
|
|
*/
|
|
export interface CommonMetricOptions {
|
|
/**
|
|
* The period over which the specified statistic is applied.
|
|
*
|
|
* @default Duration.minutes(5)
|
|
*/
|
|
readonly period?: cdk.Duration;
|
|
/**
|
|
* What function to use for aggregating.
|
|
*
|
|
* Use the `aws_cloudwatch.Stats` helper class to construct valid input strings.
|
|
*
|
|
* Can be one of the following:
|
|
*
|
|
* - "Minimum" | "min"
|
|
* - "Maximum" | "max"
|
|
* - "Average" | "avg"
|
|
* - "Sum" | "sum"
|
|
* - "SampleCount | "n"
|
|
* - "pNN.NN"
|
|
* - "tmNN.NN" | "tm(NN.NN%:NN.NN%)"
|
|
* - "iqm"
|
|
* - "wmNN.NN" | "wm(NN.NN%:NN.NN%)"
|
|
* - "tcNN.NN" | "tc(NN.NN%:NN.NN%)"
|
|
* - "tsNN.NN" | "ts(NN.NN%:NN.NN%)"
|
|
*
|
|
* @default Average
|
|
*/
|
|
readonly statistic?: string;
|
|
/**
|
|
* Dimensions of the metric
|
|
*
|
|
* @default - No dimensions.
|
|
*/
|
|
readonly dimensionsMap?: DimensionsMap;
|
|
/**
|
|
* Unit used to filter the metric stream
|
|
*
|
|
* Only refer to datums emitted to the metric stream with the given unit and
|
|
* ignore all others. Only useful when datums are being emitted to the same
|
|
* metric stream under different units.
|
|
*
|
|
* The default is to use all matric datums in the stream, regardless of unit,
|
|
* which is recommended in nearly all cases.
|
|
*
|
|
* CloudWatch does not honor this property for graphs.
|
|
*
|
|
* @default - All metric datums in the given metric stream
|
|
*/
|
|
readonly unit?: Unit;
|
|
/**
|
|
* Label for this metric when added to a Graph in a Dashboard
|
|
*
|
|
* You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
|
|
* to show summary information about the entire displayed time series
|
|
* in the legend. For example, if you use:
|
|
*
|
|
* ```
|
|
* [max: ${MAX}] MyMetric
|
|
* ```
|
|
*
|
|
* As the metric label, the maximum value in the visible range will
|
|
* be shown next to the time series name in the graph's legend.
|
|
*
|
|
* @default - No label
|
|
*/
|
|
readonly label?: string;
|
|
/**
|
|
* The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph.
|
|
* The `Color` class has a set of standard colors that can be used here.
|
|
* @default - Automatic color
|
|
*/
|
|
readonly color?: string;
|
|
/**
|
|
* Unique identifier for this metric when used in dashboard widgets.
|
|
*
|
|
* The id can be used as a variable to represent this metric in math expressions.
|
|
* Valid characters are letters, numbers, and underscore. The first character
|
|
* must be a lowercase letter.
|
|
*
|
|
* @default - No ID
|
|
*/
|
|
readonly id?: string;
|
|
/**
|
|
* Whether this metric should be visible in dashboard graphs.
|
|
*
|
|
* Setting this to false is useful when you want to hide raw metrics
|
|
* that are used in math expressions, and show only the expression results.
|
|
*
|
|
* @default true
|
|
*/
|
|
readonly visible?: boolean;
|
|
/**
|
|
* Account which this metric comes from.
|
|
*
|
|
* @default - Deployment account.
|
|
*/
|
|
readonly account?: string;
|
|
/**
|
|
* Region which this metric comes from.
|
|
*
|
|
* @default - Deployment region.
|
|
*/
|
|
readonly region?: string;
|
|
/**
|
|
* Account of the stack this metric is attached to.
|
|
*
|
|
* @default - Deployment account.
|
|
*/
|
|
readonly stackAccount?: string;
|
|
/**
|
|
* Region of the stack this metric is attached to.
|
|
*
|
|
* @default - Deployment region.
|
|
*/
|
|
readonly stackRegion?: string;
|
|
}
|
|
/**
|
|
* Properties for a metric
|
|
*/
|
|
export interface MetricProps extends CommonMetricOptions {
|
|
/**
|
|
* Namespace of the metric.
|
|
*/
|
|
readonly namespace: string;
|
|
/**
|
|
* Name of the metric.
|
|
*/
|
|
readonly metricName: string;
|
|
}
|
|
/**
|
|
* Properties of a metric that can be changed
|
|
*/
|
|
export interface MetricOptions extends CommonMetricOptions {
|
|
}
|
|
/**
|
|
* Configurable options for MathExpressions
|
|
*/
|
|
export interface MathExpressionOptions {
|
|
/**
|
|
* Label for this expression when added to a Graph in a Dashboard
|
|
*
|
|
* If this expression evaluates to more than one time series (for
|
|
* example, through the use of `METRICS()` or `SEARCH()` expressions),
|
|
* each time series will appear in the graph using a combination of the
|
|
* expression label and the individual metric label. Specify the empty
|
|
* string (`''`) to suppress the expression label and only keep the
|
|
* metric label.
|
|
*
|
|
* You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
|
|
* to show summary information about the displayed time series
|
|
* in the legend. For example, if you use:
|
|
*
|
|
* ```
|
|
* [max: ${MAX}] MyMetric
|
|
* ```
|
|
*
|
|
* As the metric label, the maximum value in the visible range will
|
|
* be shown next to the time series name in the graph's legend. If the
|
|
* math expression produces more than one time series, the maximum
|
|
* will be shown for each individual time series produce by this
|
|
* math expression.
|
|
*
|
|
* @default - Expression value is used as label
|
|
*/
|
|
readonly label?: string;
|
|
/**
|
|
* Color for this metric when added to a Graph in a Dashboard
|
|
*
|
|
* @default - Automatic color
|
|
*/
|
|
readonly color?: string;
|
|
/**
|
|
* The period over which the math expression's statistics are applied.
|
|
*
|
|
* This period overrides all periods in the metrics used in this
|
|
* math expression.
|
|
*
|
|
* @default Duration.minutes(5)
|
|
*/
|
|
readonly period?: cdk.Duration;
|
|
/**
|
|
* Account to evaluate search expressions within.
|
|
*
|
|
* Specifying a searchAccount has no effect to the account used
|
|
* for metrics within the expression (passed via usingMetrics).
|
|
*
|
|
* @default - Deployment account.
|
|
*/
|
|
readonly searchAccount?: string;
|
|
/**
|
|
* Region to evaluate search expressions within.
|
|
*
|
|
* Specifying a searchRegion has no effect to the region used
|
|
* for metrics within the expression (passed via usingMetrics).
|
|
*
|
|
* @default - Deployment region.
|
|
*/
|
|
readonly searchRegion?: string;
|
|
}
|
|
/**
|
|
* Properties for a MathExpression
|
|
*/
|
|
export interface MathExpressionProps extends MathExpressionOptions {
|
|
/**
|
|
* The expression defining the metric.
|
|
*
|
|
* When an expression contains a SEARCH function, it cannot be used
|
|
* within an Alarm.
|
|
*/
|
|
readonly expression: string;
|
|
/**
|
|
* The metrics used in the expression, in a map.
|
|
*
|
|
* The key is the identifier that represents the given metric in the
|
|
* expression, and the value is the actual Metric object.
|
|
*
|
|
* The `period` of each metric in `usingMetrics` is ignored and instead overridden
|
|
* by the `period` specified for the `MathExpression` construct. Even if no `period`
|
|
* is specified for the `MathExpression`, it will be overridden by the default
|
|
* value (`Duration.minutes(5)`).
|
|
*
|
|
* Example:
|
|
*
|
|
* ```ts
|
|
* declare const metrics: elbv2.IApplicationLoadBalancerMetrics;
|
|
* new cloudwatch.MathExpression({
|
|
* expression: 'm1+m2',
|
|
* label: 'AlbErrors',
|
|
* usingMetrics: {
|
|
* m1: metrics.custom('HTTPCode_ELB_500_Count', {
|
|
* period: Duration.minutes(1), // <- This period will be ignored
|
|
* statistic: 'Sum',
|
|
* label: 'HTTPCode_ELB_500_Count',
|
|
* }),
|
|
* m2: metrics.custom('HTTPCode_ELB_502_Count', {
|
|
* period: Duration.minutes(1), // <- This period will be ignored
|
|
* statistic: 'Sum',
|
|
* label: 'HTTPCode_ELB_502_Count',
|
|
* }),
|
|
* },
|
|
* period: Duration.minutes(3), // <- This overrides the period of each metric in `usingMetrics`
|
|
* // (Even if not specified, it is overridden by the default value)
|
|
* });
|
|
* ```
|
|
*
|
|
* @default - Empty map.
|
|
*/
|
|
readonly usingMetrics?: Record<string, IMetric>;
|
|
}
|
|
/**
|
|
* Configurable options for SearchExpressions
|
|
*/
|
|
export interface SearchExpressionOptions {
|
|
/**
|
|
* Label for this search expression when added to a Graph in a Dashboard.
|
|
*
|
|
* If this expression evaluates to more than one time series,
|
|
* each time series will appear in the graph using a combination of the
|
|
* expression label and the individual metric label. Specify the empty
|
|
* string (`''`) to suppress the expression label and only keep the
|
|
* metric label.
|
|
*
|
|
* You can use [dynamic labels](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/graph-dynamic-labels.html)
|
|
* to show summary information about the displayed time series
|
|
* in the legend. For example, if you use:
|
|
*
|
|
* ```
|
|
* [max: ${MAX}] MyMetric
|
|
* ```
|
|
*
|
|
* As the metric label, the maximum value in the visible range will
|
|
* be shown next to the time series name in the graph's legend. If the
|
|
* search expression produces more than one time series, the maximum
|
|
* will be shown for each individual time series produce by this
|
|
* search expression.
|
|
*
|
|
* @default - No label.
|
|
*/
|
|
readonly label?: string;
|
|
/**
|
|
* Color for the metric produced by the search expression.
|
|
*
|
|
* If the search expression produces more than one time series, the color is assigned to the first one.
|
|
* Other metrics are assigned colors automatically.
|
|
*
|
|
* @default - Automatically assigned.
|
|
*/
|
|
readonly color?: string;
|
|
/**
|
|
* The period over which the search expression's statistics are applied.
|
|
*
|
|
* This period overrides the period defined within the search expression.
|
|
*
|
|
* @default Duration.minutes(5)
|
|
*/
|
|
readonly period?: cdk.Duration;
|
|
/**
|
|
* Account to evaluate search expressions within.
|
|
*
|
|
* @default - Deployment account.
|
|
*/
|
|
readonly searchAccount?: string;
|
|
/**
|
|
* Region to evaluate search expressions within.
|
|
*
|
|
* @default - Deployment region.
|
|
*/
|
|
readonly searchRegion?: string;
|
|
}
|
|
/**
|
|
* Properties for a SearchExpression
|
|
*/
|
|
export interface SearchExpressionProps extends SearchExpressionOptions {
|
|
/**
|
|
* The search expression defining the metrics to be retrieved.
|
|
*
|
|
* A search expression cannot be used within an Alarm.
|
|
*
|
|
* A search expression allows you to retrieve and graph multiple related metrics in a single statement.
|
|
* It can return up to 500 time series.
|
|
*
|
|
* Examples:
|
|
* - `SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)`
|
|
* - `SEARCH('{AWS/ApplicationELB,LoadBalancer} RequestCount', 'Sum', 60)`
|
|
* - `SEARCH('{MyNamespace,ServiceName} Errors', 'Sum')`
|
|
*
|
|
* For more information about search expression syntax, see:
|
|
* https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/search-expression-syntax.html
|
|
*/
|
|
readonly expression: string;
|
|
}
|
|
/**
|
|
* A metric emitted by a service
|
|
*
|
|
* The metric is a combination of a metric identifier (namespace, name and dimensions)
|
|
* and an aggregation function (statistic, period and unit).
|
|
*
|
|
* It also contains metadata which is used only in graphs, such as color and label.
|
|
* It makes sense to embed this in here, so that compound constructs can attach
|
|
* that metadata to metrics they expose.
|
|
*
|
|
* This class does not represent a resource, so hence is not a construct. Instead,
|
|
* Metric is an abstraction that makes it easy to specify metrics for use in both
|
|
* alarms and graphs.
|
|
*/
|
|
export declare class Metric implements IMetric {
|
|
#private;
|
|
/**
|
|
* Creates an anomaly detection metric from the provided metric
|
|
*
|
|
* @param props The anomaly detection alarm properties
|
|
* @returns An anomaly detection metric
|
|
*/
|
|
static anomalyDetectionFor(props: AnomalyDetectionMetricOptions): MathExpression;
|
|
/**
|
|
* Grant permissions to the given identity to write metrics.
|
|
*
|
|
* @param grantee The IAM identity to give permissions to.
|
|
*/
|
|
static grantPutMetricData(grantee: iam.IGrantable): iam.Grant;
|
|
/** Dimensions of this metric */
|
|
readonly dimensions?: DimensionHash;
|
|
/** Namespace of this metric */
|
|
readonly namespace: string;
|
|
/** Name of this metric */
|
|
readonly metricName: string;
|
|
/** Period of this metric */
|
|
readonly period: cdk.Duration;
|
|
/** Statistic of this metric */
|
|
readonly statistic: string;
|
|
/** Label for this metric when added to a Graph in a Dashboard */
|
|
readonly label?: string;
|
|
/** The hex color code used when this metric is rendered on a graph. */
|
|
readonly color?: string;
|
|
/** Unique identifier for this metric when used in dashboard widgets. */
|
|
readonly id?: string;
|
|
/** Whether this metric should be visible in dashboard graphs. */
|
|
readonly visible?: boolean;
|
|
/** Unit of the metric. */
|
|
readonly unit?: Unit;
|
|
/**
|
|
* Warnings attached to this metric.
|
|
* @deprecated - use warningsV2
|
|
**/
|
|
readonly warnings?: string[];
|
|
/** Warnings attached to this metric. */
|
|
readonly warningsV2?: {
|
|
[id: string]: string;
|
|
};
|
|
constructor(props: MetricProps);
|
|
/**
|
|
* Return a copy of Metric `with` properties changed.
|
|
*
|
|
* All properties except namespace and metricName can be changed.
|
|
*
|
|
* @param props The set of properties to change.
|
|
*/
|
|
with(props: MetricOptions): Metric;
|
|
/**
|
|
* Attach the metric object to the given construct scope
|
|
*
|
|
* Returns a Metric object that uses the account and region from the Stack
|
|
* the given construct is defined in. If the metric is subsequently used
|
|
* in a Dashboard or Alarm in a different Stack defined in a different
|
|
* account or region, the appropriate 'region' and 'account' fields
|
|
* will be added to it.
|
|
*
|
|
* If the scope we attach to is in an environment-agnostic stack,
|
|
* nothing is done and the same Metric object is returned.
|
|
*/
|
|
attachTo(scope: IConstruct): Metric;
|
|
/**
|
|
* Account which this metric comes from.
|
|
*/
|
|
get account(): string | undefined;
|
|
/**
|
|
* Region which this metric comes from.
|
|
*/
|
|
get region(): string | undefined;
|
|
toMetricConfig(): MetricConfig;
|
|
/**
|
|
* Make a new Alarm for this metric
|
|
*
|
|
* Combines both properties that may adjust the metric (aggregation) as well
|
|
* as alarm properties.
|
|
*/
|
|
createAlarm(scope: Construct, id: string, props: CreateAlarmOptions): Alarm;
|
|
toString(): string;
|
|
/**
|
|
* Return the dimensions of this Metric as a list of Dimension.
|
|
*/
|
|
private dimensionsAsList;
|
|
private validateDimensions;
|
|
}
|
|
/**
|
|
* A math expression built with metric(s) emitted by a service
|
|
*
|
|
* The math expression is a combination of an expression (x+y) and metrics to apply expression on.
|
|
* It also contains metadata which is used only in graphs, such as color and label.
|
|
* It makes sense to embed this in here, so that compound constructs can attach
|
|
* that metadata to metrics they expose.
|
|
*
|
|
* MathExpression can also be used for search expressions. In this case,
|
|
* it also optionally accepts a searchRegion and searchAccount property for cross-environment
|
|
* search expressions.
|
|
*
|
|
* This class does not represent a resource, so hence is not a construct. Instead,
|
|
* MathExpression is an abstraction that makes it easy to specify metrics for use in both
|
|
* alarms and graphs.
|
|
*/
|
|
export declare class MathExpression implements IMetric {
|
|
/**
|
|
* The expression defining the metric.
|
|
*/
|
|
readonly expression: string;
|
|
/**
|
|
* The metrics used in the expression as KeyValuePair <id, metric>.
|
|
*/
|
|
readonly usingMetrics: Record<string, IMetric>;
|
|
/**
|
|
* Label for this metric when added to a Graph.
|
|
*/
|
|
readonly label?: string;
|
|
/**
|
|
* The hex color code, prefixed with '#' (e.g. '#00ff00'), to use when this metric is rendered on a graph.
|
|
* The `Color` class has a set of standard colors that can be used here.
|
|
*/
|
|
readonly color?: string;
|
|
/**
|
|
* Aggregation period of this metric
|
|
*/
|
|
readonly period: cdk.Duration;
|
|
/**
|
|
* Account to evaluate search expressions within.
|
|
*/
|
|
readonly searchAccount?: string;
|
|
/**
|
|
* Region to evaluate search expressions within.
|
|
*/
|
|
readonly searchRegion?: string;
|
|
/**
|
|
* Warnings generated by this math expression
|
|
* @deprecated - use warningsV2
|
|
*/
|
|
readonly warnings?: string[];
|
|
/**
|
|
* Warnings generated by this math expression
|
|
*/
|
|
readonly warningsV2?: {
|
|
[id: string]: string;
|
|
};
|
|
constructor(props: MathExpressionProps);
|
|
/**
|
|
* Return a copy of Metric with properties changed.
|
|
*
|
|
* All properties except namespace and metricName can be changed.
|
|
*
|
|
* @param props The set of properties to change.
|
|
*/
|
|
with(props: MathExpressionOptions): MathExpression;
|
|
toMetricConfig(): MetricConfig;
|
|
/**
|
|
* Make a new Alarm for this metric
|
|
*
|
|
* Combines both properties that may adjust the metric (aggregation) as well
|
|
* as alarm properties.
|
|
*/
|
|
createAlarm(scope: Construct, id: string, props: CreateAlarmOptions): Alarm;
|
|
toString(): string;
|
|
private validateNoIdConflicts;
|
|
}
|
|
/**
|
|
* A CloudWatch search expression for dynamically finding and graphing multiple related metrics.
|
|
*
|
|
* Search expressions allow you to search for and graph multiple related metrics from a single expression.
|
|
* This is particularly useful in dynamic environments where the exact metric names or dimensions
|
|
* may not be known at deployment time.
|
|
*
|
|
* Example:
|
|
* ```ts
|
|
* const searchExpression = new cloudwatch.SearchExpression({
|
|
* expression: "SEARCH('{AWS/EC2,InstanceId} CPUUtilization', 'Average', 300)",
|
|
* label: 'EC2 CPU Utilization',
|
|
* period: Duration.minutes(5),
|
|
* });
|
|
* ```
|
|
*
|
|
* This class does not represent a resource, so hence is not a construct. Instead,
|
|
* SearchExpression is an abstraction that makes it easy to specify metrics for use in graphs.
|
|
*/
|
|
export declare class SearchExpression implements IMetric {
|
|
/**
|
|
* The search expression defining the metrics to be retrieved.
|
|
*/
|
|
readonly expression: string;
|
|
/**
|
|
* The label is used as a prefix for the title of each metric returned by the search expression.
|
|
*/
|
|
readonly label?: string;
|
|
/**
|
|
* Hex color code (e.g. '#00ff00'), to use when rendering the resulting metrics in a graph.
|
|
* If multiple time series are returned, color is assigned to the first metric, color for the other metrics is automatically assigned
|
|
*/
|
|
readonly color?: string;
|
|
/**
|
|
* The aggregation period for the metrics produced by the Search Expression.
|
|
*/
|
|
readonly period: cdk.Duration;
|
|
/**
|
|
* Account to evaluate search expressions within.
|
|
*/
|
|
readonly searchAccount?: string;
|
|
/**
|
|
* Region to evaluate search expressions within.
|
|
*/
|
|
readonly searchRegion?: string;
|
|
/**
|
|
* Warnings generated by this search expression
|
|
* @deprecated - use warningsV2
|
|
*/
|
|
readonly warnings?: string[];
|
|
/**
|
|
* Warnings generated by this search expression
|
|
*/
|
|
readonly warningsV2?: {
|
|
[id: string]: string;
|
|
};
|
|
constructor(props: SearchExpressionProps);
|
|
/**
|
|
* Return a copy of SearchExpression with properties changed.
|
|
*
|
|
* All properties except expression can be changed.
|
|
*
|
|
* @param props The set of properties to change.
|
|
*/
|
|
with(props: SearchExpressionOptions): SearchExpression;
|
|
toMetricConfig(): MetricConfig;
|
|
toString(): string;
|
|
}
|
|
/**
|
|
* Properties needed to make an alarm from a metric
|
|
*/
|
|
export interface CreateAlarmOptions extends CreateAlarmOptionsBase {
|
|
/**
|
|
* Comparison to use to check if metric is breaching
|
|
*
|
|
* @default GreaterThanOrEqualToThreshold
|
|
*/
|
|
readonly comparisonOperator?: ComparisonOperator;
|
|
/**
|
|
* The value against which the specified statistic is compared.
|
|
*/
|
|
readonly threshold: number;
|
|
}
|
|
/**
|
|
* Properties needed to make an anomaly detection alarm from a metric
|
|
*/
|
|
export interface AnomalyDetectionMetricOptions extends MathExpressionOptions {
|
|
/**
|
|
* 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;
|
|
}
|