ec2-instance-running-scheduler 0.2.7 → 0.3.0

package/.jsii

@@ -8435,7 +8435,7 @@
       }
     }
   },
-  "description": "AWS CDK construct library that starts and stops EC2 instances on a cron schedule using EventBridge Scheduler and a Durable Execution Lambda. The handler discovers instances with the Resource Groups Tagging API, issues start/stop, polls until each instance reaches a stable target state (durable step / wait), processes multiple instances in parallel (bounded concurrency), and posts Slack summary and per-instance thread messages using a secret from Secrets Manager. The Lambda emits structured application logs alongside JSON platform logs.",
+  "description": "AWS CDK construct library that starts and stops EC2 instances on a cron schedule using EventBridge Scheduler and a Durable Execution Lambda. The handler discovers instances with the Resource Groups Tagging API, issues start/stop, waits until each instance reaches a stable target state (durable step / wait), processes multiple instances in parallel (bounded concurrency), and posts Slack summary and per-instance thread messages using a secret from Secrets Manager. The Lambda emits structured application logs alongside JSON platform logs.",
   "docs": {
     "stability": "stable"
   },
@@ -8461,7 +8461,7 @@
   },
   "name": "ec2-instance-running-scheduler",
   "readme": {
-    "markdown": "# EC2 Instance Running Scheduler (AWS CDK v2)\n\n[![GitHub](https://img.shields.io/github/license/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/blob/main/LICENSE)\n[![npm](https://img.shields.io/npm/v/ec2-instance-running-scheduler?style=flat-square)](https://www.npmjs.com/package/ec2-instance-running-scheduler)\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/release.yml?branch=main&label=release&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/actions/workflows/release.yml)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?sort=semver&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/releases)\n[![View on Construct Hub](https://constructs.dev/badge?package=ec2-instance-running-scheduler)](https://constructs.dev/packages/ec2-instance-running-scheduler)\n\nAWS CDK construct library that starts and stops EC2 instances on a cron schedule using **EventBridge Scheduler** and a **Durable Execution Lambda**. The handler discovers instances with the **Resource Groups Tagging API**, issues start/stop, **polls until each instance reaches a stable target state** (durable `step` / `wait`), processes **multiple instances in parallel** (bounded concurrency), and posts **Slack** summary and per-instance thread messages using a secret from **Secrets Manager**. The Lambda emits **structured application logs** alongside JSON platform logs.\n\n## Features\n\n- **Tag-based targeting** – Select EC2 instances by tag key and values (e.g. `Schedule` / `YES`) via `tag:GetResources`.\n- **EventBridge Scheduler** – Separate cron rules for start and stop, with per-rule timezone (`aws-cdk-lib` `TimeZone`).\n- **Durable Lambda** – One Lambda with AWS Lambda Durable Execution (`step`, `wait`, `map`, child contexts per instance) for long-running workflows without Step Functions.\n- **Stable-state polling** – After start/stop, the function waits (20 seconds between attempts) and re-describes instances until `running` (start mode) or `stopped` (stop mode).\n- **Configurable polling limits** – Per-instance **max loop count** and **max elapsed time** via `resourcePolling` (default: 90 loops / 1800 seconds). Failures use explicit `ResourcePollingFailed:*` messages instead of running until the Durable execution timeout (construct default: 2 hours).\n- **Validated environment variables** – The bundled handler parses required and polling env vars at invocation using strict decimal integer rules; polling limits must be **positive integers** (`> 0`).\n- **Slack notifications** – Parent message plus threaded updates per instance; credentials from Secrets Manager JSON (`token`, `channel`). The construct sets **`SLACK_SECRET_NAME`** on the function.\n- **Structured logging** – Durable execution **`ctx.logger`** for traceable JSON application logs (invocation, describe/start/stop/wait loops, polling limit errors, Slack steps, completion).\n- **Scheduling toggle** – Enable or disable both schedules without removing the stack (`enableScheduling`).\n- **Configurable schedules** – Optional cron overrides for start and stop (`minute`, `hour`, `week`, `timezone`); sensible defaults if omitted.\n- **IAM and observability** – EC2 and tagging API permissions, Slack secret read grant, **Parameters and Secrets Lambda Extension**, JSON logging, and a dedicated log group (construct defaults).\n\n## Installation\n\n**npm**\n\n```bash\nnpm install ec2-instance-running-scheduler\n```\n\n**yarn**\n\n```bash\nyarn add ec2-instance-running-scheduler\n```\n\n**pnpm**\n\n```bash\npnpm add ec2-instance-running-scheduler\n```\n\n## Usage\n\nUse the **construct** `EC2InstanceRunningScheduler` when embedding the scheduler in an existing stack or other CDK scope.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport { EC2InstanceRunningScheduler } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(app, 'MyStack');\n\nnew EC2InstanceRunningScheduler(stack, 'EC2InstanceRunningScheduler', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n  resourcePolling: {\n    maxLoopCount: 120,\n    maxElapsedSeconds: 3600,\n  },\n});\n```\n\nUse the **stack** `EC2InstanceRunningScheduleStack` when deploying the scheduler as its own stack. It accepts the same **targeting, schedules, secrets, and enable flag** as the construct (plus standard `StackProps` such as `env`). For **`resourcePolling`**, use the construct directly or extend the stack in your app.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport { EC2InstanceRunningScheduleStack } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\n\nnew EC2InstanceRunningScheduleStack(app, 'EC2InstanceRunningScheduleStack', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n});\n```\n\nEventBridge Scheduler invokes the Lambda with `Params.TagKey`, `Params.TagValues`, and `Params.Mode` (`Start` or `Stop`); the construct wires this for you. The function environment includes:\n\n| Variable | Source | Purpose |\n|----------|--------|---------|\n| `SLACK_SECRET_NAME` | `secrets.slackSecretName` | Secrets Manager secret for Slack (required) |\n| `PROCESS_RESOURCE_MAX_LOOP_COUNT` | `resourcePolling.maxLoopCount` (default `90`) | Max describe/poll iterations per instance |\n| `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` | `resourcePolling.maxElapsedSeconds` (default `1800`) | Max wall-clock seconds polling one instance |\n\nWhen you set polling limits via `resourcePolling`, the construct writes them as decimal integer strings. If you override these variables manually, each value must be a **strict decimal integer** (e.g. `\"120\"` is valid; `\"0x10\"`, `\"3.14\"`, or `\"10abc\"` are rejected) and **greater than zero**. Invalid or missing `SLACK_SECRET_NAME` causes the handler to fail at the start of an invocation.\n\n## Options\n\n### EC2InstanceRunningScheduler\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `targetResource` | `TargetResource` | Yes | Tag key and values used to select EC2 instances. |\n| `secrets` | `Secrets` | Yes | Secrets Manager secret for Slack (`slackSecretName`). |\n| `startSchedule` | `Schedule` | No | Cron for starting instances (default: `50 7 ? * MON-FRI *` in `Etc/UTC`). |\n| `stopSchedule` | `Schedule` | No | Cron for stopping instances (default: `5 19 ? * MON-FRI *` in `Etc/UTC`). |\n| `enableScheduling` | `boolean` | No | Whether both scheduler rules are enabled (default: `true`). |\n| `resourcePolling` | `ResourcePollingLimits` | No | Per-instance polling caps (see below). |\n\n### EC2InstanceRunningScheduleStack\n\nIncludes `targetResource`, `secrets`, `startSchedule`, `stopSchedule`, `enableScheduling`, and standard `StackProps`. Does **not** expose `resourcePolling`; use `EC2InstanceRunningScheduler` when you need custom polling limits.\n\n### TargetResource\n\n- `tagKey` – Tag key used to select instances (e.g. `Schedule`).\n- `tagValues` – Tag values that must match (e.g. `['YES']`).\n\n### Schedule\n\n- `timezone` – `TimeZone` from `aws-cdk-lib` (e.g. `TimeZone.ASIA_TOKYO`, `TimeZone.ETC_UTC`).\n- `minute` – Cron minute (`0`–`59`).\n- `hour` – Cron hour (`0`–`23`).\n- `week` – Cron day-of-week field (e.g. `MON-FRI`).\n\n### Secrets\n\n- `slackSecretName` – Name of the AWS Secrets Manager secret. The Lambda expects JSON with **`token`** (Slack bot token) and **`channel`** (channel ID or name for `chat.postMessage`).\n\n### ResourcePollingLimits\n\nWritten to `PROCESS_RESOURCE_MAX_LOOP_COUNT` and `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` on the running scheduler Lambda.\n\n- `maxLoopCount` – Maximum describe/poll loop iterations per instance (default: **90**). Must be a positive integer when set.\n- `maxElapsedSeconds` – Maximum wall-clock seconds spent polling one instance (default: **1800**, 30 minutes). Must be a positive integer when set.\n\nWhen a limit is exceeded during polling, the handler throws an error with prefix `ResourcePollingFailed:` (`MaxLoopCountExceeded`, `MaxElapsedTimeExceeded`, or `UnexpectedInstanceState` for unknown EC2 states).\n\n## Requirements\n\n- **Node.js** ≥ 20.0.0 (for developing or synthesizing CDK apps that depend on this package).\n- **aws-cdk-lib** ^2.232.0 and **constructs** ^10.5.1 (peer dependencies).\n- **AWS** – EventBridge Scheduler; Lambda with **Durable Execution** (Node.js **24.x** runtime in the construct; Durable Execution requires a supported Node.js runtime in your region), a **live alias**, **Parameters and Secrets Lambda Extension**; EC2 (`DescribeInstances`, `StartInstances`, `StopInstances`); Resource Groups Tagging API (`tag:GetResources`); Secrets Manager. The deployed function uses **arm64**, Durable Execution IAM policies, a 2-hour Durable execution timeout (construct default), and a bundled handler that loads secrets via **aws-lambda-secret-fetcher**.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
+    "markdown": "# EC2 Instance Running Scheduler (AWS CDK v2)\n\n[![GitHub](https://img.shields.io/github/license/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/blob/main/LICENSE)\n[![npm](https://img.shields.io/npm/v/ec2-instance-running-scheduler?style=flat-square)](https://www.npmjs.com/package/ec2-instance-running-scheduler)\n[![GitHub Workflow Status (branch)](https://img.shields.io/github/actions/workflow/status/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/release.yml?branch=main&label=release&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/actions/workflows/release.yml)\n[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler?sort=semver&style=flat-square)](https://github.com/gammarers-aws-cdk-constructs/ec2-instance-running-scheduler/releases)\n[![View on Construct Hub](https://constructs.dev/badge?package=ec2-instance-running-scheduler)](https://constructs.dev/packages/ec2-instance-running-scheduler)\n\nAWS CDK construct library that starts and stops EC2 instances on a cron schedule using **EventBridge Scheduler** and a **Durable Execution Lambda**. The handler discovers instances with the **Resource Groups Tagging API**, issues start/stop, **waits until each instance reaches a stable target state** (durable `step` / `wait`), processes **multiple instances in parallel** (bounded concurrency), and posts **Slack** summary and per-instance thread messages using a secret from **Secrets Manager**. The Lambda emits **structured application logs** alongside JSON platform logs.\n\n## Features\n\n- **Tag-based targeting** – Select EC2 instances by tag key and values (e.g. `Schedule` / `YES`) via `tag:GetResources`.\n- **EventBridge Scheduler** – Separate cron rules for start and stop, with per-rule timezone (`aws-cdk-lib` `TimeZone`).\n- **Durable Lambda** – One Lambda with AWS Lambda Durable Execution (`step`, `wait`, `map`, child contexts per instance) for long-running workflows without Step Functions.\n- **Stable-state waiting** – After start/stop, the function waits (20 seconds between attempts) and re-describes instances until `running` (start mode) or `stopped` (stop mode).\n- **Configurable wait limits** – Per-instance **max loop count** and **max elapsed time** via `resourceWait` (default: 90 loops / 1800 seconds). Failures use explicit `ResourceWaitFailed:*` messages instead of running until the Durable execution timeout (construct default: 2 hours).\n- **Validated environment variables** – The bundled handler parses env vars with **strict-env-resolver** (`StrictEnvResolver`). `SLACK_SECRET_NAME` is required; wait limits must be **finite positive numbers** (`> 0`).\n- **Slack notifications** – Parent message plus threaded updates per instance; credentials from Secrets Manager JSON (`token`, `channel`). The construct sets **`SLACK_SECRET_NAME`** on the function.\n- **Structured logging** – Durable execution **`ctx.logger`** for traceable JSON application logs (invocation, describe/start/stop/wait loops, wait limit errors, Slack steps, completion).\n- **Optional failure detection** – CloudWatch alarms and log-based metrics for Lambda errors, instance wait failures (`ResourceWaitFailed`), Slack post failures, and other handler `ERROR` logs. Optional SNS notifications via a caller-supplied topic (`failureDetection.alarmTopic`).\n- **Scheduling toggle** – Enable or disable both schedules without removing the stack (`enableScheduling`).\n- **Configurable schedules** – Optional cron overrides for start and stop (`minute`, `hour`, `week`, `timezone`); sensible defaults if omitted.\n- **IAM and observability** – EC2 and tagging API permissions, Slack secret read grant, **Parameters and Secrets Lambda Extension**, JSON logging, and a dedicated log group (construct defaults).\n\n## Installation\n\n**npm**\n\n```bash\nnpm install ec2-instance-running-scheduler\n```\n\n**yarn**\n\n```bash\nyarn add ec2-instance-running-scheduler\n```\n\n**pnpm**\n\n```bash\npnpm add ec2-instance-running-scheduler\n```\n\n## Usage\n\nUse the **construct** `EC2InstanceRunningScheduler` when embedding the scheduler in an existing stack or other CDK scope.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport * as sns from 'aws-cdk-lib/aws-sns';\nimport { EC2InstanceRunningScheduler } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\nconst stack = new cdk.Stack(app, 'MyStack');\n\nconst alarmTopic = new sns.Topic(stack, 'OpsAlerts');\n\nnew EC2InstanceRunningScheduler(stack, 'EC2InstanceRunningScheduler', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n  resourceWait: {\n    maxLoopCount: 120,\n    maxElapsedSeconds: 3600,\n  },\n  failureDetection: {\n    enabled: true,\n    alarmTopic,\n  },\n});\n```\n\nUse the **stack** `EC2InstanceRunningScheduleStack` when deploying the scheduler as its own stack. It accepts the same **targeting, schedules, secrets, enable flag, and failure detection** as the construct (plus standard `StackProps` such as `env`). For **`resourceWait`**, use the construct directly or extend the stack in your app.\n\n```typescript\nimport * as cdk from 'aws-cdk-lib';\nimport { TimeZone } from 'aws-cdk-lib';\nimport * as sns from 'aws-cdk-lib/aws-sns';\nimport { EC2InstanceRunningScheduleStack } from 'ec2-instance-running-scheduler';\n\nconst app = new cdk.App();\n\nconst alarmTopic = sns.Topic.fromTopicArn(\n  app,\n  'OpsAlerts',\n  'arn:aws:sns:ap-northeast-1:123456789012:ops-alerts',\n);\n\nnew EC2InstanceRunningScheduleStack(app, 'EC2InstanceRunningScheduleStack', {\n  targetResource: {\n    tagKey: 'Schedule',\n    tagValues: ['YES'],\n  },\n  secrets: {\n    slackSecretName: 'my-slack-secret',\n  },\n  startSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '55',\n    hour: '8',\n    week: 'MON-FRI',\n  },\n  stopSchedule: {\n    timezone: TimeZone.ASIA_TOKYO,\n    minute: '5',\n    hour: '19',\n    week: 'MON-FRI',\n  },\n  enableScheduling: true,\n  failureDetection: {\n    enabled: true,\n    alarmTopic,\n  },\n});\n```\n\nEventBridge Scheduler invokes the Lambda with `Params.TagKey`, `Params.TagValues`, and `Params.Mode` (`Start` or `Stop`); the construct wires this for you. The function environment includes:\n\n| Variable | Source | Purpose |\n|----------|--------|---------|\n| `SLACK_SECRET_NAME` | `secrets.slackSecretName` | Secrets Manager secret for Slack (required) |\n| `PROCESS_RESOURCE_MAX_LOOP_COUNT` | `resourceWait.maxLoopCount` (default `90`) | Max describe/wait iterations per instance |\n| `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` | `resourceWait.maxElapsedSeconds` (default `1800`) | Max wall-clock seconds waiting for one instance |\n\nWhen you set wait limits via `resourceWait`, the construct writes them as decimal integer strings. At invocation the handler parses them with **strict-env-resolver**; each value must be a **finite number greater than zero**. Missing `SLACK_SECRET_NAME` or invalid env values cause `StrictEnvValidationError` at the start of an invocation.\n\n## Options\n\n### EC2InstanceRunningScheduler\n\n| Option | Type | Required | Description |\n|--------|------|----------|-------------|\n| `targetResource` | `TargetResource` | Yes | Tag key and values used to select EC2 instances. |\n| `secrets` | `Secrets` | Yes | Secrets Manager secret for Slack (`slackSecretName`). |\n| `startSchedule` | `Schedule` | No | Cron for starting instances (default: `50 7 ? * MON-FRI *` in `Etc/UTC`). |\n| `stopSchedule` | `Schedule` | No | Cron for stopping instances (default: `5 19 ? * MON-FRI *` in `Etc/UTC`). |\n| `enableScheduling` | `boolean` | No | Whether both scheduler rules are enabled (default: `true`). |\n| `resourceWait` | `ResourceWaitLimits` | No | Per-instance wait caps (see below). |\n| `failureDetection` | `FailureDetectionAlarms` | No | Optional CloudWatch alarms and log-based metrics (see below). |\n\n### EC2InstanceRunningScheduleStack\n\nIncludes `targetResource`, `secrets`, `startSchedule`, `stopSchedule`, `enableScheduling`, `failureDetection`, and standard `StackProps`. Does **not** expose `resourceWait`; use `EC2InstanceRunningScheduler` when you need custom wait limits.\n\n### TargetResource\n\n- `tagKey` – Tag key used to select instances (e.g. `Schedule`).\n- `tagValues` – Tag values that must match (e.g. `['YES']`).\n\n### Schedule\n\n- `timezone` – `TimeZone` from `aws-cdk-lib` (e.g. `TimeZone.ASIA_TOKYO`, `TimeZone.ETC_UTC`).\n- `minute` – Cron minute (`0`–`59`).\n- `hour` – Cron hour (`0`–`23`).\n- `week` – Cron day-of-week field (e.g. `MON-FRI`).\n\n### Secrets\n\n- `slackSecretName` – Name of the AWS Secrets Manager secret. The Lambda expects JSON with **`token`** (Slack bot token) and **`channel`** (channel ID or name for `chat.postMessage`).\n\n### ResourceWaitLimits\n\nWritten to `PROCESS_RESOURCE_MAX_LOOP_COUNT` and `PROCESS_RESOURCE_MAX_ELAPSED_SECONDS` on the running scheduler Lambda.\n\n- `maxLoopCount` – Maximum describe/wait loop iterations per instance (default: **90**). Must be a positive integer when set.\n- `maxElapsedSeconds` – Maximum wall-clock seconds spent waiting for one instance to stabilize (default: **1800**, 30 minutes). Must be a positive integer when set.\n\nWhen a limit is exceeded during waiting, the handler throws an error with prefix `ResourceWaitFailed:` (`MaxLoopCountExceeded`, `MaxElapsedTimeExceeded`, or `UnexpectedInstanceState` for unknown EC2 states).\n\n### FailureDetectionAlarms\n\nOptional operational failure detection. Alarms are created only when `enabled` is `true`.\n\n- `enabled` – When `true`, creates four CloudWatch alarms and three log metric filters (default: disabled when omitted).\n- `alarmTopic` – Optional `sns.ITopic` for alarm actions. The construct does **not** create an SNS topic; pass an existing or imported topic. When omitted, alarms are created without SNS actions.\n\nWhen enabled, the construct creates:\n\n| Alarm | Trigger |\n|-------|---------|\n| Lambda errors | `AWS/Lambda` `Errors` metric |\n| Instance status failure | Log filter: `ResourceWaitFailed` |\n| Slack post failure | Log filter: `running-scheduler: Slack post failed` |\n| Durable execution failure | Other handler `ERROR` logs (excluding the above) |\n\nCustom metrics are published under the `EC2InstanceRunningScheduler` namespace. Access the created alarms via `EC2InstanceRunningScheduler.failureDetection` when enabled.\n\n## Requirements\n\n- **Node.js** ≥ 20.0.0 (for developing or synthesizing CDK apps that depend on this package).\n- **aws-cdk-lib** ^2.232.0 and **constructs** ^10.5.1 (peer dependencies).\n- **AWS** – EventBridge Scheduler; Lambda with **Durable Execution** (Node.js **24.x** runtime in the construct; Durable Execution requires a supported Node.js runtime in your region), a **live alias**, **Parameters and Secrets Lambda Extension**; EC2 (`DescribeInstances`, `StartInstances`, `StopInstances`); Resource Groups Tagging API (`tag:GetResources`); Secrets Manager. The deployed function uses **arm64**, Durable Execution IAM policies, a 2-hour Durable execution timeout (construct default), and a bundled handler that loads secrets via **aws-lambda-secret-fetcher** (^0.6) and parses env vars via **strict-env-resolver** (^0.5). Secret fetch runs only inside Lambda (requires runtime `AWS_SESSION_TOKEN` and the extension layer); the library retries transient extension errors including cold-start \"not ready\" responses.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.\n"
   },
   "repository": {
     "type": "git",
@@ -8478,6 +8478,7 @@
       "assembly": "ec2-instance-running-scheduler",
       "base": "aws-cdk-lib.Stack",
       "docs": {
+        "remarks": "Wires {@link EC2InstanceRunningScheduler} with targeting, schedules, secrets, scheduling toggle,\nand optional {@link FailureDetectionAlarms}. Does not expose {@link ResourceWaitLimits }; use the\nconstruct directly when custom per-instance wait limits are required.",
         "stability": "stable",
         "summary": "CDK stack that deploys the EC2 instance running scheduler (EventBridge Scheduler + Durable Lambda)."
       },
@@ -8489,7 +8490,7 @@
         },
         "locationInModule": {
           "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-          "line": 34
+          "line": 40
         },
         "parameters": [
           {
@@ -8512,7 +8513,7 @@
           },
           {
             "docs": {
-              "summary": "- Target resource, schedules, secrets, and standard stack props."
+              "summary": "- Target resource, schedules, secrets, optional failure detection, and standard stack props."
             },
             "name": "props",
             "type": {
@@ -8524,7 +8525,7 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
-        "line": 26
+        "line": 32
       },
       "name": "EC2InstanceRunningScheduleStack",
       "symbolId": "src/stacks/ec2-instance-running-schedule-stack:EC2InstanceRunningScheduleStack"
@@ -8533,7 +8534,7 @@
       "assembly": "ec2-instance-running-scheduler",
       "datatype": true,
       "docs": {
-        "see": "{@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourcePolling`).",
+        "see": "{@link EC2InstanceRunningSchedulerProps } for construct-level options not exposed here (e.g. `resourceWait`).",
         "stability": "stable",
         "summary": "Props for the EC2 instance running schedule CDK stack."
       },
@@ -8598,6 +8599,23 @@
             "primitive": "boolean"
           }
         },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Optional CloudWatch failure detection alarms and log-based metrics."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/stacks/ec2-instance-running-schedule-stack.ts",
