@composurecdk/neptune 0.8.3

package/README.md

@@ -0,0 +1,140 @@
+# @composurecdk/neptune
+
+Amazon Neptune cluster builder for [ComposureCDK](../../README.md).
+
+This package provides a fluent builder for Amazon Neptune clusters with secure, AWS-recommended defaults. It wraps the CDK alpha [`DatabaseCluster`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-neptune-alpha-readme.html) L2 construct — refer to the CDK documentation for the full set of configurable properties.
+
+> **Alpha dependency.** Neptune's CDK L2 lives in `@aws-cdk/aws-neptune-alpha`, which is production-usable but semver-unstable and version-locked to its matching `aws-cdk-lib` release. It is a **peer dependency** of this package — install it (and a matching `aws-cdk-lib`) in your app and pin the version you want.
+
+```sh
+npm install @composurecdk/neptune @aws-cdk/aws-neptune-alpha aws-cdk-lib
+```
+
+## Cluster Builder
+
+A Neptune cluster owns its writer/reader instances — the CDK L2 creates them from the instance type and instance count — so a single cluster builder covers both serverless and provisioned topologies. There is intentionally no separate instance builder: in-region read replicas are added via the instance count (`.instances(n)`), and cross-region scale-out is a [Neptune Global Database](https://docs.aws.amazon.com/neptune/latest/userguide/neptune-global-database.html) (separate read-only clusters per region, future work), not extra instances on one cluster.
+
+### Serverless
+
+```ts
+import { compose, ref } from "@composurecdk/core";
+import { createVpcBuilder, type VpcBuilderResult } from "@composurecdk/ec2";
+import { createClusterBuilder } from "@composurecdk/neptune";
+import { InstanceType } from "@aws-cdk/aws-neptune-alpha";
+
+const system = compose(
+  {
+    network: createVpcBuilder().maxAzs(2),
+    graph: createClusterBuilder()
+      .vpc(ref<VpcBuilderResult>("network").get("vpc"))
+      .instanceType(InstanceType.SERVERLESS)
+      .serverlessScalingConfiguration({ minCapacity: 1, maxCapacity: 8 }),
+  },
+  { network: [], graph: ["network"] },
+);
+```
+
+### Provisioned
+
+```ts
+const graph = createClusterBuilder()
+  .vpc(ref<VpcBuilderResult>("network").get("vpc"))
+  .instanceType(InstanceType.R6G_LARGE)
+  .instances(2); // one writer + one reader
+```
+
+The `vpc` is set via the dedicated `.vpc()` method (it is required and accepts a `Ref` for cross-component wiring). `securityGroups` likewise accept `Resolvable` values. Every other [`DatabaseClusterProps`](https://docs.aws.amazon.com/cdk/api/v2/docs/@aws-cdk_aws-neptune-alpha.DatabaseClusterProps.html) property is available as a fluent setter. The `instanceType` is **required** — defaulting it would create surprise cost.
+
+## Build result
+
+`build()` returns every construct the builder creates, per the [build-results-must-be-complete](../../docs/architecture.md) rule:
+
+```ts
+interface ClusterBuilderResult {
+  cluster: DatabaseCluster;
+  subnetGroup: ISubnetGroup;
+  clusterParameterGroup: IClusterParameterGroup;
+  alarms: Record<string, Alarm>;
+}
+```
+
+## Secure Defaults
+
+`createClusterBuilder` applies the following defaults. Each can be overridden via the builder's fluent API. Defaults are anchored to the [AWS Well-Architected Framework — Neptune lens](https://docs.aws.amazon.com/prescriptive-guidance/latest/neptune-well-architected-framework/introduction.html).
+
+| Property                  | Default                   | Rationale                                                             |
+| ------------------------- | ------------------------- | --------------------------------------------------------------------- |
+| `storageEncrypted`        | `true`                    | Encryption at rest; supply a CMK via `.kmsKey()`.                     |
+| `iamAuthentication`       | `true`                    | Removes long-lived static credentials.                                |
+| `removalPolicy`           | `RETAIN`                  | Protects graph data from an errant `cdk destroy`.                     |
+| `deletionProtection`      | `true`                    | Blocks accidental deletion of the cluster.                            |
+| `backupRetention`         | `Duration.days(7)`        | Production-grade window (CDK default is 1 day).                       |
+| `cloudwatchLogsExports`   | `[LogType.AUDIT]`         | Exports audit logs (the only CloudWatch-exportable Neptune log type). |
+| `cloudwatchLogsRetention` | `RetentionDays.ONE_MONTH` | Bounds log storage cost.                                              |
+| `copyTagsToSnapshot`      | `true`                    | Preserves cost-allocation tags on backups.                            |
+| `autoMinorVersionUpgrade` | `true`                    | Stays on patched engine versions.                                     |
+
+The defaults are exported as `CLUSTER_DEFAULTS` for visibility and testing.
+
+### Audit-log parameter group
+
+Audit log _export_ only emits data once audit logging is _enabled_ in the cluster parameter group. So the builder auto-creates a cluster parameter group with `neptune_enable_audit_log = "1"` (parallel to how `createVpcBuilder` auto-creates a flow-log group), with the family derived from the configured engine version. Add or override parameters with `.clusterParameters({...})`, or supply your own group with `.clusterParameterGroup(myGroup)` (mutually exclusive with `.clusterParameters()`).
+
+## Granting access — `allowAccessFrom`
+
+Because IAM authentication is on by default, a principal needs both a network path (security-group ingress) and an IAM `connect` grant to reach the cluster. `allowAccessFrom(peer)` does both in one declaration, and accepts a `Ref` so the grant lives inside `compose()` rather than in post-build glue:
+
+```ts
+import { createInstanceBuilder, type InstanceBuilderResult } from "@composurecdk/ec2";
+
+const system = compose(
+  {
+    network: createVpcBuilder().maxAzs(2),
+    bastion: createInstanceBuilder().vpc(ref("network").get("vpc")).instanceType(/* ... */),
+    graph: createClusterBuilder()
+      .vpc(ref("network").get("vpc"))
+      .instanceType(InstanceType.SERVERLESS)
+      .serverlessScalingConfiguration({ minCapacity: 1, maxCapacity: 8 })
+      .allowAccessFrom(ref<InstanceBuilderResult>("bastion").get("instance")),
+  },
+  { network: [], bastion: ["network"], graph: ["network", "bastion"] },
+);
+```
+
+The `peer` is any `IConnectable & IGrantable` (an EC2 instance, a Lambda function, a Fargate task, …). At build time the builder applies `cluster.connections.allowDefaultPortFrom(peer)` and `cluster.grantConnect(peer)`.
+
+If you disable IAM authentication (`.iamAuthentication(false)`), `allowAccessFrom` adapts: it opens only the network path and skips the `grantConnect` IAM policy, which would be inert without IAM auth. Authentication then falls to whatever mechanism you've configured on the cluster.
+
+## Recommended Alarms
+
+The builder creates recommended CloudWatch alarms by default. Neptune is not yet covered by the [CloudWatch out-of-the-box alarm recommendations](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Best_Practice_Recommended_Alarms_AWS_Services.html), so thresholds follow the [Neptune metrics guidance](https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html). No alarm actions are configured — access alarms from the build result to add actions.
+
+| Alarm                             | Metric                                       | Default threshold    | Created when             |
+| --------------------------------- | -------------------------------------------- | -------------------- | ------------------------ |
+| `cpuUtilization`                  | CPUUtilization (Average, 1 min)              | >= 80%               | Always                   |
+| `mainRequestQueuePendingRequests` | MainRequestQueuePendingRequests (Avg, 1 min) | > 100                | Always                   |
+| `bufferCacheHitRatio`             | BufferCacheHitRatio (Average, 1 min)         | < 99.9%              | Always                   |
+| `clusterReplicaLag`               | ClusterReplicaLag (Average, 1 min)           | > 30000 ms           | Always[^lag]             |
+| `serverlessDatabaseCapacity`      | ServerlessDatabaseCapacity (Average, 1 min)  | 90% of `maxCapacity` | Serverless clusters only |
+
+[^lag]: Only emits data when the cluster has a read replica. `TreatMissingData` defaults to `notBreaching`, so it stays quiet on a single-instance cluster.
+
+The defaults are exported as `CLUSTER_ALARM_DEFAULTS` for visibility and testing.
+
+### Customizing and disabling alarms
+
+```ts
+createClusterBuilder()
+  // tune one alarm, disable another
+  .recommendedAlarms({ cpuUtilization: { threshold: 90 }, bufferCacheHitRatio: false })
+  // add a custom alarm
+  .addAlarm("gremlinErrors", (a) =>
+    a
+      .metric((cluster) => cluster.metric("NumGremlinErrorsPerSec"))
+      .threshold(0)
+      .greaterThan(),
+  );
+
+// disable all recommended alarms
+createClusterBuilder().recommendedAlarms(false);
+```

package/dist/commonjs/cluster-alarm-config.d.ts

@@ -0,0 +1,77 @@
+import type { AlarmConfig } from "@composurecdk/cloudwatch";
+/**
+ * Controls which recommended alarms are created for a Neptune cluster.
+ * All applicable alarms are enabled by default with thresholds drawn from
+ * the Neptune team's own metric guidance. Set an individual alarm to `false`
+ * to disable it, or provide an {@link AlarmConfig} to tune its thresholds.
+ *
+ * Neptune is not yet covered by the CloudWatch out-of-the-box alarm
+ * recommendations table, so these thresholds are anchored to the Neptune
+ * User Guide's metrics guidance and the Neptune Well-Architected lens rather
+ * than to that table.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+ * @see https://docs.aws.amazon.com/prescriptive-guidance/latest/neptune-well-architected-framework/introduction.html
+ */
+export interface NeptuneClusterAlarmConfig {
+    /**
+     * Master switch: set to `false` to disable all recommended alarms.
+     * Individual alarms can also be disabled via their own entry.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Alarm on sustained high CPU on the cluster's instances — the primary
+     * signal of a saturated writer or undersized instance.
+     *
+     * Metric: `AWS/Neptune CPUUtilization`, statistic Average, period 1 minute.
+     * Default threshold: >= 80%.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/cloudwatch-monitoring-instances.html
+     */
+    cpuUtilization?: AlarmConfig | false;
+    /**
+     * Alarm when requests are queuing faster than the engine can execute them.
+     *
+     * Metric: `AWS/Neptune MainRequestQueuePendingRequests`, statistic Average,
+     * period 1 minute. Default threshold: > 100 pending requests.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+     */
+    mainRequestQueuePendingRequests?: AlarmConfig | false;
+    /**
+     * Alarm when the buffer cache hit ratio drops, indicating the working set
+     * no longer fits in memory and query latency is dominated by I/O.
+     *
+     * Metric: `AWS/Neptune BufferCacheHitRatio`, statistic Average, period 1
+     * minute. Default threshold: < 99.9%.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+     */
+    bufferCacheHitRatio?: AlarmConfig | false;
+    /**
+     * Alarm when a read replica falls too far behind the writer. Only emits
+     * data when the cluster has at least one replica, so it stays quiet on a
+     * single-instance cluster (`TreatMissingData.NOT_BREACHING`).
+     *
+     * Metric: `AWS/Neptune ClusterReplicaLag`, statistic Average, period 1
+     * minute. Default threshold: > 30000 ms.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/cw-metrics.html
+     */
+    clusterReplicaLag?: AlarmConfig | false;
+    /**
+     * Alarm when a serverless cluster sustains capacity near its configured
+     * ceiling, indicating the max NCU setting is too low or query load is
+     * running away. Only created when the cluster is serverless (i.e.
+     * `serverlessScalingConfiguration` is set); the default threshold is
+     * derived as 90% of the configured `maxCapacity`.
+     *
+     * Metric: `AWS/Neptune ServerlessDatabaseCapacity`, statistic Average,
+     * period 1 minute.
+     *
+     * @see https://docs.aws.amazon.com/neptune/latest/userguide/neptune-serverless-capacity-scaling.html
+     */
+    serverlessDatabaseCapacity?: AlarmConfig | false;
+}
+//# sourceMappingURL=cluster-alarm-config.d.ts.map

package/dist/commonjs/cluster-alarm-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-config.d.ts","sourceRoot":"","sources":["../../src/cluster-alarm-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;;;OAQG;IACH,cAAc,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAErC;;;;;;;OAOG;IACH,+BAA+B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAEtD;;;;;;;;OAQG;IACH,mBAAmB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAE1C;;;;;;;;;OASG;IACH,iBAAiB,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;IAExC;;;;;;;;;;;OAWG;IACH,0BAA0B,CAAC,EAAE,WAAW,GAAG,KAAK,CAAC;CAClD"}

package/dist/commonjs/cluster-alarm-config.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=cluster-alarm-config.js.map

package/dist/commonjs/cluster-alarm-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-config.js","sourceRoot":"","sources":["../../src/cluster-alarm-config.ts"],"names":[],"mappings":""}

package/dist/commonjs/cluster-alarm-defaults.d.ts

@@ -0,0 +1,20 @@
+import type { AlarmConfigDefaults } from "@composurecdk/cloudwatch";
+interface ClusterAlarmDefaults {
+    enabled: true;
+    cpuUtilization: AlarmConfigDefaults;
+    mainRequestQueuePendingRequests: AlarmConfigDefaults;
+    bufferCacheHitRatio: AlarmConfigDefaults;
+    clusterReplicaLag: AlarmConfigDefaults;
+    /** `threshold` is unused — the real value is derived from `maxCapacity` at build time. */
+    serverlessDatabaseCapacity: AlarmConfigDefaults;
+}
+/**
+ * Recommended default alarm configuration for Neptune clusters. Thresholds
+ * follow the Neptune team's metric guidance; Neptune is absent from the
+ * CloudWatch recommended-alarms table, so no anchor to that page exists.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+ */
+export declare const CLUSTER_ALARM_DEFAULTS: ClusterAlarmDefaults;
+export {};
+//# sourceMappingURL=cluster-alarm-defaults.d.ts.map

package/dist/commonjs/cluster-alarm-defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-defaults.d.ts","sourceRoot":"","sources":["../../src/cluster-alarm-defaults.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,UAAU,oBAAoB;IAC5B,OAAO,EAAE,IAAI,CAAC;IACd,cAAc,EAAE,mBAAmB,CAAC;IACpC,+BAA+B,EAAE,mBAAmB,CAAC;IACrD,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,0FAA0F;IAC1F,0BAA0B,EAAE,mBAAmB,CAAC;CACjD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,EAAE,oBA4CpC,CAAC"}

package/dist/commonjs/cluster-alarm-defaults.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLUSTER_ALARM_DEFAULTS = void 0;
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+/**
+ * Recommended default alarm configuration for Neptune clusters. Thresholds
+ * follow the Neptune team's metric guidance; Neptune is absent from the
+ * CloudWatch recommended-alarms table, so no anchor to that page exists.
+ *
+ * @see https://docs.aws.amazon.com/neptune/latest/userguide/best-practices-general-metrics.html
+ */
+exports.CLUSTER_ALARM_DEFAULTS = {
+    enabled: true,
+    /** Sustained CPU at/above 80% over several minutes signals saturation. */
+    cpuUtilization: {
+        threshold: 80,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** A growing request backlog means the engine cannot keep up with load. */
+    mainRequestQueuePendingRequests: {
+        threshold: 100,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** A cache hit ratio below 99.9% indicates the working set exceeds memory. */
+    bufferCacheHitRatio: {
+        threshold: 99.9,
+        evaluationPeriods: 15,
+        datapointsToAlarm: 10,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    /** Replica lag over 30s risks stale reads; quiet on single-instance clusters. */
+    clusterReplicaLag: {
+        threshold: 30_000,
+        evaluationPeriods: 5,
+        datapointsToAlarm: 3,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+    // `threshold` is a required-shape filler: the serverless capacity alarm
+    // always derives its threshold from `maxCapacity` at build time (or a user
+    // override), so this value is never read. The evaluation window is.
+    serverlessDatabaseCapacity: {
+        threshold: 0,
+        evaluationPeriods: 15,
+        datapointsToAlarm: 10,
+        treatMissingData: aws_cloudwatch_1.TreatMissingData.NOT_BREACHING,
+    },
+};
+//# sourceMappingURL=cluster-alarm-defaults.js.map

package/dist/commonjs/cluster-alarm-defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarm-defaults.js","sourceRoot":"","sources":["../../src/cluster-alarm-defaults.ts"],"names":[],"mappings":";;;AAAA,+DAA8D;AAa9D;;;;;;GAMG;AACU,QAAA,sBAAsB,GAAyB;IAC1D,OAAO,EAAE,IAAI;IAEb,0EAA0E;IAC1E,cAAc,EAAE;QACd,SAAS,EAAE,EAAE;QACb,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,2EAA2E;IAC3E,+BAA+B,EAAE;QAC/B,SAAS,EAAE,GAAG;QACd,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,8EAA8E;IAC9E,mBAAmB,EAAE;QACnB,SAAS,EAAE,IAAI;QACf,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,iFAAiF;IACjF,iBAAiB,EAAE;QACjB,SAAS,EAAE,MAAM;QACjB,iBAAiB,EAAE,CAAC;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;IAED,wEAAwE;IACxE,2EAA2E;IAC3E,oEAAoE;IACpE,0BAA0B,EAAE;QAC1B,SAAS,EAAE,CAAC;QACZ,iBAAiB,EAAE,EAAE;QACrB,iBAAiB,EAAE,EAAE;QACrB,gBAAgB,EAAE,iCAAgB,CAAC,aAAa;KACjD;CACF,CAAC"}

package/dist/commonjs/cluster-alarms.d.ts

@@ -0,0 +1,25 @@
+import { type Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { IDatabaseCluster, ServerlessScalingConfiguration } from "@aws-cdk/aws-neptune-alpha";
+import type { IConstruct } from "constructs";
+import type { AlarmDefinition, AlarmDefinitionBuilder } from "@composurecdk/cloudwatch";
+import type { NeptuneClusterAlarmConfig } from "./cluster-alarm-config.js";
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for a Neptune cluster. The serverless capacity
+ * alarm is only emitted when `serverlessScaling` is provided.
+ */
+export declare function resolveClusterAlarmDefinitions(cluster: IDatabaseCluster, config: NeptuneClusterAlarmConfig | undefined, serverlessScaling: ServerlessScalingConfiguration | undefined): AlarmDefinition[];
+/**
+ * Creates recommended CloudWatch alarms for a Neptune cluster, merging the
+ * recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param cluster - The Neptune cluster to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param serverlessScaling - The cluster's serverless scaling config, if any.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ */
+export declare function createClusterAlarms(scope: IConstruct, id: string, cluster: IDatabaseCluster, config: NeptuneClusterAlarmConfig | false | undefined, serverlessScaling: ServerlessScalingConfiguration | undefined, customAlarms?: AlarmDefinitionBuilder<IDatabaseCluster>[]): Record<string, Alarm>;
+//# sourceMappingURL=cluster-alarms.d.ts.map

package/dist/commonjs/cluster-alarms.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarms.d.ts","sourceRoot":"","sources":["../../src/cluster-alarms.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,KAAK,EAAsB,MAAM,4BAA4B,CAAC;AAC5E,OAAO,KAAK,EAAE,gBAAgB,EAAE,8BAA8B,EAAE,MAAM,4BAA4B,CAAC;AACnG,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAExF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AAY3E;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,yBAAyB,GAAG,SAAS,EAC7C,iBAAiB,EAAE,8BAA8B,GAAG,SAAS,GAC5D,eAAe,EAAE,CA4GnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,UAAU,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,yBAAyB,GAAG,KAAK,GAAG,SAAS,EACrD,iBAAiB,EAAE,8BAA8B,GAAG,SAAS,EAC7D,YAAY,GAAE,sBAAsB,CAAC,gBAAgB,CAAC,EAAO,GAC5D,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAUvB"}

package/dist/commonjs/cluster-alarms.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveClusterAlarmDefinitions = resolveClusterAlarmDefinitions;
+exports.createClusterAlarms = createClusterAlarms;
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const aws_cloudwatch_1 = require("aws-cdk-lib/aws-cloudwatch");
+const cloudwatch_1 = require("@composurecdk/cloudwatch");
+const cluster_alarm_defaults_js_1 = require("./cluster-alarm-defaults.js");
+const METRIC_PERIOD = aws_cdk_lib_1.Duration.minutes(1);
+const METRIC_PERIOD_LABEL = `${String(METRIC_PERIOD.toMinutes())} minute`;
+/**
+ * Fraction of a serverless cluster's configured `maxCapacity` at which the
+ * `serverlessDatabaseCapacity` alarm fires by default.
+ */
+const SERVERLESS_CAPACITY_ALARM_FRACTION = 0.9;
+/**
+ * Resolves the recommended alarm configuration into fully-resolved
+ * {@link AlarmDefinition}s for a Neptune cluster. The serverless capacity
+ * alarm is only emitted when `serverlessScaling` is provided.
+ */
+function resolveClusterAlarmDefinitions(cluster, config, serverlessScaling) {
+    if (config?.enabled === false)
+        return [];
+    const definitions = [];
+    if (config?.cpuUtilization !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.cpuUtilization, cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS.cpuUtilization);
+        definitions.push({
+            key: "cpuUtilization",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("CPUUtilization", { period: METRIC_PERIOD, statistic: "Average" }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune cluster CPU utilization is high. Threshold: >= ${String(cfg.threshold)}% over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    if (config?.mainRequestQueuePendingRequests !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.mainRequestQueuePendingRequests, cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS.mainRequestQueuePendingRequests);
+        definitions.push({
+            key: "mainRequestQueuePendingRequests",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("MainRequestQueuePendingRequests", {
+                period: METRIC_PERIOD,
+                statistic: "Average",
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune cluster request queue is backing up. Threshold: > ${String(cfg.threshold)} pending requests over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    if (config?.bufferCacheHitRatio !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.bufferCacheHitRatio, cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS.bufferCacheHitRatio);
+        definitions.push({
+            key: "bufferCacheHitRatio",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("BufferCacheHitRatio", {
+                period: METRIC_PERIOD,
+                statistic: "Average",
+            }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.LESS_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune cluster buffer cache hit ratio is low; working set may exceed memory. Threshold: < ${String(cfg.threshold)}% over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    if (config?.clusterReplicaLag !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.clusterReplicaLag, cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS.clusterReplicaLag);
+        definitions.push({
+            key: "clusterReplicaLag",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("ClusterReplicaLag", { period: METRIC_PERIOD, statistic: "Average" }),
+            threshold: cfg.threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune read replica is lagging the writer. Threshold: > ${String(cfg.threshold)} ms over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    // Contextual: only meaningful for a serverless cluster, where capacity is
+    // measured in NCUs and a ceiling is configured. The threshold defaults to a
+    // fraction of the configured maximum.
+    if (serverlessScaling !== undefined && config?.serverlessDatabaseCapacity !== false) {
+        const cfg = (0, cloudwatch_1.resolveAlarmConfig)(config?.serverlessDatabaseCapacity, cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS.serverlessDatabaseCapacity);
+        const threshold = config?.serverlessDatabaseCapacity?.threshold ??
+            serverlessScaling.maxCapacity * SERVERLESS_CAPACITY_ALARM_FRACTION;
+        definitions.push({
+            key: "serverlessDatabaseCapacity",
+            alarmName: cfg.alarmName,
+            metric: cluster.metric("ServerlessDatabaseCapacity", {
+                period: METRIC_PERIOD,
+                statistic: "Average",
+            }),
+            threshold,
+            comparisonOperator: aws_cloudwatch_1.ComparisonOperator.GREATER_THAN_OR_EQUAL_TO_THRESHOLD,
+            evaluationPeriods: cfg.evaluationPeriods,
+            datapointsToAlarm: cfg.datapointsToAlarm,
+            treatMissingData: cfg.treatMissingData,
+            description: `Neptune serverless capacity is sustained near its ${String(serverlessScaling.maxCapacity)} NCU ceiling. Threshold: >= ${String(threshold)} NCU over ${METRIC_PERIOD_LABEL} periods.`,
+        });
+    }
+    return definitions;
+}
+/**
+ * Creates recommended CloudWatch alarms for a Neptune cluster, merging the
+ * recommended definitions with any custom alarm builders.
+ *
+ * @param scope - CDK construct scope for creating alarm constructs.
+ * @param id - Base identifier for alarm construct ids.
+ * @param cluster - The Neptune cluster to create alarms for.
+ * @param config - User-provided alarm configuration, or `false` to disable all.
+ * @param serverlessScaling - The cluster's serverless scaling config, if any.
+ * @param customAlarms - Custom alarm builders added via `addAlarm()`.
+ * @returns A record mapping alarm keys to their created Alarm constructs.
+ */
+function createClusterAlarms(scope, id, cluster, config, serverlessScaling, customAlarms = []) {
+    if (config === false)
+        return {};
+    const enabled = config?.enabled ?? cluster_alarm_defaults_js_1.CLUSTER_ALARM_DEFAULTS.enabled;
+    if (!enabled)
+        return {};
+    const recommended = resolveClusterAlarmDefinitions(cluster, config, serverlessScaling);
+    const custom = customAlarms.map((b) => b.resolve(cluster));
+    return (0, cloudwatch_1.createAlarms)(scope, id, [...recommended, ...custom]);
+}
+//# sourceMappingURL=cluster-alarms.js.map

package/dist/commonjs/cluster-alarms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-alarms.js","sourceRoot":"","sources":["../../src/cluster-alarms.ts"],"names":[],"mappings":"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"}