@ts-cloud/core 0.2.3 → 0.2.4

package/dist/modules/monitoring.d.ts

@@ -0,0 +1,574 @@
+import type { CloudWatchAlarm, CloudWatchDashboard, CloudWatchLogGroup, CloudWatchLogStream, CloudWatchMetricFilter, CloudWatchCompositeAlarm } from '@ts-cloud/aws-types';
+import type { EnvironmentType } from '../types';
+export interface AlarmOptions {
+    slug: string;
+    environment: EnvironmentType;
+    alarmName?: string;
+    metricName: string;
+    namespace: string;
+    statistic?: 'Average' | 'Sum' | 'Minimum' | 'Maximum' | 'SampleCount';
+    period?: number;
+    evaluationPeriods?: number;
+    threshold: number;
+    comparisonOperator: 'GreaterThanThreshold' | 'GreaterThanOrEqualToThreshold' | 'LessThanThreshold' | 'LessThanOrEqualToThreshold';
+    treatMissingData?: 'breaching' | 'notBreaching' | 'ignore' | 'missing';
+    actionsEnabled?: boolean;
+    alarmActions?: string[];
+    okActions?: string[];
+    insufficientDataActions?: string[];
+    dimensions?: Record<string, string>;
+    unit?: string;
+    datapointsToAlarm?: number;
+}
+export interface DashboardOptions {
+    slug: string;
+    environment: EnvironmentType;
+    dashboardName?: string;
+    widgets: DashboardWidget[];
+}
+export interface DashboardWidget {
+    type: 'metric' | 'log' | 'text' | 'alarm';
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    properties: Record<string, unknown>;
+}
+export interface LogGroupOptions {
+    slug: string;
+    environment: EnvironmentType;
+    logGroupName?: string;
+    retentionInDays?: number;
+    kmsKeyId?: string;
+}
+export interface LogStreamOptions {
+    slug: string;
+    environment: EnvironmentType;
+    logStreamName?: string;
+}
+export interface MetricFilterOptions {
+    slug: string;
+    environment: EnvironmentType;
+    filterName?: string;
+    filterPattern: string;
+    metricTransformations: MetricTransformation[];
+}
+export interface MetricTransformation {
+    metricName: string;
+    metricNamespace: string;
+    metricValue: string;
+    defaultValue?: number;
+    unit?: string;
+}
+export interface CompositeAlarmOptions {
+    slug: string;
+    environment: EnvironmentType;
+    alarmName?: string;
+    alarmRule: string;
+    actionsEnabled?: boolean;
+    alarmActions?: string[];
+    okActions?: string[];
+    insufficientDataActions?: string[];
+}
+/**
+ * Monitoring Module - CloudWatch
+ * Provides clean API for alarms, dashboards, logs, and metrics
+ */
+export declare class Monitoring {
+    /**
+     * Create a CloudWatch alarm
+     */
+    static createAlarm(options: AlarmOptions): {
+        alarm: CloudWatchAlarm;
+        logicalId: string;
+    };
+    /**
+     * Create a composite alarm (combines multiple alarms)
+     */
+    static createCompositeAlarm(options: CompositeAlarmOptions): {
+        alarm: CloudWatchCompositeAlarm;
+        logicalId: string;
+    };
+    /**
+     * Create a CloudWatch dashboard
+     */
+    static createDashboard(options: DashboardOptions): {
+        dashboard: CloudWatchDashboard;
+        logicalId: string;
+    };
+    /**
+     * Create a CloudWatch log group
+     */
+    static createLogGroup(options: LogGroupOptions): {
+        logGroup: CloudWatchLogGroup;
+        logicalId: string;
+    };
+    /**
+     * Create a CloudWatch log stream
+     */
+    static createLogStream(logGroupLogicalId: string, options: LogStreamOptions): {
+        logStream: CloudWatchLogStream;
+        logicalId: string;
+    };
+    /**
+     * Create a metric filter for log group
+     */
+    static createMetricFilter(logGroupLogicalId: string, options: MetricFilterOptions): {
+        metricFilter: CloudWatchMetricFilter;
+        logicalId: string;
+    };
+    /**
+     * Common alarm configurations
+     */
+    static readonly AlarmTypes: {
+        /**
+         * High CPU utilization alarm
+         */
+        readonly highCpu: (slug: string, environment: EnvironmentType, resourceId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * High memory utilization alarm
+         */
+        readonly highMemory: (slug: string, environment: EnvironmentType, resourceId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * High disk utilization alarm
+         */
+        readonly highDisk: (slug: string, environment: EnvironmentType, resourceId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * Lambda error rate alarm
+         */
+        readonly lambdaErrors: (slug: string, environment: EnvironmentType, functionName: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * Lambda throttles alarm
+         */
+        readonly lambdaThrottles: (slug: string, environment: EnvironmentType, functionName: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * API Gateway 5xx errors alarm
+         */
+        readonly apiGateway5xxErrors: (slug: string, environment: EnvironmentType, apiName: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * API Gateway 4xx errors alarm
+         */
+        readonly apiGateway4xxErrors: (slug: string, environment: EnvironmentType, apiName: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * DynamoDB throttled requests alarm
+         */
+        readonly dynamoDBThrottles: (slug: string, environment: EnvironmentType, tableName: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * RDS CPU alarm
+         */
+        readonly rdsCpu: (slug: string, environment: EnvironmentType, dbInstanceId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * RDS free storage alarm
+         */
+        readonly rdsFreeStorage: (slug: string, environment: EnvironmentType, dbInstanceId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * SQS queue depth alarm
+         */
+        readonly sqsQueueDepth: (slug: string, environment: EnvironmentType, queueName: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * ALB target unhealthy alarm
+         */
+        readonly albUnhealthyTargets: (slug: string, environment: EnvironmentType, loadBalancer: string, targetGroup: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * SES bounce rate alarm
+         */
+        readonly sesBounceRate: (slug: string, environment: EnvironmentType, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * SES complaint rate alarm
+         */
+        readonly sesComplaintRate: (slug: string, environment: EnvironmentType, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * Pinpoint SMS delivery failure alarm
+         */
+        readonly smsDeliveryFailure: (slug: string, environment: EnvironmentType, applicationId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * Pinpoint SMS spend alarm
+         */
+        readonly smsSpendLimit: (slug: string, environment: EnvironmentType, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+        /**
+         * Connect missed calls alarm
+         */
+        readonly connectMissedCalls: (slug: string, environment: EnvironmentType, instanceId: string, threshold?: number, snsTopicArn?: string) => AlarmOptions;
+    };
+    /**
+     * Common dashboard widgets
+     */
+    static readonly DashboardWidgets: {
+        /**
+         * Metric widget
+         */
+        readonly metric: (x: number, y: number, width: number, height: number, metrics: Array<[string, string, Record<string, string>?]>, title?: string) => DashboardWidget;
+        /**
+         * Text widget
+         */
+        readonly text: (x: number, y: number, width: number, height: number, markdown: string) => DashboardWidget;
+        /**
+         * Log widget
+         */
+        readonly log: (x: number, y: number, width: number, height: number, logGroupNames: string[], title?: string) => DashboardWidget;
+    };
+    /**
+     * Common log retention periods
+     */
+    static readonly RetentionPeriods: {
+        readonly ONE_DAY: 1;
+        readonly THREE_DAYS: 3;
+        readonly FIVE_DAYS: 5;
+        readonly ONE_WEEK: 7;
+        readonly TWO_WEEKS: 14;
+        readonly ONE_MONTH: 30;
+        readonly TWO_MONTHS: 60;
+        readonly THREE_MONTHS: 90;
+        readonly FOUR_MONTHS: 120;
+        readonly FIVE_MONTHS: 150;
+        readonly SIX_MONTHS: 180;
+        readonly ONE_YEAR: 365;
+        readonly THIRTEEN_MONTHS: 400;
+        readonly EIGHTEEN_MONTHS: 545;
+        readonly TWO_YEARS: 731;
+        readonly FIVE_YEARS: 1827;
+        readonly TEN_YEARS: 3653;
+        readonly NEVER_EXPIRE: undefined;
+    };
+    /**
+     * Common metric filter patterns
+     */
+    static readonly FilterPatterns: {
+        /**
+         * Match ERROR log lines
+         */
+        readonly errors: "[time, request_id, event_type = ERROR*, ...]";
+        /**
+         * Match all log lines
+         */
+        readonly all: "";
+        /**
+         * Match JSON logs with specific field
+         */
+        readonly jsonField: (field: string, value: string) => string;
+        /**
+         * Match HTTP status codes
+         */
+        readonly httpStatus: (statusCode: number) => string;
+        /**
+         * Match 4xx errors
+         */
+        readonly http4xx: "[..., status_code = 4*, ...]";
+        /**
+         * Match 5xx errors
+         */
+        readonly http5xx: "[..., status_code = 5*, ...]";
+    };
+    /**
+     * Create a comprehensive application dashboard
+     */
+    static createApplicationDashboard(options: {
+        slug: string;
+        environment: EnvironmentType;
+        region?: string;
+        components?: {
+            ec2InstanceIds?: string[];
+            lambdaFunctionNames?: string[];
+            ecsClusterName?: string;
+            ecsServiceName?: string;
+            albName?: string;
+            targetGroupName?: string;
+            rdsInstanceId?: string;
+            sqsQueueNames?: string[];
+            logGroupNames?: string[];
+        };
+    }): {
+        dashboard: CloudWatchDashboard;
+        logicalId: string;
+    };
+    /**
+     * Dashboard templates for common architectures
+     */
+    static readonly DashboardTemplates: {
+        /**
+         * Static website dashboard (S3 + CloudFront)
+         */
+        staticWebsite: (options: {
+            slug: string;
+            environment: EnvironmentType;
+            region?: string;
+            cloudFrontDistributionId: string;
+            s3BucketName: string;
+        }) => DashboardOptions;
+        /**
+         * Serverless API dashboard (Lambda + API Gateway)
+         */
+        serverlessApi: (options: {
+            slug: string;
+            environment: EnvironmentType;
+            region?: string;
+            apiGatewayName: string;
+            lambdaFunctionNames: string[];
+        }) => DashboardOptions;
+        /**
+         * Container service dashboard (ECS + ALB)
+         */
+        containerService: (options: {
+            slug: string;
+            environment: EnvironmentType;
+            region?: string;
+            ecsClusterName: string;
+            ecsServiceName: string;
+            albName: string;
+            rdsInstanceId?: string;
+        }) => DashboardOptions;
+    };
+    /**
+     * Monitoring Configuration helpers
+     * Provides Stacks configuration parity for monitoring options
+     */
+    static readonly Config: {
+        /**
+         * Create alarm configuration
+         */
+        createAlarmConfig: (options: {
+            metricName: string;
+            namespace: string;
+            threshold: number;
+            comparisonOperator?: "GreaterThanThreshold" | "GreaterThanOrEqualToThreshold" | "LessThanThreshold" | "LessThanOrEqualToThreshold";
+            evaluationPeriods?: number;
+            period?: number;
+            statistic?: "Average" | "Sum" | "Maximum" | "Minimum" | "SampleCount";
+            treatMissingData?: "breaching" | "notBreaching" | "ignore" | "missing";
+        }) => {
+            MetricName: string;
+            Namespace: string;
+            Threshold: number;
+            ComparisonOperator: string;
+            EvaluationPeriods: number;
+            Period: number;
+            Statistic: string;
+            TreatMissingData: string;
+        };
+        /**
+         * AWS namespace constants
+         */
+        namespaces: {
+            readonly ec2: "AWS/EC2";
+            readonly ecs: "AWS/ECS";
+            readonly lambda: "AWS/Lambda";
+            readonly rds: "AWS/RDS";
+            readonly sqs: "AWS/SQS";
+            readonly sns: "AWS/SNS";
+            readonly s3: "AWS/S3";
+            readonly cloudfront: "AWS/CloudFront";
+            readonly alb: "AWS/ApplicationELB";
+            readonly nlb: "AWS/NetworkELB";
+            readonly apiGateway: "AWS/ApiGateway";
+            readonly dynamodb: "AWS/DynamoDB";
+            readonly elasticache: "AWS/ElastiCache";
+        };
+        /**
+         * Comparison operator options
+         */
+        comparisonOperators: {
+            readonly greaterThan: "GreaterThanThreshold";
+            readonly greaterOrEqual: "GreaterThanOrEqualToThreshold";
+            readonly lessThan: "LessThanThreshold";
+            readonly lessOrEqual: "LessThanOrEqualToThreshold";
+        };
+        /**
+         * Common metric configurations by service
+         */
+        metrics: {
+            ec2: {
+                cpu: {
+                    metricName: string;
+                    namespace: string;
+                };
+                networkIn: {
+                    metricName: string;
+                    namespace: string;
+                };
+                networkOut: {
+                    metricName: string;
+                    namespace: string;
+                };
+                statusCheck: {
+                    metricName: string;
+                    namespace: string;
+                };
+            };
+            ecs: {
+                cpu: {
+                    metricName: string;
+                    namespace: string;
+                };
+                memory: {
+                    metricName: string;
+                    namespace: string;
+                };
+            };
+            lambda: {
+                invocations: {
+                    metricName: string;
+                    namespace: string;
+                };
+                errors: {
+                    metricName: string;
+                    namespace: string;
+                };
+                duration: {
+                    metricName: string;
+                    namespace: string;
+                };
+                throttles: {
+                    metricName: string;
+                    namespace: string;
+                };
+                concurrentExecutions: {
+                    metricName: string;
+                    namespace: string;
+                };
+            };
+            rds: {
+                cpu: {
+                    metricName: string;
+                    namespace: string;
+                };
+                connections: {
+                    metricName: string;
+                    namespace: string;
+                };
+                freeStorage: {
+                    metricName: string;
+                    namespace: string;
+                };
+                readLatency: {
+                    metricName: string;
+                    namespace: string;
+                };
+                writeLatency: {
+                    metricName: string;
+                    namespace: string;
+                };
+            };
+            alb: {
+                requestCount: {
+                    metricName: string;
+                    namespace: string;
+                };
+                responseTime: {
+                    metricName: string;
+                    namespace: string;
+                };
+                httpCode4xx: {
+                    metricName: string;
+                    namespace: string;
+                };
+                httpCode5xx: {
+                    metricName: string;
+                    namespace: string;
+                };
+                healthyHosts: {
+                    metricName: string;
+                    namespace: string;
+                };
+            };
+            sqs: {
+                messagesVisible: {
+                    metricName: string;
+                    namespace: string;
+                };
+                messagesDelayed: {
+                    metricName: string;
+                    namespace: string;
+                };
+                messageAge: {
+                    metricName: string;
+                    namespace: string;
+                };
+            };
+        };
+        /**
+         * Common alarm presets
+         */
+        presets: {
+            /**
+             * High CPU alarm
+             */
+            highCpu: (threshold?: number) => {
+                metricName: string;
+                threshold: number;
+                comparisonOperator: "GreaterThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Average";
+            };
+            /**
+             * High memory alarm (for ECS)
+             */
+            highMemory: (threshold?: number) => {
+                metricName: string;
+                threshold: number;
+                comparisonOperator: "GreaterThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Average";
+            };
+            /**
+             * High error rate alarm
+             */
+            highErrors: (threshold?: number) => {
+                metricName: string;
+                threshold: number;
+                comparisonOperator: "GreaterThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Sum";
+            };
+            /**
+             * High latency alarm
+             */
+            highLatency: (threshold?: number) => {
+                metricName: string;
+                threshold: number;
+                comparisonOperator: "GreaterThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Average";
+            };
+            /**
+             * Low healthy hosts alarm
+             */
+            lowHealthyHosts: (threshold?: number) => {
+                metricName: string;
+                namespace: string;
+                threshold: number;
+                comparisonOperator: "LessThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Minimum";
+            };
+            /**
+             * Queue depth alarm
+             */
+            queueDepth: (threshold?: number) => {
+                metricName: string;
+                namespace: string;
+                threshold: number;
+                comparisonOperator: "GreaterThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Average";
+            };
+            /**
+             * Low storage alarm
+             */
+            lowStorage: (threshold?: number) => {
+                metricName: string;
+                namespace: string;
+                threshold: number;
+                comparisonOperator: "LessThanThreshold";
+                evaluationPeriods: number;
+                period: number;
+                statistic: "Average";
+            };
+        };
+    };
+}