+            "line": 22
+          },
+          "name": "failureDetection",
+          "optional": true,
+          "type": {
+            "fqn": "ec2-instance-running-scheduler.FailureDetectionAlarms"
+          }
+        },
         {
           "abstract": true,
           "docs": {
@@ -8639,7 +8657,7 @@
       "assembly": "ec2-instance-running-scheduler",
       "base": "constructs.Construct",
       "docs": {
-        "remarks": "Each schedule invokes the function with `Params` (`TagKey`, `TagValues`, `Mode`). The function uses\nthe Resource Groups Tagging API and EC2 APIs; Slack notifications use the secret named in {@link Secrets.slackSecretName}.\n\nPer-instance polling timeouts are configured via {@link EC2InstanceRunningSchedulerProps.resourcePolling}\nand enforced in the handler before the Durable execution timeout.",
+        "remarks": "Each schedule invokes the function with `Params` (`TagKey`, `TagValues`, `Mode`). The function uses\nthe Resource Groups Tagging API and EC2 APIs; Slack notifications use the secret named in {@link Secrets.slackSecretName}.\n\nPer-instance wait timeouts are configured via {@link EC2InstanceRunningSchedulerProps.resourceWait}\nand enforced in the handler before the Durable execution timeout. Optional CloudWatch failure\ndetection is available via {@link EC2InstanceRunningSchedulerProps.failureDetection}.",
         "stability": "stable",
         "summary": "Provisions EventBridge Scheduler rules and a Durable Execution Lambda that start/stop tagged EC2 instances."
       },
@@ -8647,11 +8665,11 @@
       "initializer": {
         "docs": {
           "stability": "stable",
-          "summary": "Defines IAM, logging, two cron schedules (start/stop), and the bundled running-scheduler Lambda (Node.js, Durable Execution)."
+          "summary": "Defines IAM, logging, optional failure detection alarms, two cron schedules (start/stop), and the bundled running-scheduler Lambda (Node.js, Durable Execution)."
         },
         "locationInModule": {
           "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-          "line": 109
+          "line": 136
         },
         "parameters": [
           {
@@ -8674,7 +8692,7 @@
           },
           {
             "docs": {
-              "summary": "- Target tags, schedules, Slack secret, schedule enable flag, and optional {@link ResourcePollingLimits}."
+              "summary": "- Target tags, schedules, Slack secret, schedule enable flag, optional {@link ResourceWaitLimits}, and optional {@link FailureDetectionAlarms}."
             },
             "name": "props",
             "type": {
@@ -8686,9 +8704,27 @@
       "kind": "class",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 101
+        "line": 123
       },
       "name": "EC2InstanceRunningScheduler",
+      "properties": [
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "Failure detection alarms, when {@link EC2InstanceRunningSchedulerProps.failureDetection} is enabled."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/ec2-instance-running-scheduler.ts",
+            "line": 125
+          },
+          "name": "failureDetection",
+          "optional": true,
+          "type": {
+            "fqn": "ec2-instance-running-scheduler.RunningSchedulerFailureDetection"
+          }
+        }
+      ],
       "symbolId": "src/constructs/ec2-instance-running-scheduler:EC2InstanceRunningScheduler"
     },
     "ec2-instance-running-scheduler.EC2InstanceRunningSchedulerProps": {
@@ -8702,7 +8738,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 73
+        "line": 86
       },
       "name": "EC2InstanceRunningSchedulerProps",
       "properties": [
@@ -8715,7 +8751,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 79
+            "line": 92
           },
           "name": "secrets",
           "type": {
@@ -8731,7 +8767,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 75
+            "line": 88
           },
           "name": "targetResource",
           "type": {
@@ -8748,7 +8784,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 77
+            "line": 90
           },
           "name": "enableScheduling",
           "optional": true,
@@ -8759,19 +8795,38 @@
         {
           "abstract": true,
           "docs": {
-            "default": "{@link DEFAULT_RESOURCE_POLLING_LIMITS }",
+            "default": "disabled when omitted",
+            "remarks": "Set `enabled: true` to create alarms; optionally pass `alarmTopic` for SNS notifications.",
             "stability": "stable",
-            "summary": "Per-instance polling limits for the running scheduler Lambda."
+            "summary": "Optional CloudWatch alarms and log-based metrics for failure detection."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 89
+            "line": 110
           },
-          "name": "resourcePolling",
+          "name": "failureDetection",
           "optional": true,
           "type": {
-            "fqn": "ec2-instance-running-scheduler.ResourcePollingLimits"
+            "fqn": "ec2-instance-running-scheduler.FailureDetectionAlarms"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "{@link DEFAULT_RESOURCE_WAIT_LIMITS }",
+            "stability": "stable",
+            "summary": "Per-instance wait limits for the running scheduler Lambda."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/ec2-instance-running-scheduler.ts",
+            "line": 102
+          },
+          "name": "resourceWait",
+          "optional": true,
+          "type": {
+            "fqn": "ec2-instance-running-scheduler.ResourceWaitLimits"
           }
         },
         {
@@ -8783,7 +8838,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 83
+            "line": 96
           },
           "name": "startSchedule",
           "optional": true,
@@ -8800,7 +8855,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 81
+            "line": 94
           },
           "name": "stopSchedule",
           "optional": true,
@@ -8811,33 +8866,89 @@
       ],
       "symbolId": "src/constructs/ec2-instance-running-scheduler:EC2InstanceRunningSchedulerProps"
     },
