@fjall/components-infrastructure 12.0.0 → 12.1.1

package/dist/lib/patterns/aws/clickhouseDatabase.d.ts

@@ -3,6 +3,7 @@ import { type TaskDefinition } from "aws-cdk-lib/aws-ecs";
 import { type IBucket } from "aws-cdk-lib/aws-s3";
 import { Construct } from "constructs";
 import { Secret, type SecretImport } from "../../resources/aws/secrets/secret.js";
+import { type ClickHouseAlarmThresholds } from "../../resources/aws/monitoring/index.js";
 import { type ClickHouseSchemaAdmin, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";
 import { type ISecret } from "aws-cdk-lib/aws-secretsmanager";
 import { type ITopic } from "aws-cdk-lib/aws-sns";
@@ -73,8 +74,15 @@ export interface ClickHouseDatabaseProps {
     /**
      * BACKUP DATABASE TO S3 schedule (D19). Schedule string validated by CDK
      * `Schedule.expression(...)` at synth time. `false` disables the sidecar
-     * (and skips the backup-task log group).
+     * (and skips the backup-task log group, so no backup alarms materialise).
      * Default: `BACKUP_SCHEDULE` from `clickhouseConstants.ts`.
+     *
+     * Coupled to `alarms.backupHeartbeatWindowHours`: the backup heartbeat
+     * pages when no success lands within the window (default 26 h, sized for
+     * the daily default). A customised schedule without a matching window
+     * override draws a synth-time warning — sparser-than-daily schedules must
+     * widen the window (max 143 h — the paging-guarantee ceiling), and
+     * schedules sparser than ~5.8 days must disable the heartbeat.
      */
     backupSchedule?: string | false;
     /**
@@ -136,22 +144,50 @@ export interface ClickHouseDatabaseProps {
      */
     tls?: ClickHouseTlsOptions;
     /**
-     * Ops alarm SNS topic for the ClickHouse host-posture alarms (CPU / memory /
-     * disk warn+critical) and — when `backupSchedule` is enabled — the
-     * backup-failure alarm. Accepts an `ITopic`, an `arn:` string, or the
-     * `"import:<ExportName>"` form the generator scaffolds onto production apps
-     * (`"import:SharedAlarmTopicArn"`). Forwarded automatically by
-     * `DatabaseFactory.build` from `BaseDatabaseProps.alertsTopic`. Omitted (the
-     * default) → no host alarms, matching the dormant pre-dogfood behaviour.
+     * Ops alarm SNS topic for the full ClickHouse alarm surface: host-posture
+     * alarms (CPU / disk warn+critical), the ECS-layer service alarms (cgroup
+     * memory, `RunningTaskCount` liveness, task-stop watchdog), the server-log
+     * signal alarms (errors, failed queries, backpressure, cold-tier S3), and —
+     * when `backupSchedule` is enabled — the backup-failure alarm plus the
+     * backup success heartbeat (absence + arming-gate alarms and the paging
+     * composite). Accepts an
+     * `ITopic`, an `arn:` string, or the `"import:<ExportName>"` form the
+     * generator scaffolds onto production apps (`"import:SharedAlarmTopicArn"`).
+     * Forwarded automatically by `DatabaseFactory.build`. Omitted (the default)
+     * → no alarms, matching the dormant pre-dogfood behaviour.
      *
-     * Resolved internally via `resolveAlertsTopic`; the construct owns the
-     * `instanceRole` / `asgName` / `backupTaskLogGroup` the alarms need, so no
-     * caller wiring is required. The stuck-merge alarm is NOT declared here —
-     * `"Stuck merge detected"` is emitted by the webapp app process, so it lives
-     * on the app service's declarative `logAlarms` instead.
+     * Resolved internally via `resolveAlertsTopic` and threaded into the inner
+     * `EcsCompute` so the generic ECS alarm pipeline materialises alongside the
+     * curated host set; the container-CPU service alarm is deliberately
+     * disabled (host CPU owns that signal — a 1-vCPU box pins container CPU on
+     * routine merges). The construct owns the `instanceRole` / `asgName` /
+     * `backupTaskLogGroup` the alarms need, so no caller wiring is required.
+     * The stuck-merge alarm is NOT declared here — `"Stuck merge detected"` is
+     * emitted by the webapp app process, so it lives on the app service's
+     * declarative `logAlarms` instead.
      */
     alertsTopic?: ITopic | string;
+    /**
+     * Alarm-threshold tuning knob, fanned out across the host alarms, the ECS
+     * service memory alarm, and the server-log signal alarms — see
+     * `ClickHouseAlarmThresholds` for the per-field defaults. `false` suppresses
+     * the whole ClickHouse alarm surface (host, service, log, watchdog) even
+     * when `alertsTopic` is set; the persistent-data-volume alarms are
+     * infrastructure-level and unaffected. Omitted → defaults.
+     */
+    alarms?: ClickHouseAlarmThresholds | false;
+    /**
+     * Application ID for webhook-to-application alarm mapping. Tagged onto every
+     * ClickHouse alarm and appended to alarm descriptions — same contract as the
+     * RDS branch of `DatabaseFactory.build`.
+     */
+    applicationId?: string;
 }
+/**
+ * Public-facing re-export of the alarm knob so factory consumers can type
+ * `alarms:` from the patterns layer (same convention as `ServiceLogAlarm`).
+ */
+export type { ClickHouseAlarmThresholds };
 /**
  * ClickHouse analytics database wrapper implementing IClickHouseDatabase.
  *

package/dist/lib/patterns/aws/clickhouseDatabase.js

@@ -19,9 +19,9 @@ import { createClickHouseSecurityGroup } from "../../resources/aws/database/clic
 import { buildClickHouseEntrypointWrapper, buildClickHouseUserData, generateUsersConfigXml } from "../../resources/aws/database/clickhouseUserData.js";
 import { toPascalCase } from "../../utils/capitaliseString.js";
 import { resolveAlertsTopic } from "../../utils/resolveAlertsTopic.js";
-import { createClickHouseAlarms } from "../../resources/aws/monitoring/index.js";
+import { createClickHouseAlarms, validateClickHouseAlarmThresholds, BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS, BACKUP_HEARTBEAT_MAX_WINDOW_HOURS, METRIC_NAMESPACE, stackScopedMetricNamespace } from "../../resources/aws/monitoring/index.js";
 import { ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, PROFILE_NAME_PATTERN } from "../../resources/aws/database/clickhouseSchemas.js";
-import { deriveClickHouseDefaultProfiles } from "../../resources/aws/database/clickhouseTuning.js";
+import { deriveClickHouseDefaultProfiles, deriveClickHouseServerTuning } from "../../resources/aws/database/clickhouseTuning.js";
 import { inferAmiHardwareType } from "../../resources/aws/compute/ecsConstants.js";
 import { CLICKHOUSE_DATABASE_NAME, DEFAULT_CLICKHOUSE_INSTANCE_TYPE, CLICKHOUSE_IMAGE, CLICKHOUSE_EBS_VOLUME_SIZE_GB, CLICKHOUSE_EBS_IOPS, CLICKHOUSE_EBS_THROUGHPUT_MBPS, clickHouseTaskMemoryMiB, CLICKHOUSE_HTTP_PORT, CLICKHOUSE_HTTPS_PORT, CLICKHOUSE_NATIVE_PORT, CLICKHOUSE_TCP_SECURE_PORT, CLICKHOUSE_TLS_CERT_MOUNT_PATH, CLICKHOUSE_PROMETHEUS_PORT, CLICKHOUSE_DATA_MOUNT_PATH, CLICKHOUSE_SECRET_OPTIONS, CLICKHOUSE_SERVER_ROLE_TAG, CLICKHOUSE_HOST_METRICS, clickHouseUserSecretName, CLICKHOUSE_HEALTH_CHECK, CLICKHOUSE_STOP_TIMEOUT_SECONDS, CLICKHOUSE_EBS_DEVICE_NAME, CLICKHOUSE_CONFIG_SUBDIR, CLICKHOUSE_USERS_SUBDIR, userPasswordEnvName, OPTIMISE_FINAL_SCHEDULE, REPLACING_MERGE_TREE_TABLES, OPTIMISE_MV_TABLES, CLICKHOUSE_CLOUDMAP_SERVICE_NAME, CLICKHOUSE_SERVER_CONTAINER_NAME, CLICKHOUSE_SERVICE_NAME, OPTIMISE_TASK_MEMORY_MIB, OPTIMISE_TASK_CPU_UNITS, BACKUP_SCHEDULE, BACKUP_TASK_MEMORY_MIB, BACKUP_TASK_CPU_UNITS, BACKUP_RETENTION_DAYS } from "../../resources/aws/database/clickhouseConstants.js";
 import { TlsCertGenerator } from "../../resources/aws/utilities/tlsCertGenerator.js";
@@ -50,6 +50,75 @@ function resolveClickHouseDesiredCount(contextValue, propValue) {
         return propValue;
     return 1;
 }
+/**
+ * Positional (space-delimited) CloudWatch filter patterns for ClickHouse
+ * server-log lines, e.g.:
+ *
+ *   `2026.08.12 10:15:42.123456 [ 456 ] {query-id} <Error> executeQuery: …`
+ *
+ * CloudWatch tokenises on spaces, treating the bracketed thread id `[ 456 ]`
+ * as ONE field, so the severity token is always field 5 and the component
+ * token field 6. Positional matching is the only reliable shape here:
+ * CloudWatch's regex subset rejects `<`/`>` and `()` grouping outright, and a
+ * plain substring term (`"<Error>"` unanchored) false-positives on query text
+ * echoed into log lines (a SELECT containing the literal). The severity
+ * position cannot.
+ */
+const CLICKHOUSE_ERROR_LINE_PATTERN = '[w1, w2, w3, w4, w5="<Error>" || w5="<Fatal>", ...]';
+const CLICKHOUSE_FAILED_QUERY_PATTERN = '[w1, w2, w3, w4, w5="<Error>", w6="executeQuery:", ...]';
+/**
+ * Server-log signal alarm specs for the ClickHouse service's declarative
+ * `logAlarms`. Three always-on signals plus a cold-tier S3 signal when the
+ * cold tier is enabled. Thresholds come from the `alarms` knob with defaults
+ * documented on `ClickHouseAlarmThresholds`; the failed-queries default
+ * derives from the instance's `maxConcurrentQueries` so it tracks host size.
+ */
+function buildClickHouseLogAlarmSpecs(thresholds, coldTierEnabled, maxConcurrentQueries) {
+    const specs = [
+        {
+            idStem: "ClickHouseServerErrors",
+            metricName: "ClickHouseServerErrorCount",
+            description: "ClickHouse server error/fatal log rate exceeds threshold — check system.errors, recent merges, and disk headroom",
+            literal: CLICKHOUSE_ERROR_LINE_PATTERN,
+            threshold: thresholds.serverErrorsPer5Min ?? 30,
+            period: Duration.minutes(5),
+            evaluationPeriods: 3,
+            datapointsToAlarm: 2
+        },
+        {
+            idStem: "ClickHouseFailedQueries",
+            metricName: "ClickHouseFailedQueryCount",
+            description: "ClickHouse failed-query rate exceeds threshold — check system.query_log for the failing statement and error code",
+            literal: CLICKHOUSE_FAILED_QUERY_PATTERN,
+            threshold: thresholds.failedQueriesPer5Min ?? 3 * maxConcurrentQueries,
+            period: Duration.minutes(5),
+            evaluationPeriods: 3,
+            datapointsToAlarm: 2
+        },
+        {
+            idStem: "ClickHouseBackpressure",
+            metricName: "ClickHouseBackpressureCount",
+            description: "ClickHouse background backpressure — merge scheduling pausing or parts accumulating; check background pool sizing and partition granularity",
+            anyTerms: ["Temporarily pause scheduling", "Too many parts"],
+            threshold: thresholds.backpressurePer15Min ?? 50,
+            period: Duration.minutes(15),
+            evaluationPeriods: 2,
+            datapointsToAlarm: 2
+        }
+    ];
+    if (coldTierEnabled) {
+        specs.push({
+            idStem: "ClickHouseColdTierS3Errors",
+            metricName: "ClickHouseColdTierS3ErrorCount",
+            description: "ClickHouse server-side S3 errors (cold-tier moves or BACKUP TO S3) — check the instance role grants and bucket policies for the cold-tier and backup buckets",
+            anyTerms: ["S3_ERROR", "AccessDenied"],
+            threshold: 1,
+            period: Duration.minutes(15),
+            evaluationPeriods: 1
+        });
+    }
+    return specs;
+}
 /**
  * Narrow `T | undefined` to `T`. Used at the 3 sites where a `Map.get(...)` /
  * `Array.find(...)` result is structurally undefined-able but invariants
@@ -367,9 +436,22 @@ export class ClickHouseDatabase extends Construct {
                 userSecret.getImport("password");
         }
         const resolvedAlertsTopic = resolveAlertsTopic(this, "AlertsTopic", props.alertsTopic);
+        const alarmsDisabled = props.alarms === false;
+        const alarmThresholds = typeof props.alarms === "object" ? props.alarms : {};
+        validateClickHouseAlarmThresholds(alarmThresholds);
+        const serverTuning = deriveClickHouseServerTuning(instanceType);
+        const serviceLogAlarms = alarmsDisabled
+            ? undefined
+            : buildClickHouseLogAlarmSpecs(alarmThresholds, coldTierEnabled, serverTuning.maxConcurrentQueries);
         const ecsCompute = new EcsCompute(this, "Compute", {
             type: "ecs",
             vpc,
+            ...(resolvedAlertsTopic !== undefined && {
+                alertsTopic: resolvedAlertsTopic
+            }),
+            ...(props.applicationId !== undefined && {
+                applicationId: props.applicationId
+            }),
             cluster: {
                 loadBalancer: false,
                 securityGroup,
@@ -380,6 +462,22 @@ export class ClickHouseDatabase extends Construct {
                     name: CLICKHOUSE_SERVICE_NAME,
                     capacityProvider: "EC2",
                     desiredCount,
+                    alarms: alarmsDisabled
+                        ? false
+                        : {
+                            // Container CPU is deliberately NOT alarmed: the host CPU
+                            // alarm (AWS/EC2) owns that signal on this single-purpose
+                            // box, and merges routinely pin container CPU on 1-vCPU
+                            // hosts. Memory IS alarmed here rather than via CWAgent —
+                            // the ECS denominator is `clickHouseTaskMemoryMiB()`, so
+                            // the % means the same headroom on every instance size.
+                            cpuThreshold: false,
+                            memoryThreshold: alarmThresholds.memoryThreshold ?? 90
+                        },
+                    ...(serviceLogAlarms !== undefined && {
+                        logAlarms: serviceLogAlarms
+                    }),
+                    logMetricNamespace: stackScopedMetricNamespace(METRIC_NAMESPACE.CLICKHOUSE),
                     // Omitting `scaling` attaches default CPU target tracking. A scaled-out
                     // second task is an EMPTY second database behind the same Cloud Map name
                     // (plain MergeTree does not replicate) — desired-count scaling stays off.
@@ -527,12 +625,23 @@ export class ClickHouseDatabase extends Construct {
         // it the alarms cannot be built; no topic is the default, so skip silently
         // rather than throw.
         const asgName = ecsCompute.getAutoScalingGroupName();
-        if (resolvedAlertsTopic !== undefined && asgName !== undefined) {
+        if (resolvedAlertsTopic !== undefined &&
+            asgName !== undefined &&
+            !alarmsDisabled) {
+            if (backupEnabled &&
+                typeof props.backupSchedule === "string" &&
+                alarmThresholds.backupHeartbeatWindowHours === undefined) {
+                Annotations.of(this).addWarningV2("fjall:clickhouse:backup-heartbeat-window", `backupSchedule is customised but alarms.backupHeartbeatWindowHours is not set — the backup heartbeat pages when no successful backup lands within ${BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS}h. For sparser schedules set backupHeartbeatWindowHours (schedule interval + 2h margin, max ${BACKUP_HEARTBEAT_MAX_WINDOW_HOURS}); schedules sparser than ~5.8 days cannot be heartbeat-monitored — set false to disable the heartbeat instead.`);
+            }
             createClickHouseAlarms({
                 scope: this,
                 instanceRole,
                 asgName,
                 alarmTopic: resolvedAlertsTopic,
+                config: alarmThresholds,
+                ...(props.applicationId !== undefined && {
+                    applicationId: props.applicationId
+                }),
                 ...(backupTaskLogGroup !== undefined && { backupTaskLogGroup })
             });
         }

package/dist/lib/patterns/aws/database.d.ts

@@ -4,7 +4,7 @@ import type { ITopic } from "aws-cdk-lib/aws-sns";
 import type { RdsAlarmThresholds } from "../../resources/aws/monitoring/index.js";
 import type App from "../../app.js";
 import { type DynamoDBKeySchema, type DynamoDBGlobalSecondaryIndex } from "../../resources/aws/database/dynamodb.js";
-import { ClickHouseDatabase, type ClickHouseDatabaseProps } from "./clickhouseDatabase.js";
+import { ClickHouseDatabase, type ClickHouseDatabaseProps, type ClickHouseAlarmThresholds } from "./clickhouseDatabase.js";
 import { type Connections, type IConnectable, type IVpc } from "aws-cdk-lib/aws-ec2";
 import { type ITable } from "aws-cdk-lib/aws-dynamodb";
 import { type Secret, type SecretImport } from "../../resources/aws/secrets/index.js";
@@ -331,7 +331,7 @@ export declare class RelationalDatabase extends Construct implements IRelational
      */
     grantIamConnect(grantee: IGrantable, dbUsername: string): Grant;
 }
