@cdklabs/multi-az-observability 0.0.1-alpha.4 → 0.0.1-alpha.40

package/README.md

@@ -1,7 +1,9 @@
+![Build Workflow](https://github.com/cdklabs/cdk-multi-az-observability/actions/workflows/build.yml/badge.svg) ![Release Workflow](https://github.com/cdklabs/cdk-multi-az-observability/actions/workflows/release.yml/badge.svg) ![GitHub Release](https://img.shields.io/github/v/release/cdklabs/cdk-multi-az-observability?include_prereleases&sort=semver&logo=github&label=version)
+
 # multi-az-observability
 This is a CDK construct for multi-AZ observability to help detect single-AZ impairments. This is currently an `alpha` version, but is being used in the AWS [Advanced Multi-AZ Resilience Patterns](https://catalog.workshops.aws/multi-az-gray-failures/en-US) workshop.
 
-There is a lot of available information to think through and combine to provide signals about single-AZ impact. To simplify the setup and use reasonable defaults, this construct (available in TypeScript, Go, Python, and .NET [Java coming soon]) sets up the necessary observability. To use the CDK construct, you first define your service like this:
+There is a lot of available information to think through and combine to provide signals about single-AZ impact. To simplify the setup and use reasonable defaults, this construct (available in [TypeScript](https://www.npmjs.com/package/@cdklabs/multi-az-observability), [Go](https://github.com/cdklabs/cdk-multi-az-observability-go), [Python](https://pypi.org/project/cdklabs.multi-az-observability/), [.NET](https://www.nuget.org/packages/Cdklabs.MultiAZObservability), and [Java](https://central.sonatype.com/artifact/io.github.cdklabs/cdk-multi-az-observability)) sets up the necessary observability. To use the CDK construct, you first define your service like this:
 
 ```csharp
 var wildRydesService = new Service(new ServiceProps(){
@@ -35,7 +37,7 @@ var wildRydesService = new Service(new ServiceProps(){
         GraphedSuccessStatistics = new string[] { "p50", "p99", "tm50", "tm99" },
         MetricNamespace = metricsNamespace,
         Period = Duration.Seconds(60),
-        SuccessAlarmThreshold = 100,
+        SuccessAlarmThreshold = Duration.Millis(100),
         SuccessMetricNames = new string[] {"SuccessLatency"},
         Unit = Unit.MILLISECONDS,
     }),
@@ -69,11 +71,11 @@ wildRydesService.AddOperation(new Operation(new OperationProps() {
     }, wildRydesService.DefaultAvailabilityMetricDetails),
     ServerSideLatencyMetricDetails = new OperationMetricDetails(new OperationMetricDetailsProps() {
         OperationName = "Signin",
-        SuccessAlarmThreshold = 150,
+        SuccessAlarmThreshold = Duration.Millis(150),
         MetricDimensions = new MetricDimensions(new Dictionary<string, string> {{ "Operation", "Signin"}}, "AZ-ID", "Region")
     }, wildRydesService.DefaultLatencyMetricDetails),
     CanaryTestLatencyMetricsOverride = new CanaryTestMetricsOverride(new CanaryTestMetricsOverrideProps() {
-        SuccessAlarmThreshold = 250
+        SuccessAlarmThreshold = Duration.Millis(250),
     })
 }));
 wildRydesService.AddOperation(new Operation(new OperationProps() {
@@ -88,11 +90,11 @@ wildRydesService.AddOperation(new Operation(new OperationProps() {
     }, wildRydesService.DefaultAvailabilityMetricDetails),
     ServerSideLatencyMetricDetails = new OperationMetricDetails(new OperationMetricDetailsProps() {
         OperationName = "Pay",
-        SuccessAlarmThreshold = 200,
+        SuccessAlarmThreshold = Duration.Millis(200),
         MetricDimensions = new MetricDimensions(new Dictionary<string, string> {{ "Operation", "Pay"}}, "AZ-ID", "Region")
     }, wildRydesService.DefaultLatencyMetricDetails),
     CanaryTestLatencyMetricsOverride = new CanaryTestMetricsOverride(new CanaryTestMetricsOverrideProps() {
-        SuccessAlarmThreshold = 300
+        SuccessAlarmThreshold = Duration.Millis(300)
     })
 }));
 wildRydesService.AddOperation(new Operation(new OperationProps() {
@@ -107,11 +109,11 @@ wildRydesService.AddOperation(new Operation(new OperationProps() {
     }, wildRydesService.DefaultAvailabilityMetricDetails),
     ServerSideLatencyMetricDetails = new OperationMetricDetails(new OperationMetricDetailsProps() {
         OperationName = "Ride",
-        SuccessAlarmThreshold = 350,
+        SuccessAlarmThreshold = Duration.Millis(350),
         MetricDimensions = new MetricDimensions(new Dictionary<string, string> {{ "Operation", "Ride"}}, "AZ-ID", "Region")
     }, wildRydesService.DefaultLatencyMetricDetails),
     CanaryTestLatencyMetricsOverride = new CanaryTestMetricsOverride(new CanaryTestMetricsOverrideProps() {
-        SuccessAlarmThreshold = 550
+        SuccessAlarmThreshold = Duration.Millis(550)
     })
 }));
 wildRydesService.AddOperation(new Operation(new OperationProps() {
@@ -126,11 +128,11 @@ wildRydesService.AddOperation(new Operation(new OperationProps() {
     }, wildRydesService.DefaultAvailabilityMetricDetails),
     ServerSideLatencyMetricDetails = new OperationMetricDetails(new OperationMetricDetailsProps() {
         OperationName = "Home",
-        SuccessAlarmThreshold = 100,
+        SuccessAlarmThreshold = Duration.Millis(100),
         MetricDimensions = new MetricDimensions(new Dictionary<string, string> {{ "Operation", "Ride"}}, "AZ-ID", "Region")
     }, wildRydesService.DefaultLatencyMetricDetails),
     CanaryTestLatencyMetricsOverride = new CanaryTestMetricsOverride(new CanaryTestMetricsOverrideProps() {
-        SuccessAlarmThreshold = 200
+        SuccessAlarmThreshold = Duration.Millis(200)
     })
 }));
 ```
@@ -146,30 +148,35 @@ InstrumentedServiceMultiAZObservability multiAvailabilityZoneObservability = new
 });
 ```
 
-You define some characteristics of the service, default values for metrics and alarms, and then add operations as well as any overrides for default values that you need. The construct can also automatically create synthetic canaries that test each operation with a very simple HTTP check, or you can configure your own synthetics and just tell the construct about the metric details and optionally log files. This creates metrics, alarms, and dashboards that can be used to detect single-AZ impact.
+You define some characteristics of the service, default values for metrics and alarms, and then add operations as well as any overrides for default values that you need. The construct can also automatically create synthetic canaries that test each operation with a very simple HTTP check, or you can configure your own synthetics and just tell the construct about the metric details and optionally log files. This creates metrics, alarms, and dashboards that can be used to detect single-AZ impact. You can access these alarms from the `multiAvailabilityZoneObservability` object and use them in your CDK project to start automation, send SNS notifications, or incorporate in your own dashboards.
 
-If you don't have service specific logs and custom metrics with per-AZ dimensions, you can still use the construct to evaluate ALB and NAT Gateway metrics to find single AZ faults.
+If you don't have service specific logs and custom metrics with per-AZ dimensions, you can still use the construct to evaluate ALB and/or NAT Gateway metrics to find single AZ impairments.
 
 ```csharp
-BasicServiceMultiAZObservability multiAvailabilityZoneObservability = new BasicServiceMultiAZObservability(this, "MultiAZObservability", new BasicServiceMultiAZObservabilityProps() {
-    ApplicationLoadBalancers = new IApplicationLoadBalancer[] { loadBalancer },
-    NatGateways = new Dictionary<string, CfnNatGateway>() {
-        { "us-east-1a", natGateway1},
-        { "us-east-1b", natGateway2},
-        { "us-east-1c", natGateway3},
+BasicServiceMultiAZObservability multiAZObservability = new BasicServiceMultiAZObservability(this, "basic-service-", new BasicServiceMultiAZObservabilityProps() {  
+    ApplicationLoadBalancerProps = new ApplicationLoadBalancerDetectionProps() {
+        ApplicationLoadBalancers = [ myALB ],
+        LatencyStatistic = Stats.Percentile(99),
+        FaultCountPercentThreshold = 1,
+        LatencyThreshold = Duration.Millis(500)
+    },
+    NatGatewayProps = new NatGatewayDetectionProps() {     
+        PacketLossPercentThreshold = 0.01,
+        NatGateways = {
+           { "us-east-1a", [ natGateway1 ] },
+           { "us-east-1b", [ natGateway2 ] },
+           { "us-east-1c", [ natGateway3 ] }
+        },
     },
     CreateDashboard = true,
-    OutlierDetectionAlgorithm = OutlierDetectionAlgorithm.STATIC,
-    FaultCountPercentageThreshold = 1.0, // The fault rate to alarm on for errors seen from the ALBs in the same AZ
-    PacketLossImpactPercentageThreshold = 0.01, // The percentage of packet loss to alarm on for the NAT Gateways in the same AZ
+    DatapointsToAlarm = 2,
+    EvaluationPeriods = 3,
     ServiceName = "WildRydes",
-    Period = Duration.Seconds(60), // The period for metric evaluation
-    Interval = Duration.Minutes(60) // The interval for the dashboards
-    EvaluationPeriods = 5,
-    DatapointsToAlarm = 3
+    Period = Duration.Seconds(60),
+    Interval = Duration.Minutes(60),          
 });
 ```
 
 If you provide a load balancer, the construct assumes it is deployed in each AZ of the VPC the load balancer is associated with and will look for HTTP metrics using those AZs as dimensions.
 
-Both options support running workloads on EC2, ECS, Lambda, and EKS.
+Both options support running workloads on EC2, ECS, Lambda, and EKS.

package/cdk.json

@@ -1,5 +1,5 @@
 {
-  "app": "npx ts-node --prefer-ts-exts test/synth-test.ts",
+  "app": "npx ts-node --prefer-ts-exts test/basic-service-synth-test.ts",
   "watch": {
     "include": [
       "**"

package/lib/alarmsandrules/AvailabilityAndLatencyAlarmsAndRules.d.ts

@@ -9,6 +9,8 @@ import { IContributorInsightRuleDetails } from '../services/IContributorInsightR
 import { IOperation } from '../services/IOperation';
 import { IOperationMetricDetails } from '../services/IOperationMetricDetails';
 import { OutlierDetectionAlgorithm } from '../utilities/OutlierDetectionAlgorithm';
+import { IOperationAvailabilityMetricDetails } from '../services/IOperationAvailabilityMetricDetails';
+import { IOperationLatencyMetricDetails } from '../services/IOperationLatencyMetricDetails';
 /**
  * Class used to create availability and latency alarms and Contributor Insight rules
  */
@@ -22,7 +24,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param counter
      * @returns
      */
-    static createZonalAvailabilityAlarm(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, counter: number, nameSuffix?: string): IAlarm;
+    static createZonalAvailabilityAlarm(scope: Construct, metricDetails: IOperationAvailabilityMetricDetails, availabilityZone: string, availabilityZoneId: string, counter: number, nameSuffix?: string): IAlarm;
     /**
      * Creates a zonal latency alarm
      * @param scope
@@ -32,7 +34,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param counter
      * @returns
      */
-    static createZonalLatencyAlarm(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, counter: number, nameSuffix?: string): IAlarm;
+    static createZonalLatencyAlarm(scope: Construct, metricDetails: IOperationLatencyMetricDetails, availabilityZone: string, availabilityZoneId: string, counter: number, nameSuffix?: string): IAlarm;
     /**
      * Creates a composite alarm when either latency or availability is breached in the Availabiltiy Zone
      * @param scope
@@ -55,7 +57,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param outlierThreshold
      * @returns
      */
-    static createZonalFaultRateStaticOutlierAlarm(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
+    static createZonalFaultRateStaticOutlierAlarm(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZone: string, availabilityZoneId: string, counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
     /**
    * An alarm that compares error rate in this AZ to the overall region error based only on metric data.
    * This is different for canaries because the metrics they test at the regional level are different
@@ -69,15 +71,15 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
    * @param outlierThreshold
    * @returns
    */
-    static createZonalFaultRateStaticOutlierAlarmForCanaries(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, availabilityZones: string[], counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
+    static createZonalFaultRateStaticOutlierAlarmForCanaries(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZone: string, availabilityZoneId: string, availabilityZoneIds: string[], counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
     static createZonalFaultRateOutlierAlarm(scope: IConstruct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, allAvailabilityZoneIds: string[], outlierThreshold: number, outlierDetectionFunction: IFunction, outlierDetectionAlgorithm: OutlierDetectionAlgorithm, counter: number, nameSuffix?: string): IAlarm;
     static createZonalFaultRateOutlierAlarmForAlb(scope: IConstruct, loadBalancers: IApplicationLoadBalancer[], availabilityZoneId: string, outlierThreshold: number, outlierDetectionFunction: IFunction, outlierDetectionAlgorithm: OutlierDetectionAlgorithm, azMapper: IAvailabilityZoneMapper, counter: number, evaluationPeriods: number, datapointsToAlarm: number, period: Duration, nameSuffix?: string): IAlarm;
     static createZonalFaultRateOutlierAlarmForNatGW(scope: IConstruct, natGateways: {
         [key: string]: CfnNatGateway[];
     }, availabilityZoneId: string, outlierThreshold: number, outlierDetectionFunction: IFunction, outlierDetectionAlgorithm: OutlierDetectionAlgorithm, azMapper: IAvailabilityZoneMapper, counter: number, evaluationPeriods: number, datapointsToAlarm: number, period: Duration, nameSuffix?: string): IAlarm;
-    static createZonalHighLatencyOutlierAlarm(scope: IConstruct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, allAvailabilityZoneIds: string[], outlierThreshold: number, outlierDetectionFunction: IFunction, outlierDetectionAlgorithm: OutlierDetectionAlgorithm, counter: number, nameSuffix?: string): IAlarm;
-    static createZonalHighLatencyStaticOutlierAlarm(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
-    static createZonalHighLatencyStaticOutlierAlarmForCanaries(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, availabilityZones: string[], counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
+    static createZonalHighLatencyOutlierAlarm(scope: IConstruct, metricDetails: IOperationLatencyMetricDetails, availabilityZoneId: string, allAvailabilityZoneIds: string[], outlierThreshold: number, outlierDetectionFunction: IFunction, outlierDetectionAlgorithm: OutlierDetectionAlgorithm, counter: number, nameSuffix?: string): IAlarm;
+    static createZonalHighLatencyStaticOutlierAlarm(scope: Construct, metricDetails: IOperationLatencyMetricDetails, availabilityZone: string, availabilityZoneId: string, counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
+    static createZonalHighLatencyStaticOutlierAlarmForCanaries(scope: Construct, metricDetails: IOperationLatencyMetricDetails, availabilityZone: string, availabilityZoneId: string, availabilityZones: string[], counter: number, outlierThreshold: number, nameSuffix?: string): IAlarm;
     /**
      * An insight rule that calculates how many instances are responding to requests in
      * the specified AZ. Only useful for server-side metrics since the canary doesn't record instance id metrics.
@@ -120,7 +122,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param counter
      * @returns
      */
-    static createServerSideInstanceHighLatencyContributorsInThisAZRule(scope: Construct, metricDetails: IOperationMetricDetails, availabilityZoneId: string, ruleDetails: IContributorInsightRuleDetails, counter: number, nameSuffix?: string): CfnInsightRule;
+    static createServerSideInstanceHighLatencyContributorsInThisAZRule(scope: Construct, metricDetails: IOperationLatencyMetricDetails, availabilityZoneId: string, ruleDetails: IContributorInsightRuleDetails, counter: number, nameSuffix?: string): CfnInsightRule;
     /**
      * An alarm that indicates some percentage of the instances in this AZ are producing errors. Only
      * useful for server-side metrics since the canary doesn't record instance id metrics.
@@ -204,7 +206,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param counter
      * @returns
      */
-    static createRegionalAvailabilityAlarm(scope: Construct, metricDetails: IOperationMetricDetails, nameSuffix: string): IAlarm;
+    static createRegionalAvailabilityAlarm(scope: Construct, metricDetails: IOperationAvailabilityMetricDetails, nameSuffix: string): IAlarm;
     /**
      * Creates a regional latency alarm for the operation
      * @param scope
@@ -213,7 +215,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param counter
      * @returns
      */
-    static createRegionalLatencyAlarm(scope: Construct, metricDetails: IOperationMetricDetails, nameSuffix: string): IAlarm;
+    static createRegionalLatencyAlarm(scope: Construct, metricDetails: IOperationLatencyMetricDetails, nameSuffix: string): IAlarm;
     /**
      * A composite alarm combining latency and availability alarms for this operation in the region
      * as measured from either the server side or canary
@@ -224,7 +226,7 @@ export declare class AvailabilityAndLatencyAlarmsAndRules {
      * @param regionalLatencyAlarm
      * @returns
      */
-    static createRegionalCustomerExperienceAlarm(scope: Construct, operationName: string, nameSuffix: string, regionalAvailabilityAlarm: IAlarm, regionalLatencyAlarm: IAlarm): IAlarm;
-    static createRegionalInstanceContributorsToHighLatency(scope: Construct, metricDetails: IOperationMetricDetails, ruleDetails: IContributorInsightRuleDetails): CfnInsightRule;
+    static createRegionalAvailabilityOrLatencyImpactAlarm(scope: Construct, operationName: string, nameSuffix: string, regionalAvailabilityAlarm: IAlarm, regionalLatencyAlarm: IAlarm): IAlarm;
+    static createRegionalInstanceContributorsToHighLatency(scope: Construct, metricDetails: IOperationLatencyMetricDetails, ruleDetails: IContributorInsightRuleDetails): CfnInsightRule;
     static createRegionalInstanceContributorsToFaults(scope: Construct, metricDetails: IOperationMetricDetails, ruleDetails: IContributorInsightRuleDetails): CfnInsightRule;
 }