-    "ec2-instance-running-scheduler.ResourcePollingLimits": {
+    "ec2-instance-running-scheduler.FailureDetectionAlarms": {
       "assembly": "ec2-instance-running-scheduler",
       "datatype": true,
       "docs": {
-        "remarks": "Values are written to {@link PROCESS_RESOURCE_MAX_LOOP_COUNT_ENV} and\n{@link PROCESS_RESOURCE_MAX_ELAPSED_SECONDS_ENV} on the running scheduler function.\nPrevents abnormal or stuck transitions from running until the Durable execution timeout.",
+        "remarks": "When {@link FailureDetectionAlarms.enabled} is true, the construct creates alarms for Lambda\nerrors, Durable handler failures, EC2 instance status wait failures, and Slack post failures.\nAlarms can optionally notify an SNS topic supplied by the caller.",
         "stability": "stable",
-        "summary": "CDK-side limits for per-instance stable-state polling in the Durable Lambda handler."
+        "summary": "Optional CloudWatch alarms and log-based metrics for operational failure detection."
       },
-      "fqn": "ec2-instance-running-scheduler.ResourcePollingLimits",
+      "fqn": "ec2-instance-running-scheduler.FailureDetectionAlarms",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/constructs/running-scheduler-failure-detection.ts",
+        "line": 31
+      },
+      "name": "FailureDetectionAlarms",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "remarks": "When omitted, alarms are created without SNS actions.",
+            "stability": "stable",
+            "summary": "SNS topic for alarm notifications."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 43
+          },
+          "name": "alarmTopic",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sns.ITopic"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "default": "false when omitted",
+            "stability": "stable",
+            "summary": "When true, creates failure detection alarms and log-based metrics."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 37
+          },
+          "name": "enabled",
+          "optional": true,
+          "type": {
+            "primitive": "boolean"
+          }
+        }
+      ],
+      "symbolId": "src/constructs/running-scheduler-failure-detection:FailureDetectionAlarms"
+    },
+    "ec2-instance-running-scheduler.ResourceWaitLimits": {
+      "assembly": "ec2-instance-running-scheduler",
+      "datatype": true,
+      "docs": {
+        "remarks": "Optional fields map to {@link PROCESS_RESOURCE_MAX_LOOP_COUNT_ENV} and\n{@link PROCESS_RESOURCE_MAX_ELAPSED_SECONDS_ENV} on the running scheduler function.\nPrevents abnormal or stuck transitions from running until the Durable execution timeout.",
+        "see": "{@link ResourceWaitLimits } in `running-scheduler-predicates.ts` for the handler-side required shape.",
+        "stability": "stable",
+        "summary": "CDK-side limits for per-instance stable-state waiting in the Durable Lambda handler."
+      },
+      "fqn": "ec2-instance-running-scheduler.ResourceWaitLimits",
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 55
+        "line": 68
       },