-export { ClickHouseDatabase, type ClickHouseDatabaseProps };
+export { ClickHouseDatabase, type ClickHouseDatabaseProps, type ClickHouseAlarmThresholds };
 export { ClickHouseDefaultProfiles, ClickHouseSchemaAdminSchema, ManagedPasswordNameSchema, ProfileSpecSchema, type ClickHouseSchemaAdmin, type ManagedPasswordName, type ProfileSpec } from "../../resources/aws/database/clickhouseSchemas.js";
 export { renderUsersXml } from "../../resources/aws/database/clickhouseXmlRenderer.js";
 export type { RenderUsersXmlOptions } from "../../resources/aws/database/clickhouseXmlRenderer.js";

package/dist/lib/resources/aws/database/clickhouseUserData.js

@@ -119,8 +119,9 @@ export function generateServerConfigXml(options) {
          max_bytes_before_external_group_by) live in the profile blocks of
          users.xml — ClickHouse 26.3.10 rejects them at top level with
          UNKNOWN_ELEMENT_IN_CONFIG. The default localhost user inherits
-         ClickHouse's built-in defaults; workload users (app_writer,
-         audit_writer, backup_reader, schema_admin) carry explicit caps. -->
+         ClickHouse's built-in defaults; the SQL-managed workload users
+         (app_writer, audit_writer, backup_reader) and the XML-defined
+         schema_admin all carry explicit caps via their bound profiles. -->
     <!-- Mark + index-mark caches scale linearly with instance memory
          (384 MiB + 128 MiB at the 4 GiB baseline). CH counts these against
          max_server_memory_usage. On a single-tenant dashboard workload they
