@pulumi/awsx
Version:
[](https://github.com/pulumi/pulumi-awsx/actions) [](https://slack.pulumi.com) [ • 17.5 kB
TypeScript
import * as aws from "@pulumi/aws";
import * as pulumi from "@pulumi/pulumi";
import * as wjson from "./widgets_json";
/**
* Metrics are the fundamental concept in CloudWatch. A metric represents a time-ordered set of data
* points that are published to CloudWatch. Think of a metric as a variable to monitor, and the data
* points as representing the values of that variable over time. For example, the CPU usage of a
* particular EC2 instance is one metric provided by Amazon EC2. The data points themselves can come
* from any application or business activity from which you collect data.
*
* AWS services send metrics to CloudWatch, and you can send your own custom metrics to CloudWatch.
* You can add the data points in any order, and at any rate you choose. You can retrieve statistics
* about those data points as an ordered set of time-series data.
*
* Metrics exist only in the region in which they are created. Metrics cannot be deleted, but they
* automatically expire after 15 months if no new data is published to them. Data points older than
* 15 months expire on a rolling basis; as new data points come in, data older than 15 months is
* dropped.
*
* Metrics are uniquely defined by a name, a namespace, and zero or more dimensions. Each data point
* in a metric has a time stamp, and (optionally) a unit of measure. You can retrieve statistics
* from CloudWatch for any metric.
*
* see https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html#Metric
* for more details.
*/
export declare class Metric {
/**
* Optional resource this is a metric for. Used only for parenting purposes when making new alarms.
*/
readonly resource: pulumi.Resource | undefined;
/**
* The namespace for this metric. See docs for the
* [list of namespaces](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/aws-namespaces.html).
* See docs for
* [supported metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html).
*/
readonly namespace: pulumi.Output<string>;
/**
* The name for this metric. See docs for
* [supported metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html).
*/
readonly name: pulumi.Output<string>;
/**
* The dimensions for this metric. For the list of available dimensions see the AWS documentation
* [here](http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html).
*/
readonly dimensions: pulumi.Output<Record<string, string>> | undefined;
/**
* The period in seconds over which the specified [statistic] is applied. Must be in multiples
* of 60. Periods are defined in numbers of seconds, and valid values for period are 1, 5, 10,
* 30, or any multiple of 60. For example, to specify a period of six minutes, use 360 as the
* period value. You can adjust how the data is aggregated by varying the length of the period.
* A period can be as short as one second or as long as one day (86,400 seconds). The default
* value is 60 seconds.
*
* See https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/cloudwatch_concepts.html
* for more details.
*/
readonly period: pulumi.Output<number>;
/**
* The statistic to apply to the alarm's associated metric. Either of the following is
* supported: `SampleCount`, `Average`, `Sum`, `Minimum`, `Maximum`.
*
* Defaults to [Average] if [statistic] and [extendedStatistic] is unspecified.
*/
readonly statistic: pulumi.Output<MetricStatistic>;
/**
* The percentile statistic for the metric associated with the alarm. Specify a value between
* [0.0] and [100].
*/
readonly extendedStatistic: pulumi.Output<number | undefined>;
/**
* The unit for this metric.
*
* See https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html
*/
readonly unit: pulumi.Output<MetricUnit | undefined>;
/**
* The six-digit HTML hex color code to be used for this metric.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
readonly color: pulumi.Output<string | undefined>;
/**
* The label to display for this metric in the graph legend. If this is not specified, the
* metric is given an autogenerated label that distinguishes it from the other metrics in the
* widget.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
readonly label: pulumi.Output<string | undefined>;
/**
* Set this to true to have the metric appear in the graph, or false to have it be hidden. The
* default is true.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
readonly visible: pulumi.Output<boolean>;
/**
* Where on the graph to display the y-axis for this metric. The default is left.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
readonly yAxis: pulumi.Output<"left" | "right">;
/**
* The id of this metric. This id can be used as part of a math expression.
*/
readonly id: pulumi.Output<string | undefined>;
/**
* @param resource Optional resource this is a metric for. This is only used for parenting
* purposes. i.e. if an [Alarm] is created from this [Metric], then [resource] will be used as
* the parent of the alarm by default.
*/
constructor(args: MetricArgs, resource?: pulumi.Resource);
with(change: MetricChange | undefined): Metric;
private features;
private spread;
/**
* Produces a new [Metric] instances with the specific [dimensions] of this instance overwritten
* with the [dimensions] pass in as arguments. Because this is a merging, to unset a particular
* dimension, pass in an explicit value of `{ name: undefined }`. To clear all dimensions, pass
* in `undefined` for the entire argument.
*/
withDimensions(dimensions: pulumi.Input<Record<string, pulumi.Input<string>>> | undefined): Metric;
withPeriod(period: pulumi.Input<number> | undefined): Metric;
withUnit(unit: pulumi.Input<MetricUnit> | undefined): Metric;
withColor(color: pulumi.Input<string> | undefined): Metric;
withLabel(label: pulumi.Input<string> | undefined): Metric;
withVisible(visible: pulumi.Input<boolean> | undefined): Metric;
withYAxis(yAxis: pulumi.Input<"left" | "right"> | undefined): Metric;
withId(id: pulumi.Input<string> | undefined): Metric;
withStatistic(statistic: pulumi.Input<MetricStatistic> | undefined): Metric;
withExtendedStatistic(extendedStatistic: pulumi.Input<number> | undefined): Metric;
createAlarm(name: string, args: AlarmArgs, opts?: pulumi.CustomResourceOptions): import("@pulumi/aws/cloudwatch/metricAlarm").MetricAlarm;
/** For internal use only. */
addWidgetJson(metrics: wjson.MetricJson[]): void;
}
/**
* Interface for all the parts of a metric that can be changed.
*/
export interface MetricChange {
/**
* The new dimension for this metric. If this object is missing this property, then no change
* will be made. However, if the property is there by set to [undefined] then the value will be
* cleared.
*/
dimensions?: pulumi.Input<Record<string, pulumi.Input<string>>>;
/**
* The new period in seconds over which the specified `stat` is applied. If this object is
* missing this property, then no change will be made. However, if the property is there by set
* to [undefined] then the value will be set to the default (300s).
*/
period?: pulumi.Input<number>;
/**
* The new statistic to apply to the alarm's associated metric. If this object is missing this
* property, then no change will be made. However, if the property is there by set to
* [undefined] then the value will be set to the default.
*/
statistic?: pulumi.Input<MetricStatistic>;
/**
* The new percentile statistic for the metric associated with the alarm. If this object is
* missing this property, then no change will be made. However, if the property is there by set
* to [undefined] then the value will be set to the default.
*/
extendedStatistic?: pulumi.Input<number>;
/**
* The new unit for this metric. If this object is missing this property, then no change will
* be made. However, if the property is there by set to [undefined] then the value will be set
* to the default.
*/
unit?: pulumi.Input<MetricUnit>;
/**
* The six-digit HTML hex color code to be used for this metric.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
color?: pulumi.Input<string>;
/**
* The label to display for this metric in the graph legend. If this is not specified, the
* metric is given an autogenerated label that distinguishes it from the other metrics in the
* widget.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
label?: pulumi.Input<string>;
/**
* Set this to true to have the metric appear in the graph, or false to have it be hidden. The
* default is true.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
visible?: pulumi.Input<boolean>;
/**
* Where on the graph to display the y-axis for this metric. The default is left.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
yAxis?: pulumi.Input<"left" | "right">;
/**
* The id of this metric. This id can be used as part of a math expression.
*/
id?: pulumi.Input<string>;
}
export type AlarmComparisonOperator = "GreaterThanOrEqualToThreshold" | "GreaterThanThreshold" | "LessThanThreshold" | "LessThanOrEqualToThreshold";
export interface AlarmArgs {
/**
* Indicates whether or not actions should be executed during any changes to the alarm's state.
* Defaults to `true`.
*/
actionsEnabled?: pulumi.Input<boolean>;
/**
* The list of actions to execute when this alarm transitions into an ALARM state from any other
* state. Each action is specified as an Amazon Resource Name (ARN).
*/
alarmActions?: pulumi.Input<pulumi.Input<string | aws.sns.Topic>[]>;
/**
* The description for the alarm.
*/
alarmDescription?: pulumi.Input<string>;
/**
* The descriptive name for the alarm. This name must be unique within the user's AWS account
*/
name?: pulumi.Input<string>;
/**
* The arithmetic operation to use when comparing the specified Statistic and Threshold. The
* specified Statistic value is used as the first operand. Either of the following is supported:
* `GreaterThanOrEqualToThreshold`, `GreaterThanThreshold`, `LessThanThreshold`,
* `LessThanOrEqualToThreshold`.
*
* Defaults to [GreaterThanOrEqualToThreshold] if unspecified.
*/
comparisonOperator?: pulumi.Input<AlarmComparisonOperator>;
/**
* The number of datapoints that must be breaching to trigger the alarm.
*/
datapointsToAlarm?: pulumi.Input<number>;
/**
* Used only for alarms based on percentiles. If you specify `ignore`, the alarm state will not
* change during periods with too few data points to be statistically significant. If you
* specify `evaluate` or omit this parameter, the alarm will always be evaluated and possibly
* change state no matter how many data points are available. The following values are
* supported: `ignore`, and `evaluate`.
*/
evaluateLowSampleCountPercentiles?: pulumi.Input<"ignore" | "evaluate">;
/**
* The number of periods over which data is compared to the specified threshold.
*/
evaluationPeriods: pulumi.Input<number>;
/**
* The percentile statistic for the metric associated with the alarm. Specify a value between
* p0.0 and p100.
*/
extendedStatistic?: pulumi.Input<string>;
/**
* The list of actions to execute when this alarm transitions into an INSUFFICIENT_DATA state
* from any other state. Each action is specified as an Amazon Resource Name (ARN).
*/
insufficientDataActions?: pulumi.Input<pulumi.Input<string | aws.sns.Topic>[]>;
/**
* Enables you to create an alarm based on a metric math expression. You may specify at most 20.
*/
metricQueries?: pulumi.Input<pulumi.Input<{
expression?: pulumi.Input<string>;
id: pulumi.Input<string>;
label?: pulumi.Input<string>;
metric?: pulumi.Input<{
dimensions?: pulumi.Input<{
[key: string]: string;
}>;
metricName: pulumi.Input<string>;
namespace?: pulumi.Input<string>;
period: pulumi.Input<number>;
stat: pulumi.Input<string>;
unit?: pulumi.Input<string>;
}>;
returnData?: pulumi.Input<boolean>;
}>[]>;
/**
* The list of actions to execute when this alarm transitions into an OK state from any other
* state. Each action is specified as an Amazon Resource Name (ARN).
*/
okActions?: pulumi.Input<pulumi.Input<string | aws.sns.Topic>[]>;
/**
* The value against which the specified statistic is compared.
*/
threshold: pulumi.Input<number>;
/**
* Sets how this alarm is to handle missing data points. The following values are supported:
* `missing`, `ignore`, `breaching` and `notBreaching`. Defaults to `missing`.
*/
treatMissingData?: pulumi.Input<"missing" | "ignore" | "breaching" | "notBreaching">;
}
export interface MetricArgs {
/**
* The namespace for this metric. See docs for the
* [list of namespaces](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/aws-namespaces.html).
* See docs for
* [supported metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html).
*/
namespace: pulumi.Input<string>;
/**
* The name for this metric. See docs for
* [supported metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html).
*/
name: pulumi.Input<string>;
/**
* The dimensions for this metric. For the list of available dimensions see the AWS documentation
* [here](http://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/CW_Support_For_AWS.html).
*/
dimensions?: pulumi.Input<Record<string, pulumi.Input<string>>>;
/**
* The period in seconds over which the specified `stat` is applied. Must be in multiples of 60.
* Default to [300] if unspecified.
*/
period?: pulumi.Input<number | undefined>;
/**
* The statistic to apply to the alarm's associated metric. Either of the following is
* supported: `SampleCount`, `Average`, `Sum`, `Minimum`, `Maximum`
*/
statistic?: pulumi.Input<MetricStatistic | undefined>;
/**
* The percentile statistic for the metric associated with the alarm. Specify a value between
* [0.0] and [100].
*/
extendedStatistic?: pulumi.Input<number | undefined>;
/**
* The unit for this metric.
*
* See https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/API_MetricDatum.html
*/
unit?: pulumi.Input<MetricUnit | undefined>;
/**
* The six-digit HTML hex color code to be used for this metric.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
color?: pulumi.Input<string | undefined>;
/**
* The label to display for this metric in the graph legend. If this is not specified, the
* metric is given an autogenerated label that distinguishes it from the other metrics in the
* widget.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
label?: pulumi.Input<string | undefined>;
/**
* Set this to true to have the metric appear in the graph, or false to have it be hidden. The
* default is true.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
visible?: pulumi.Input<boolean | undefined>;
/**
* Where on the graph to display the y-axis for this metric. The default is left.
*
* Only used if this metric is displayed in a [Dashboard] with a [MetricWidget].
*/
yAxis?: pulumi.Input<"left" | "right" | undefined>;
/**
* The id of this metric. This id can be used as part of a math expression.
*/
id?: pulumi.Input<string | undefined>;
}
export type MetricStatistic = "SampleCount" | "Average" | "Sum" | "Minimum" | "Maximum";
export type MetricUnit = "Seconds" | "Microseconds" | "Milliseconds" | "Bytes" | "Kilobytes" | "Megabytes" | "Gigabytes" | "Terabytes" | "Bits" | "Kilobits" | "Megabits" | "Gigabits" | "Terabits" | "Percent" | "Count" | "Bytes/Second" | "Kilobytes/Second" | "Megabytes/Second" | "Gigabytes/Second" | "Terabytes/Second" | "Bits/Second" | "Kilobits/Second" | "Megabits/Second" | "Gigabits/Second" | "Terabits/Second" | "Count/Second" | "None";