-      "name": "ResourcePollingLimits",
+      "name": "ResourceWaitLimits",
       "properties": [
         {
           "abstract": true,
           "docs": {
-            "default": "{@link DEFAULT_RESOURCE_POLLING_LIMITS.maxElapsedSeconds } (1800, 30 minutes)",
+            "default": "{@link DEFAULT_RESOURCE_WAIT_LIMITS.maxElapsedSeconds } (1800, 30 minutes)",
             "stability": "stable",
-            "summary": "Maximum wall-clock seconds spent polling a single instance."
+            "summary": "Maximum wall-clock seconds spent waiting for a single instance to stabilize."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 67
+            "line": 80
           },
           "name": "maxElapsedSeconds",
           "optional": true,
@@ -8848,14 +8959,14 @@
         {
           "abstract": true,
           "docs": {
-            "default": "{@link DEFAULT_RESOURCE_POLLING_LIMITS.maxLoopCount } (90)",
+            "default": "{@link DEFAULT_RESOURCE_WAIT_LIMITS.maxLoopCount } (90)",
             "stability": "stable",
-            "summary": "Maximum describe/poll loop iterations per instance."
+            "summary": "Maximum describe/wait loop iterations per instance."
           },
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 61
+            "line": 74
           },
           "name": "maxLoopCount",
           "optional": true,
@@ -8864,7 +8975,206 @@
           }
         }
       ],