@@ -360,8 +361,10 @@ chmod 600 "$MOUNT_POINT/server-certs/server.key"
 chmod 644 "$MOUNT_POINT/server-certs/client.xml"
 `
         : "";
-    // The CWAgent-namespace alarms (mem_used_percent / disk_used_percent) have
-    // no producer without this — no CloudWatch Agent is installed. The ASG name
+    // The CWAgent-namespace metrics have no producer without this — no
+    // CloudWatch Agent is installed. disk_used_percent feeds the host disk
+    // alarms; mem_used_percent is dashboards-only (the CWAgent memory alarm is
+    // retired — memory alarming lives on ECS MemoryUtilization). The ASG name
     // (the alarms' dimension) is unknowable at synth (LaunchTemplate → ASG is a
     // CFN cycle), so it resolves at run time: IMDS instance tags first, with a
     // describe-auto-scaling-instances fallback. AL2023 ECS AMIs ship no cron;

package/dist/lib/resources/aws/monitoring/alarmDefaults.d.ts

@@ -1,5 +1,5 @@
 import { Duration } from "aws-cdk-lib";
-import type { Alarm } from "aws-cdk-lib/aws-cloudwatch";
+import type { Alarm, AlarmBase } from "aws-cdk-lib/aws-cloudwatch";
 import type { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
 /**
  * Tag key for mapping CloudWatch alarms to Fjall applications.
@@ -36,5 +36,5 @@ export declare const ALARM_DEFAULTS: {
 export declare function buildAlarmDescription(baseDescription: string, applicationId: string | undefined): string;
 /** Wire an alarm to the SNS topic (both ALARM and OK transitions) and collect it. */
 export declare function registerAlarm(alarm: Alarm, snsAction: SnsAction, alarms: Alarm[]): void;
-/** Tag all alarms with the application ID for webhook-to-application mapping. */
-export declare function tagAlarmsWithApplicationId(alarms: Alarm[], applicationId: string | undefined): void;
+/** Tag all alarms (incl. composite alarms) with the application ID for webhook-to-application mapping. */
+export declare function tagAlarmsWithApplicationId(alarms: readonly AlarmBase[], applicationId: string | undefined): void;

package/dist/lib/resources/aws/monitoring/alarmDefaults.js

@@ -25,7 +25,7 @@ export function registerAlarm(alarm, snsAction, alarms) {
     alarm.addOkAction(snsAction);
     alarms.push(alarm);
 }
-/** Tag all alarms with the application ID for webhook-to-application mapping. */
+/** Tag all alarms (incl. composite alarms) with the application ID for webhook-to-application mapping. */
 export function tagAlarmsWithApplicationId(alarms, applicationId) {
     if (!applicationId)
         return;

package/dist/lib/resources/aws/monitoring/clickhouseAlarms.d.ts

@@ -3,16 +3,75 @@ import type { IRole } from "aws-cdk-lib/aws-iam";
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import type { ILogGroup } from "aws-cdk-lib/aws-logs";
 import type { Construct } from "constructs";
+/**
+ * The single alarm-tuning knob on `ClickHouseDatabaseProps.alarms`. The
+ * ClickHouseDatabase pattern fans it out across three mechanisms: host-level
+ * fields feed `createClickHouseAlarms` (this factory), `memoryThreshold` feeds
+ * the generic ECS service memory alarm (cgroup-honest — the container limit
+ * IS `clickHouseTaskMemoryMiB()`, so the % means the same headroom on every
+ * instance size), and the log-signal fields feed the service's declarative
+ * `logAlarms` specs.
+ */
 export interface ClickHouseAlarmThresholds {
-    /** EC2 host CPU % over 5 min. Default 90. */
+    /** EC2 host CPU % over 5 min. Default 90. Informational on a 1-vCPU host —
+     *  merges routinely pin CPU; liveness is owned by the ECS running-tasks
+     *  alarm. */
     cpuThreshold?: number;
-    /** EC2 host memory % over 5 min (CWAgent namespace). Default 80. */
+    /** ECS `MemoryUtilization` % over 5 min (container cgroup vs the task
+     *  memory limit). Default 90. Consumed by the service-level memory alarm
+     *  the ClickHouseDatabase pattern wires, NOT by this factory — the former
+     *  CWAgent host-memory alarm is retired (its threshold meant a different
+     *  headroom per instance size; the timer metric remains for dashboards). */
     memoryThreshold?: number;
     /** ClickHouse data volume disk % used. Default 70 (warn) — paired with critical at 85. */
     diskWarnThreshold?: number;
     /** ClickHouse data volume disk % used. Default 85. */
     diskCriticalThreshold?: number;
+    /** `<Error>`/`<Fatal>` server-log lines per 5 min. Default 30. */
+    serverErrorsPer5Min?: number;
+    /** Failed `executeQuery:` error lines per 5 min. Default derived:
+     *  3 × `deriveClickHouseServerTuning(instanceType).maxConcurrentQueries`. */
+    failedQueriesPer5Min?: number;
+    /** Background-backpressure lines ("Temporarily pause scheduling" /
+     *  "Too many parts") per 15 min. Default 50. */
+    backpressurePer15Min?: number;
+    /** Backup heartbeat window in hours (integer, 1–143): the maximum tolerated
+     *  gap between backup successes before the heartbeat composite pages.
+     *  Default 26 — the daily schedule interval plus a 2 h completion-drift
+     *  margin. The 143 ceiling keeps the paging guarantee ahead of the arming
+     *  gate's 7-day memory (see `BACKUP_HEARTBEAT_MAX_WINDOW_HOURS`); schedules
+     *  sparser than ~5.8 days cannot be heartbeat-monitored — set `false` to
+     *  disable the heartbeat trio (the success metric filter remains for
+     *  dashboards). */
+    backupHeartbeatWindowHours?: number | false;
 }
+/**
+ * The subset of the knob this factory actually reads — host CPU + disk + the
+ * backup heartbeat window. The remaining fields are consumed by the pattern's
+ * service-alarm and logAlarms wiring (see `ClickHouseAlarmThresholds`).
+ */
+export type ClickHouseHostAlarmThresholds = Pick<ClickHouseAlarmThresholds, "cpuThreshold" | "diskWarnThreshold" | "diskCriticalThreshold" | "backupHeartbeatWindowHours">;
+export declare const BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS = 26;
+/**
+ * Ceiling derivation — an ORDERING bound, not CloudWatch expressibility.
+ * The 7-day evaluation-span cap would allow 168 hourly buckets, but the
+ * composite only pages while the arming gate still reads OK, and the gate's
+ * 7 daily buckets are UTC-midnight-aligned: after a success at UTC hour h
+ * the gate re-alarms 168 − h hours later (h ≤ 23), while the absence alarm
+ * needs windowHours + 1 hours. Paging is therefore guaranteed for every
+ * schedule time only when windowHours ≤ 143; above that the gate can
+ * re-alarm first and the composite never fires. Net: schedules sparser than
+ * ~5.8 days (141 h interval + the 2 h margin) cannot be heartbeat-monitored
+ * — disable with `false` instead.
+ */
+export declare const BACKUP_HEARTBEAT_MAX_WINDOW_HOURS = 143;
+/**
+ * Pure validation for the alarm-thresholds knob (synth-contract corpus
+ * surface). Called from both the `ClickHouseDatabase` constructor and
+ * `createClickHouseAlarms` — the factory call is defence-in-depth; the
+ * constructor call is what a direct instantiation hits.
+ */
+export declare function validateClickHouseAlarmThresholds(config: ClickHouseHostAlarmThresholds): void;
 export interface ClickHouseAlarmsProps {
     scope: Construct;
     /**
@@ -36,12 +95,14 @@ export interface ClickHouseAlarmsProps {
      * Omitted when `backupSchedule: false` — no backup task, no log group.
      */
     backupTaskLogGroup?: ILogGroup;
-    config?: ClickHouseAlarmThresholds;
+    config?: ClickHouseHostAlarmThresholds;
+    /** Application ID for webhook-to-application alarm mapping. */
+    applicationId?: string;
 }
 /**
  * Single-node ClickHouse host-posture alarms. Covers host-level CPU (AWS/EC2)
- * plus memory and disk in the `CWAgent` namespace — fed NOT by the CloudWatch
- * Agent (never installed on these hosts) but by the lightweight put-metric-data
+ * plus disk in the `CWAgent` namespace — fed NOT by the CloudWatch Agent
+ * (never installed on these hosts) but by the lightweight put-metric-data
  * timer the user-data installs (see `buildClickHouseUserData`), which publishes
  * `mem_used_percent` / `disk_used_percent` under the same names and
  * `AutoScalingGroupName` dimension the agent would use — plus the
@@ -51,9 +112,20 @@ export interface ClickHouseAlarmsProps {
  *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
  *   that masked the original IAM-grant misconfiguration (see
  *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ * - **Backup success heartbeat** — pages when no `BACKUP_CREATED` success
+ *   marker lands within the heartbeat window on a stack whose backups
+ *   previously succeeded. The complete-but-slow complement of the failure
+ *   alarm: catches hangs, dead schedulers, and tasks that never start (see
+ *   `createBackupHeartbeat` and
+ *   `designs/2026-08-15-clickhouse-backup-success-heartbeat.md`).
  *
  * The stuck-merge alarm — a `"Stuck merge detected"` line emitted by the webapp
  * app process, not this construct — lives on the app service's declarative
  * `logAlarms` instead; it is an app-log alarm, not a database-host concern.
+ * Memory, liveness, and server-log signals are likewise NOT here: the
+ * ClickHouseDatabase pattern wires those through the generic ECS service
+ * alarms (cgroup memory ≥ 90, `RunningTaskCount` < 1) and the service's
+ * declarative `logAlarms` — this factory owns only what the ECS layer cannot
+ * see (the EC2 host and the backup task).
  */
 export declare function createClickHouseAlarms(props: ClickHouseAlarmsProps): Alarm[];

package/dist/lib/resources/aws/monitoring/clickhouseAlarms.js

@@ -1,15 +1,58 @@
 import { Duration } from "aws-cdk-lib";
-import { Alarm, ComparisonOperator, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
+import { Alarm, AlarmRule, AlarmState, ComparisonOperator, CompositeAlarm, MathExpression, TreatMissingData } from "aws-cdk-lib/aws-cloudwatch";
 import { SnsAction } from "aws-cdk-lib/aws-cloudwatch-actions";
 import { Metric } from "aws-cdk-lib/aws-cloudwatch";
 import { FilterPattern, MetricFilter } from "aws-cdk-lib/aws-logs";
-import { ALARM_DEFAULTS, registerAlarm, buildAlarmDescription } from "./alarmDefaults.js";
-import { METRIC_NAMESPACE } from "./metricNamespaces.js";
+import { ALARM_DEFAULTS, registerAlarm, tagAlarmsWithApplicationId, buildAlarmDescription } from "./alarmDefaults.js";
+import { METRIC_NAMESPACE, stackScopedMetricNamespace } from "./metricNamespaces.js";
 import { CLICKHOUSE_HOST_METRICS } from "../database/clickhouseConstants.js";
+export const BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS = 26;
+/**
+ * Ceiling derivation — an ORDERING bound, not CloudWatch expressibility.
+ * The 7-day evaluation-span cap would allow 168 hourly buckets, but the
+ * composite only pages while the arming gate still reads OK, and the gate's
+ * 7 daily buckets are UTC-midnight-aligned: after a success at UTC hour h
+ * the gate re-alarms 168 − h hours later (h ≤ 23), while the absence alarm
+ * needs windowHours + 1 hours. Paging is therefore guaranteed for every
+ * schedule time only when windowHours ≤ 143; above that the gate can
+ * re-alarm first and the composite never fires. Net: schedules sparser than
+ * ~5.8 days (141 h interval + the 2 h margin) cannot be heartbeat-monitored
+ * — disable with `false` instead.
+ */
+export const BACKUP_HEARTBEAT_MAX_WINDOW_HOURS = 143;
+/** Arming memory of the heartbeat: 7 daily buckets — the 7-day CloudWatch
+ *  evaluation-span cap, the longest "a backup has succeeded recently" memory
+ *  an alarm can carry. */
+const BACKUP_HEARTBEAT_ARMING_DAYS = 7;
+/** Composite actions wait this long for the suppressor (arming gate) to
+ *  reach ALARM before firing — the real page's only added latency. */
+const BACKUP_HEARTBEAT_SUPPRESSOR_WAIT = Duration.minutes(2);
+/** Composite actions stay suppressed this long after the gate LEAVES ALARM:
+ *  covers the arming transition, where both children flip ALARM→OK on the
+ *  same first-success datapoint but on unsynchronised ~1-minute evaluation
+ *  cycles — a gate-first ordering would otherwise transiently satisfy the
+ *  rule and page the very stacks the design promises stay quiet. */
+const BACKUP_HEARTBEAT_SUPPRESSOR_EXTENSION = Duration.minutes(5);
+/**
+ * Pure validation for the alarm-thresholds knob (synth-contract corpus
+ * surface). Called from both the `ClickHouseDatabase` constructor and
+ * `createClickHouseAlarms` — the factory call is defence-in-depth; the
+ * constructor call is what a direct instantiation hits.
+ */
+export function validateClickHouseAlarmThresholds(config) {
+    const windowHours = config.backupHeartbeatWindowHours;
+    if (windowHours === undefined || windowHours === false)
+        return;
+    if (!Number.isInteger(windowHours) ||
+        windowHours < 1 ||
+        windowHours > BACKUP_HEARTBEAT_MAX_WINDOW_HOURS) {
+        throw new Error(`ClickHouseDatabase: alarms.backupHeartbeatWindowHours must be an integer between 1 and ${BACKUP_HEARTBEAT_MAX_WINDOW_HOURS} (hours), or false to disable the backup heartbeat; got ${windowHours}.`);
+    }
+}
 /**
  * Single-node ClickHouse host-posture alarms. Covers host-level CPU (AWS/EC2)
- * plus memory and disk in the `CWAgent` namespace — fed NOT by the CloudWatch
- * Agent (never installed on these hosts) but by the lightweight put-metric-data
+ * plus disk in the `CWAgent` namespace — fed NOT by the CloudWatch Agent
+ * (never installed on these hosts) but by the lightweight put-metric-data
  * timer the user-data installs (see `buildClickHouseUserData`), which publishes
  * `mem_used_percent` / `disk_used_percent` under the same names and
  * `AutoScalingGroupName` dimension the agent would use — plus the
@@ -19,17 +62,29 @@ import { CLICKHOUSE_HOST_METRICS } from "../database/clickhouseConstants.js";
  *   task's BACKUP DATABASE TO S3 statement. Closes the silent-failure mode
  *   that masked the original IAM-grant misconfiguration (see
  *   `designs/2026-04-27-clickhouse-backup-iam-role.md`).
+ * - **Backup success heartbeat** — pages when no `BACKUP_CREATED` success
+ *   marker lands within the heartbeat window on a stack whose backups
+ *   previously succeeded. The complete-but-slow complement of the failure
+ *   alarm: catches hangs, dead schedulers, and tasks that never start (see
+ *   `createBackupHeartbeat` and
+ *   `designs/2026-08-15-clickhouse-backup-success-heartbeat.md`).
  *
  * The stuck-merge alarm — a `"Stuck merge detected"` line emitted by the webapp
  * app process, not this construct — lives on the app service's declarative
  * `logAlarms` instead; it is an app-log alarm, not a database-host concern.
+ * Memory, liveness, and server-log signals are likewise NOT here: the
+ * ClickHouseDatabase pattern wires those through the generic ECS service
+ * alarms (cgroup memory ≥ 90, `RunningTaskCount` < 1) and the service's
+ * declarative `logAlarms` — this factory owns only what the ECS layer cannot
+ * see (the EC2 host and the backup task).
  */
 export function createClickHouseAlarms(props) {
-    const { scope, instanceRole, asgName, alarmTopic, backupTaskLogGroup, config = {} } = props;
+    const { scope, instanceRole, asgName, alarmTopic, backupTaskLogGroup, config = {}, applicationId } = props;
+    validateClickHouseAlarmThresholds(config);
     const alarms = [];
     const snsAction = new SnsAction(alarmTopic);
     const cpuAlarm = new Alarm(scope, "ClickHouseCpuAlarm", {
-        alarmDescription: buildAlarmDescription("ClickHouse host CPU utilisation exceeds threshold", undefined),
+        alarmDescription: buildAlarmDescription("ClickHouse host CPU utilisation exceeds threshold", applicationId),
         metric: new Metric({
             namespace: "AWS/EC2",
             metricName: "CPUUtilization",
@@ -44,24 +99,9 @@ export function createClickHouseAlarms(props) {
         treatMissingData: TreatMissingData.NOT_BREACHING
     });
     registerAlarm(cpuAlarm, snsAction, alarms);
-    const memoryAlarm = new Alarm(scope, "ClickHouseMemoryAlarm", {
-        alarmDescription: buildAlarmDescription("ClickHouse host memory utilisation exceeds threshold (CWAgent)", undefined),
-        metric: new Metric({
-            namespace: CLICKHOUSE_HOST_METRICS.namespace,
-            metricName: CLICKHOUSE_HOST_METRICS.memoryMetric,
-            dimensionsMap: { [CLICKHOUSE_HOST_METRICS.asgDimension]: asgName },
-            period: ALARM_DEFAULTS.EVALUATION_PERIOD,
-            statistic: "Average"
-        }),
-        threshold: config.memoryThreshold ?? 80,
-        evaluationPeriods: 3,
-        datapointsToAlarm: 2,
-        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
-        treatMissingData: TreatMissingData.NOT_BREACHING
-    });
-    registerAlarm(memoryAlarm, snsAction, alarms);
+    const diskWarnThreshold = config.diskWarnThreshold ?? 70;
     const diskWarnAlarm = new Alarm(scope, "ClickHouseDiskWarnAlarm", {
-        alarmDescription: buildAlarmDescription("ClickHouse data volume above 70% used — plan growth response", undefined),
+        alarmDescription: buildAlarmDescription(`ClickHouse data volume above ${diskWarnThreshold}% used — plan growth response`, applicationId),
         metric: new Metric({
             namespace: CLICKHOUSE_HOST_METRICS.namespace,
             metricName: CLICKHOUSE_HOST_METRICS.diskMetric,
@@ -69,15 +109,16 @@ export function createClickHouseAlarms(props) {
             period: Duration.minutes(15),
             statistic: "Average"
         }),
-        threshold: config.diskWarnThreshold ?? 70,
+        threshold: diskWarnThreshold,
         evaluationPeriods: 2,
         datapointsToAlarm: 2,
         comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
         treatMissingData: TreatMissingData.NOT_BREACHING
     });
     registerAlarm(diskWarnAlarm, snsAction, alarms);
+    const diskCriticalThreshold = config.diskCriticalThreshold ?? 85;
     const diskCriticalAlarm = new Alarm(scope, "ClickHouseDiskCriticalAlarm", {
-        alarmDescription: buildAlarmDescription("ClickHouse data volume above 85% used — imminent insert failures", undefined),
+        alarmDescription: buildAlarmDescription(`ClickHouse data volume above ${diskCriticalThreshold}% used — imminent insert failures`, applicationId),
         metric: new Metric({
             namespace: CLICKHOUSE_HOST_METRICS.namespace,
             metricName: CLICKHOUSE_HOST_METRICS.diskMetric,
@@ -85,7 +126,7 @@ export function createClickHouseAlarms(props) {
             period: Duration.minutes(5),
             statistic: "Average"
         }),
-        threshold: config.diskCriticalThreshold ?? 85,
+        threshold: diskCriticalThreshold,
         evaluationPeriods: 2,
         datapointsToAlarm: 2,
         comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
@@ -98,18 +139,19 @@ export function createClickHouseAlarms(props) {
     registerAlarm(diskCriticalAlarm, snsAction, alarms);
     if (backupTaskLogGroup !== undefined) {
         const backupFailureMetricName = "ClickHouseBackupFailureCount";
+        const backupFailureNamespace = stackScopedMetricNamespace(METRIC_NAMESPACE.CLICKHOUSE);
         new MetricFilter(scope, "ClickHouseBackupFailureMetricFilter", {
             logGroup: backupTaskLogGroup,
-            metricNamespace: METRIC_NAMESPACE.CLICKHOUSE,
+            metricNamespace: backupFailureNamespace,
             metricName: backupFailureMetricName,
             filterPattern: FilterPattern.anyTerm("AccessDenied", "S3Exception"),
             metricValue: "1",
             defaultValue: 0
         });
         const backupFailureAlarm = new Alarm(scope, "ClickHouseBackupFailureAlarm", {
-            alarmDescription: buildAlarmDescription(`ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify instance role '${instanceRole.roleName}' grant on backup bucket`, undefined),
+            alarmDescription: buildAlarmDescription(`ClickHouse BACKUP TO S3 emitted AccessDenied/S3Exception — verify instance role '${instanceRole.roleName}' grant on backup bucket`, applicationId),
             metric: new Metric({
-                namespace: METRIC_NAMESPACE.CLICKHOUSE,
+                namespace: backupFailureNamespace,
                 metricName: backupFailureMetricName,
                 period: Duration.hours(1),
                 statistic: "Sum"
@@ -121,6 +163,126 @@ export function createClickHouseAlarms(props) {
             treatMissingData: TreatMissingData.NOT_BREACHING
         });
         registerAlarm(backupFailureAlarm, snsAction, alarms);
+        createBackupHeartbeat({
+            scope,
+            backupTaskLogGroup,
+            namespace: backupFailureNamespace,
+            windowHours: config.backupHeartbeatWindowHours,
+            snsAction,
+            applicationId,
+            alarms
+        });
     }
+    tagAlarmsWithApplicationId(alarms, applicationId);
     return alarms;
 }
+/**
+ * Backup success heartbeat — the complete-but-slow half of the backup alarm
+ * pair (the AccessDenied/S3Exception failure alarm above is the fast half).
+ * Closes the failure modes the error filter cannot see: a hung BACKUP, a
+ * scheduler that never fires, a task that cannot start.
+ *
+ * The success marker is the backup task's single stdout line per successful
+ * synchronous `BACKUP DATABASE … TO S3(…)` — `<uuid>\tBACKUP_CREATED`
+ * (ClickHouse's terminal success status; a failed backup prints exception
+ * text, which never contains the token, and a run that never happens prints
+ * nothing). Verified against production backup-task logs 2026-08-15.
+ *
+ * Three alarms, one pager:
+ *
+ * - **Absence** (`FILL(m1, 0) < 1`, 1 h buckets × windowHours, no actions) —
+ *   ALARM when no success lands for windowHours consecutive hours. FILL
+ *   materialises zeros for empty buckets, so this is deterministic — but it
+ *   also zero-fills the buckets before the metric existed, putting every
+ *   fresh stack (and every existing stack on the deploy that introduces the
+ *   filter) into ALARM until its first backup.
+ * - **Unestablished** (success Sum < 1 per daily bucket, 7 × 7, no actions) —
+ *   ALARM while no success has been observed in the trailing 7 days: true on
+ *   stacks younger than one backup cycle, false from the first success
+ *   onward. This is the arming gate that absorbs the absence alarm's
+ *   cold-start.
+ * - **Heartbeat composite** (the pager): Absence in ALARM AND Unestablished
+ *   in OK — "backups previously succeeded here and have now stopped". Quiet
+ *   from stack birth, armed by the first observed success. The gate doubles
+ *   as the composite's actions SUPPRESSOR: at the arming transition both
+ *   children flip ALARM→OK on the same datapoint but on unsynchronised
+ *   evaluation cycles, and a gate-first ordering would transiently satisfy
+ *   the rule — the suppressor's extension period absorbs that race, at the
+ *   cost of the real page arriving `BACKUP_HEARTBEAT_SUPPRESSOR_WAIT` late.
+ *   Bounded caveat: after 7 further days of unresolved absence the arming
+ *   gate re-enters ALARM and the composite returns to OK — with its actions
+ *   suppressed by the gate, so no misleading "resolved" notification fires;
+ *   the page fired on day one and the absence alarm stays visibly in ALARM
+ *   in the console.
+ *
+ * Both child alarms treat missing data as breaching so the shape is
+ * deterministic whichever way the metric-math engine renders a
+ * never-populated metric (empty series vs zero-filled grid) — the composite
+ * gate makes the breaching reading safe at birth.
+ */
+function createBackupHeartbeat(props) {
+    const { scope, backupTaskLogGroup, namespace, windowHours, snsAction, applicationId, alarms } = props;
+    const successMetricName = "ClickHouseBackupSuccessCount";
+    // The filter always materialises (dashboards + the heartbeat both read it);
+    // defaultValue 0 emits real zero datapoints whenever backup-task log events
+    // arrive without the success marker — an actively failing backup produces
+    // deterministic breaching data instead of relying on missing-data handling.
+    new MetricFilter(scope, "ClickHouseBackupSuccessMetricFilter", {
+        logGroup: backupTaskLogGroup,
+        metricNamespace: namespace,
+        metricName: successMetricName,
+        filterPattern: FilterPattern.allTerms("BACKUP_CREATED"),
+        metricValue: "1",
+        defaultValue: 0
+    });
+    if (windowHours === false)
+        return;
+    const effectiveWindowHours = windowHours ?? BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS;
+    const hourlySuccesses = new Metric({
+        namespace,
+        metricName: successMetricName,
+        period: Duration.hours(1),
+        statistic: "Sum"
+    });
+    const absenceAlarm = new Alarm(scope, "ClickHouseBackupAbsenceAlarm", {
+        alarmDescription: buildAlarmDescription(`No ClickHouse backup success in the trailing ${effectiveWindowHours}h. No actions here — ClickHouseBackupHeartbeatAlarm pages when this coincides with backups having previously succeeded`, applicationId),
+        metric: new MathExpression({
+            expression: "FILL(m1, 0)",
+            usingMetrics: { m1: hourlySuccesses },
+            label: "Backup successes per hour",
+            period: Duration.hours(1)
+        }),
+        threshold: 1,
+        evaluationPeriods: effectiveWindowHours,
+        datapointsToAlarm: effectiveWindowHours,
+        comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.BREACHING
+    });
+    alarms.push(absenceAlarm);
+    const dailySuccesses = new Metric({
+        namespace,
+        metricName: successMetricName,
+        period: Duration.days(1),
+        statistic: "Sum"
+    });
+    const unestablishedAlarm = new Alarm(scope, "ClickHouseBackupUnestablishedAlarm", {
+        alarmDescription: buildAlarmDescription(`No ClickHouse backup success in the trailing ${BACKUP_HEARTBEAT_ARMING_DAYS} days — expected (and harmless) on stacks younger than one backup cycle; arms ClickHouseBackupHeartbeatAlarm once the first success lands. No actions attached`, applicationId),
+        metric: dailySuccesses,
+        threshold: 1,
+        evaluationPeriods: BACKUP_HEARTBEAT_ARMING_DAYS,
+        datapointsToAlarm: BACKUP_HEARTBEAT_ARMING_DAYS,
+        comparisonOperator: ComparisonOperator.LESS_THAN_THRESHOLD,
+        treatMissingData: TreatMissingData.BREACHING
+    });
+    alarms.push(unestablishedAlarm);
+    const heartbeat = new CompositeAlarm(scope, "ClickHouseBackupHeartbeatAlarm", {
+        alarmDescription: buildAlarmDescription(`ClickHouse backups have stopped succeeding: no success in the trailing ${effectiveWindowHours}h on a stack where backups previously succeeded — check the backup scheduled task's ECS run history, then the backup task log group, then the instance role's S3 grants`, applicationId),
+        alarmRule: AlarmRule.allOf(AlarmRule.fromAlarm(absenceAlarm, AlarmState.ALARM), AlarmRule.fromAlarm(unestablishedAlarm, AlarmState.OK)),
+        actionsSuppressor: unestablishedAlarm,
+        actionsSuppressorWaitPeriod: BACKUP_HEARTBEAT_SUPPRESSOR_WAIT,
+        actionsSuppressorExtensionPeriod: BACKUP_HEARTBEAT_SUPPRESSOR_EXTENSION
+    });
+    heartbeat.addAlarmAction(snsAction);
+    heartbeat.addOkAction(snsAction);
+    tagAlarmsWithApplicationId([heartbeat], applicationId);
+}

package/dist/lib/resources/aws/monitoring/ecsAlarms.d.ts

@@ -4,10 +4,18 @@ import { type IApplicationTargetGroup } from "aws-cdk-lib/aws-elasticloadbalanci
 import type { ITopic } from "aws-cdk-lib/aws-sns";
 import type { Construct } from "constructs";
 export interface EcsServiceAlarmThresholds {
-    cpuThreshold?: number;
-    memoryThreshold?: number;
+    /** CPU utilisation % threshold. `false` disables the CPU alarm entirely —
+     *  for services whose CPU signal is owned elsewhere (e.g. the ClickHouse
+     *  pattern alarms host CPU via AWS/EC2 and routinely pins container CPU
+     *  during merges). */
+    cpuThreshold?: number | false;
+    /** Memory utilisation % threshold. `false` disables the memory alarm. */
+    memoryThreshold?: number | false;
+    /** Minimum running tasks; `0` disables the running-tasks alarm. */
     runningTasksMinimum?: number;
-    http5xxThreshold?: number;
+    /** 5xx error-rate % threshold (ALB services only). `false` disables the
+     *  5xx alarm; the p99 response-time alarm is unaffected. */
+    http5xxThreshold?: number | false;
 }
 export interface EcsServiceAlarmsProps {
     scope: Construct;

package/dist/lib/resources/aws/monitoring/ecsAlarms.js

@@ -7,30 +7,34 @@ export function createEcsServiceAlarms(props) {
     const { scope, serviceName, service, targetGroup, config, alarmTopic, applicationId } = props;
     const alarms = [];
     const snsAction = new SnsAction(alarmTopic);
-    const cpuAlarm = new Alarm(scope, `${serviceName}CpuAlarm`, {
-        alarmDescription: buildAlarmDescription(`ECS service ${serviceName} CPU utilisation exceeds threshold`, applicationId),
-        metric: service.metricCpuUtilization({
-            period: ALARM_DEFAULTS.EVALUATION_PERIOD
-        }),
-        threshold: config.cpuThreshold ?? ALARM_DEFAULTS.ECS.CPU,
-        evaluationPeriods: 3,
-        datapointsToAlarm: 2,
-        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
-        treatMissingData: TreatMissingData.NOT_BREACHING
-    });
-    registerAlarm(cpuAlarm, snsAction, alarms);
-    const memoryAlarm = new Alarm(scope, `${serviceName}MemoryAlarm`, {
-        alarmDescription: buildAlarmDescription(`ECS service ${serviceName} memory utilisation exceeds threshold`, applicationId),
-        metric: service.metricMemoryUtilization({
-            period: ALARM_DEFAULTS.EVALUATION_PERIOD
-        }),
-        threshold: config.memoryThreshold ?? ALARM_DEFAULTS.ECS.MEMORY,
-        evaluationPeriods: 3,
-        datapointsToAlarm: 2,
-        comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
-        treatMissingData: TreatMissingData.NOT_BREACHING
-    });
-    registerAlarm(memoryAlarm, snsAction, alarms);
+    if (config.cpuThreshold !== false) {
+        const cpuAlarm = new Alarm(scope, `${serviceName}CpuAlarm`, {
+            alarmDescription: buildAlarmDescription(`ECS service ${serviceName} CPU utilisation exceeds threshold`, applicationId),
+            metric: service.metricCpuUtilization({
+                period: ALARM_DEFAULTS.EVALUATION_PERIOD
+            }),
+            threshold: config.cpuThreshold ?? ALARM_DEFAULTS.ECS.CPU,
+            evaluationPeriods: 3,
+            datapointsToAlarm: 2,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(cpuAlarm, snsAction, alarms);
+    }
+    if (config.memoryThreshold !== false) {
+        const memoryAlarm = new Alarm(scope, `${serviceName}MemoryAlarm`, {
+            alarmDescription: buildAlarmDescription(`ECS service ${serviceName} memory utilisation exceeds threshold`, applicationId),
+            metric: service.metricMemoryUtilization({
+                period: ALARM_DEFAULTS.EVALUATION_PERIOD
+            }),
+            threshold: config.memoryThreshold ?? ALARM_DEFAULTS.ECS.MEMORY,
+            evaluationPeriods: 3,
+            datapointsToAlarm: 2,
+            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+            treatMissingData: TreatMissingData.NOT_BREACHING
+        });
+        registerAlarm(memoryAlarm, snsAction, alarms);
+    }
     const runningMin = config.runningTasksMinimum ?? ALARM_DEFAULTS.ECS.RUNNING_TASKS_MIN;
     if (runningMin > 0) {
         const runningTasksAlarm = new Alarm(scope, `${serviceName}RunningTasksAlarm`, {
@@ -53,25 +57,27 @@ export function createEcsServiceAlarms(props) {
     }
     // ALB-based alarms only when a target group is provided
     if (targetGroup) {
-        const http5xxThreshold = config.http5xxThreshold ?? ALARM_DEFAULTS.ALB.HTTP_5XX_PERCENT;
-        const http5xxAlarm = new Alarm(scope, `${serviceName}Http5xxAlarm`, {
-            alarmDescription: buildAlarmDescription(`ECS service ${serviceName} 5xx error rate exceeds ${http5xxThreshold}%`, applicationId),
-            metric: new MathExpression({
-                expression: "(errors / requests) * 100",
-                label: "5xx Error Rate %",
-                period: ALARM_DEFAULTS.EVALUATION_PERIOD,
-                usingMetrics: {
-                    errors: targetGroup.metrics.httpCodeTarget(HttpCodeTarget.TARGET_5XX_COUNT, { statistic: "Sum" }),
-                    requests: targetGroup.metrics.requestCount({ statistic: "Sum" })
-                }
-            }),
-            threshold: http5xxThreshold,
-            evaluationPeriods: 2,
-            datapointsToAlarm: 2,
-            comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
-            treatMissingData: TreatMissingData.NOT_BREACHING
-        });
-        registerAlarm(http5xxAlarm, snsAction, alarms);
+        if (config.http5xxThreshold !== false) {
+            const http5xxThreshold = config.http5xxThreshold ?? ALARM_DEFAULTS.ALB.HTTP_5XX_PERCENT;
+            const http5xxAlarm = new Alarm(scope, `${serviceName}Http5xxAlarm`, {
+                alarmDescription: buildAlarmDescription(`ECS service ${serviceName} 5xx error rate exceeds ${http5xxThreshold}%`, applicationId),
+                metric: new MathExpression({
+                    expression: "(errors / requests) * 100",
+                    label: "5xx Error Rate %",
+                    period: ALARM_DEFAULTS.EVALUATION_PERIOD,
+                    usingMetrics: {
+                        errors: targetGroup.metrics.httpCodeTarget(HttpCodeTarget.TARGET_5XX_COUNT, { statistic: "Sum" }),
+                        requests: targetGroup.metrics.requestCount({ statistic: "Sum" })
+                    }
+                }),
+                threshold: http5xxThreshold,
+                evaluationPeriods: 2,
+                datapointsToAlarm: 2,
+                comparisonOperator: ComparisonOperator.GREATER_THAN_THRESHOLD,
+                treatMissingData: TreatMissingData.NOT_BREACHING
+            });
+            registerAlarm(http5xxAlarm, snsAction, alarms);
+        }
         const p99Alarm = new Alarm(scope, `${serviceName}P99ResponseTimeAlarm`, {
             alarmDescription: buildAlarmDescription(`ECS service ${serviceName} p99 response time exceeds threshold`, applicationId),
             metric: targetGroup.metrics.targetResponseTime({

package/dist/lib/resources/aws/monitoring/index.d.ts

@@ -4,8 +4,8 @@ export { createRdsAlarms, type RdsAlarmThresholds, type RdsAlarmsProps } from ".
 export { createLambdaAlarms, type LambdaAlarmThresholds, type LambdaAlarmsProps } from "./lambdaAlarms.js";
 export { createScheduleAlarms, type ScheduleAlarmThresholds, type CreateScheduleAlarmsProps } from "./scheduleAlarms.js";
 export { createSqsDlqAlarms, type SqsAlarmThresholds, type SqsDlqAlarmsProps } from "./sqsAlarms.js";
-export { createClickHouseAlarms, type ClickHouseAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";
+export { createClickHouseAlarms, validateClickHouseAlarmThresholds, BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS, BACKUP_HEARTBEAT_MAX_WINDOW_HOURS, type ClickHouseAlarmThresholds, type ClickHouseHostAlarmThresholds, type ClickHouseAlarmsProps } from "./clickhouseAlarms.js";
 export { createBuildkiteAlarms, type BuildkiteAlarmsProps } from "./buildkiteAlarms.js";
 export { createLogPatternAlarms, type LogPatternAlarmSpec, type LogPatternAlarmsProps } from "./logPatternAlarms.js";
 export { createEcsTaskStopWatchdog, ABNORMAL_TASK_STOP_CODES, TASK_STOP_METRIC_NAME, type EcsTaskStopWatchdog, type EcsTaskStopWatchdogProps } from "./ecsTaskStopWatchdog.js";
-export { METRIC_NAMESPACE, type MetricNamespace } from "./metricNamespaces.js";
+export { METRIC_NAMESPACE, stackScopedMetricNamespace, type MetricNamespace } from "./metricNamespaces.js";

package/dist/lib/resources/aws/monitoring/index.js

@@ -4,8 +4,8 @@ export { createRdsAlarms } from "./rdsAlarms.js";
 export { createLambdaAlarms } from "./lambdaAlarms.js";
 export { createScheduleAlarms } from "./scheduleAlarms.js";
 export { createSqsDlqAlarms } from "./sqsAlarms.js";
-export { createClickHouseAlarms } from "./clickhouseAlarms.js";
+export { createClickHouseAlarms, validateClickHouseAlarmThresholds, BACKUP_HEARTBEAT_DEFAULT_WINDOW_HOURS, BACKUP_HEARTBEAT_MAX_WINDOW_HOURS } from "./clickhouseAlarms.js";
 export { createBuildkiteAlarms } from "./buildkiteAlarms.js";
 export { createLogPatternAlarms } from "./logPatternAlarms.js";
 export { createEcsTaskStopWatchdog, ABNORMAL_TASK_STOP_CODES, TASK_STOP_METRIC_NAME } from "./ecsTaskStopWatchdog.js";
-export { METRIC_NAMESPACE } from "./metricNamespaces.js";
+export { METRIC_NAMESPACE, stackScopedMetricNamespace } from "./metricNamespaces.js";

package/dist/lib/resources/aws/monitoring/metricNamespaces.d.ts

@@ -12,3 +12,16 @@ export declare const METRIC_NAMESPACE: {
     readonly WEBAPP: "Fjall/WebApp";
 };
 export type MetricNamespace = (typeof METRIC_NAMESPACE)[keyof typeof METRIC_NAMESPACE];
+/**
+ * Scope a metric namespace to the deploying stack (`<base>/<stack name>`).
+ *
+ * Log-pattern metric streams carry no dimensions — CloudWatch metric-filter
+ * dimensions can only reference fields extracted from the log event, and
+ * non-JSON logs (ClickHouse server logs) have no field carrying stack
+ * identity — so two stacks in one account+region publishing under a bare
+ * namespace+name share ONE metric stream and each stack's alarm fires on the
+ * union of both stacks' log lines. The stack name is the per-instance
+ * discriminator (two databases in one stack is already a synth error via the
+ * EC2 capacity slot).
+ */
+export declare function stackScopedMetricNamespace(base: MetricNamespace): string;

package/dist/lib/resources/aws/monitoring/metricNamespaces.js

@@ -1,3 +1,4 @@
+import { Aws } from "aws-cdk-lib";
 /**
  * Single source of truth for Fjall CloudWatch metric namespaces.
  *
@@ -11,3 +12,18 @@ export const METRIC_NAMESPACE = {
     ECS: "Fjall/ECS",
     WEBAPP: "Fjall/WebApp"
 };
+/**
+ * Scope a metric namespace to the deploying stack (`<base>/<stack name>`).
+ *
+ * Log-pattern metric streams carry no dimensions — CloudWatch metric-filter
+ * dimensions can only reference fields extracted from the log event, and
+ * non-JSON logs (ClickHouse server logs) have no field carrying stack
+ * identity — so two stacks in one account+region publishing under a bare
+ * namespace+name share ONE metric stream and each stack's alarm fires on the
+ * union of both stacks' log lines. The stack name is the per-instance
+ * discriminator (two databases in one stack is already a synth error via the
+ * EC2 capacity slot).
+ */
+export function stackScopedMetricNamespace(base) {
+    return `${base}/${Aws.STACK_NAME}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/components-infrastructure",
-  "version": "12.0.0",
+  "version": "12.1.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -80,8 +80,8 @@
   },
   "dependencies": {
     "@aws-sdk/client-organizations": "^3.1098.0",
-    "@fjall/generator": "^12.0.0",
-    "@fjall/util": "^12.0.0",
+    "@fjall/generator": "^12.1.1",
+    "@fjall/util": "^12.1.1",
     "constructs": "^10.7.2"
   },
   "overrides": {
@@ -89,7 +89,7 @@
   },
   "peerDependencies": {
     "aws-cdk": "^2.1134.0",
-    "aws-cdk-lib": "^2.263.0",
+    "aws-cdk-lib": "^2.265.0",
     "constructs": "^10.7.2"
   },
   "engines": {