-      "symbolId": "src/constructs/ec2-instance-running-scheduler:ResourcePollingLimits"
+      "symbolId": "src/constructs/ec2-instance-running-scheduler:ResourceWaitLimits"
+    },
+    "ec2-instance-running-scheduler.RunningSchedulerFailureDetection": {
+      "assembly": "ec2-instance-running-scheduler",
+      "base": "constructs.Construct",
+      "docs": {
+        "remarks": "When enabled, creates four alarms:\n- `lambdaErrorsAlarm` – `AWS/Lambda` `Errors` metric.\n- `instanceStatusFailureAlarm` – log filter for `ResourceWaitFailed:*`.\n- `slackPostFailureAlarm` – log filter for `running-scheduler: Slack post failed`.\n- `durableExecutionFailureAlarm` – other handler-level `ERROR` logs (excluding the above).\n\nCustom metrics are published under the `EC2InstanceRunningScheduler` namespace.",
+        "stability": "stable",
+        "summary": "CloudWatch alarms and log-based metrics for the running scheduler Lambda."
+      },
+      "fqn": "ec2-instance-running-scheduler.RunningSchedulerFailureDetection",
+      "initializer": {
+        "docs": {
+          "stability": "stable"
+        },
+        "locationInModule": {
+          "filename": "src/constructs/running-scheduler-failure-detection.ts",
+          "line": 132
+        },
+        "parameters": [
+          {
+            "docs": {
+              "summary": "- Parent construct."
+            },
+            "name": "scope",
+            "type": {
+              "fqn": "constructs.Construct"
+            }
+          },
+          {
+            "docs": {
+              "summary": "- Construct id."
+            },
+            "name": "id",
+            "type": {
+              "primitive": "string"
+            }
+          },
+          {
+            "docs": {
+              "summary": "- Lambda, log group, and {@link FailureDetectionAlarms} (must have `enabled: true`)."
+            },
+            "name": "props",
+            "type": {
+              "fqn": "ec2-instance-running-scheduler.RunningSchedulerFailureDetectionProps"
+            }
+          }
+        ]
+      },
+      "kind": "class",
+      "locationInModule": {
+        "filename": "src/constructs/running-scheduler-failure-detection.ts",
+        "line": 115
+      },
+      "name": "RunningSchedulerFailureDetection",
+      "properties": [
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "Fires on handler-level ERROR logs outside instance waiting and Slack post failures."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 121
+          },
+          "name": "durableExecutionFailureAlarm",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudwatch.Alarm"
+          }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "Fires when instance stable-state waiting fails (`ResourceWaitFailed:*`)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 123
+          },
+          "name": "instanceStatusFailureAlarm",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudwatch.Alarm"
+          }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "Fires when the Lambda `Errors` metric is non-zero."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 119
+          },
+          "name": "lambdaErrorsAlarm",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudwatch.Alarm"
+          }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "Fires when Slack `chat.postMessage` fails."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 125
+          },
+          "name": "slackPostFailureAlarm",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_cloudwatch.Alarm"
+          }
+        },
+        {
+          "docs": {
+            "stability": "stable",
+            "summary": "SNS topic used for alarm actions, when configured."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 117
+          },
+          "name": "alarmTopic",
+          "optional": true,
+          "type": {
+            "fqn": "aws-cdk-lib.aws_sns.ITopic"
+          }
+        }
+      ],
+      "symbolId": "src/constructs/running-scheduler-failure-detection:RunningSchedulerFailureDetection"
+    },
+    "ec2-instance-running-scheduler.RunningSchedulerFailureDetectionProps": {
+      "assembly": "ec2-instance-running-scheduler",
+      "datatype": true,
+      "docs": {
+        "stability": "stable",
+        "summary": "Props for {@link RunningSchedulerFailureDetection}."
+      },
+      "fqn": "ec2-instance-running-scheduler.RunningSchedulerFailureDetectionProps",
+      "kind": "interface",
+      "locationInModule": {
+        "filename": "src/constructs/running-scheduler-failure-detection.ts",
+        "line": 49
+      },
+      "name": "RunningSchedulerFailureDetectionProps",
+      "properties": [
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Alarm configuration (must have {@link FailureDetectionAlarms.enabled} true)."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 51
+          },
+          "name": "failureDetection",
+          "type": {
+            "fqn": "ec2-instance-running-scheduler.FailureDetectionAlarms"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Application log group for the running scheduler Lambda."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 55
+          },
+          "name": "logGroup",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_logs.ILogGroup"
+          }
+        },
+        {
+          "abstract": true,
+          "docs": {
+            "stability": "stable",
+            "summary": "Running scheduler Lambda to monitor."
+          },
+          "immutable": true,
+          "locationInModule": {
+            "filename": "src/constructs/running-scheduler-failure-detection.ts",
+            "line": 53
+          },
+          "name": "runningScheduleFunction",
+          "type": {
+            "fqn": "aws-cdk-lib.aws_lambda.IFunction"
+          }
+        }
+      ],
+      "symbolId": "src/constructs/running-scheduler-failure-detection:RunningSchedulerFailureDetectionProps"
     },
     "ec2-instance-running-scheduler.Schedule": {
       "assembly": "ec2-instance-running-scheduler",
@@ -8877,7 +9187,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 19
+        "line": 30
       },
       "name": "Schedule",
       "properties": [
@@ -8890,7 +9200,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 21
+            "line": 32
           },
           "name": "timezone",
           "type": {
@@ -8906,7 +9216,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 25
+            "line": 36
           },
           "name": "hour",
           "optional": true,
@@ -8923,7 +9233,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 23
+            "line": 34
           },
           "name": "minute",
           "optional": true,
@@ -8940,7 +9250,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 27
+            "line": 38
           },
           "name": "week",
           "optional": true,
@@ -8962,7 +9272,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 43
+        "line": 54
       },
       "name": "Secrets",
       "properties": [
@@ -8975,7 +9285,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 45
+            "line": 56
           },
           "name": "slackSecretName",
           "type": {
@@ -8996,7 +9306,7 @@
       "kind": "interface",
       "locationInModule": {
         "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-        "line": 33
+        "line": 44
       },
       "name": "TargetResource",
       "properties": [
@@ -9009,7 +9319,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 35
+            "line": 46
           },
           "name": "tagKey",
           "type": {
@@ -9025,7 +9335,7 @@
           "immutable": true,
           "locationInModule": {
             "filename": "src/constructs/ec2-instance-running-scheduler.ts",
-            "line": 37
+            "line": 48
           },
           "name": "tagValues",
           "type": {
@@ -9041,6 +9351,6 @@
       "symbolId": "src/constructs/ec2-instance-running-scheduler:TargetResource"
     }
   },
-  "version": "0.2.7",
-  "fingerprint": "vh5lSZ1r+w01KIrqSdRiUxdYdRCWaCfJR2Rg3QXGWQY="
+  "version": "0.3.0",
+  "fingerprint": "bwKUClibSPFDZfqak8YNEMPWz002RMgKad/Ke/6VtnE="
 }