@oneuptime/common 12.0.1 → 12.0.3

package/Server/Services/DockerResourceService.ts

@@ -1,9 +1,14 @@
 import DatabaseService from "./DatabaseService";
 import Model from "../../Models/DatabaseModels/DockerResource";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ColumnLength from "../../Types/Database/ColumnLength";
 import ObjectID from "../../Types/ObjectID";
 import OneUptimeDate from "../../Types/Date";
 import { JSONObject } from "../../Types/JSON";
+import {
+  truncateLongText,
+  truncateShortText,
+} from "../Utils/Database/TruncateColumnValue";
 import logger from "../Utils/Logger";
 
 /*
@@ -56,6 +61,35 @@ export interface DockerHostInventoryCounts {
 const UPSERT_BATCH_SIZE: number = 500;
 const STALE_DELETE_WARN_THRESHOLD: number = 100;
 
+/*
+ * DockerResource's text columns are bounded varchars — name / imageName
+ * at 500 chars, kind / containerId / state at 100. These bulk paths go
+ * through manager.query(), which skips the length validation
+ * DatabaseService applies to ordinary writes, so a single oversized
+ * value aborts the whole 500-row INSERT chunk it rides in. Clamp per
+ * value instead, so one pathological container can never drop the rest.
+ */
+function sanitizeContainer(c: ParsedDockerContainer): ParsedDockerContainer {
+  return {
+    ...c,
+    containerName: truncateLongText(c.containerName),
+    containerId: truncateShortText(c.containerId),
+    imageName: truncateLongText(c.imageName),
+    state: truncateShortText(c.state),
+  };
+}
+
+function sanitizeResource(r: ParsedDockerResource): ParsedDockerResource {
+  return {
+    ...r,
+    kind: truncateShortText(r.kind),
+    name: truncateLongText(r.name),
+    containerId: truncateShortText(r.containerId),
+    imageName: truncateLongText(r.imageName),
+    state: truncateShortText(r.state),
+  };
+}
+
 export class Service extends DatabaseService<Model> {
   public constructor() {
     super(Model);
@@ -83,12 +117,20 @@ export class Service extends DatabaseService<Model> {
       return;
     }
 
-    for (
-      let i: number = 0;
-      i < data.containers.length;
-      i += UPSERT_BATCH_SIZE
-    ) {
-      const chunk: Array<ParsedDockerContainer> = data.containers.slice(
+    const containers: Array<ParsedDockerContainer> = data.containers.map(
+      (c: ParsedDockerContainer) => {
+        const sanitized: ParsedDockerContainer = sanitizeContainer(c);
+        if (sanitized.containerName !== c.containerName) {
+          logger.warn(
+            `DockerResource container name exceeds ${ColumnLength.LongText} chars; truncated to "${sanitized.containerName}" (host ${data.dockerHostId.toString()}).`,
+          );
+        }
+        return sanitized;
+      },
+    );
+
+    for (let i: number = 0; i < containers.length; i += UPSERT_BATCH_SIZE) {
+      const chunk: Array<ParsedDockerContainer> = containers.slice(
         i,
         i + UPSERT_BATCH_SIZE,
       );
@@ -164,8 +206,20 @@ export class Service extends DatabaseService<Model> {
       return;
     }
 
-    for (let i: number = 0; i < data.resources.length; i += UPSERT_BATCH_SIZE) {
-      const chunk: Array<ParsedDockerResource> = data.resources.slice(
+    const resources: Array<ParsedDockerResource> = data.resources.map(
+      (r: ParsedDockerResource) => {
+        const sanitized: ParsedDockerResource = sanitizeResource(r);
+        if (sanitized.name !== r.name) {
+          logger.warn(
+            `DockerResource name exceeds ${ColumnLength.LongText} chars; truncated to "${sanitized.name}" (host ${data.dockerHostId.toString()}).`,
+          );
+        }
+        return sanitized;
+      },
+    );
+
+    for (let i: number = 0; i < resources.length; i += UPSERT_BATCH_SIZE) {
+      const chunk: Array<ParsedDockerResource> = resources.slice(
         i,
         i + UPSERT_BATCH_SIZE,
       );

package/Server/Services/DockerSwarmClusterService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/DockerSwarmCluster";
 import Label from "../../Models/DatabaseModels/Label";
 import { OnCreate } from "../Types/Database/Hooks";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ResourceHeartbeat from "../Utils/Telemetry/ResourceHeartbeat";
 import ObjectID from "../../Types/ObjectID";
 import QueryHelper from "../Types/Database/QueryHelper";
 import OneUptimeDate from "../../Types/Date";
@@ -182,7 +183,6 @@ export class Service extends DatabaseService<Model> {
       networkCount?: number | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = clusterId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -202,83 +202,65 @@ export class Service extends DatabaseService<Model> {
       )
       .digest("hex");
 
-    let cached: string | null = null;
-    try {
-      cached = await GlobalCache.getString(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-    } catch {
-      /*
-       * Cache unavailable — fail open and refresh lastSeenAt anyway. A
-       * cache error must never skip the DB write below, otherwise the
-       * resource is wrongly marked "disconnected" while telemetry is
-       * still flowing. Mirrors shouldRunMaintenance's fail-open stance.
-       */
-      cached = null;
-    }
-
-    if (cached === extrasFingerprint) {
-      return; // same data was written recently
-    }
-
-    try {
-      await GlobalCache.setString(
-        LAST_SEEN_CACHE_NAMESPACE,
-        cacheKey,
-        extrasFingerprint,
-        { expiresInSeconds: LAST_SEEN_THROTTLE_SECONDS },
-      );
-    } catch {
-      // Best-effort throttle write; proceed with the DB update regardless.
-    }
-
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const data: any = {
+    const liveness: any = {
       lastSeenAt: OneUptimeDate.getCurrentDate(),
       otelCollectorStatus: "connected",
     };
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const metadata: any = {};
+
     if (extra?.dockerVersion) {
-      data.dockerVersion = extra.dockerVersion;
+      metadata.dockerVersion = extra.dockerVersion;
     }
     if (extra?.swarmId) {
-      data.swarmId = extra.swarmId;
+      metadata.swarmId = extra.swarmId;
     }
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
     // Counts: 0 is a legitimate value — gate on undefined, not falsiness.
     if (extra?.nodeCount !== undefined) {
-      data.nodeCount = extra.nodeCount;
+      metadata.nodeCount = extra.nodeCount;
     }
     if (extra?.readyNodeCount !== undefined) {
-      data.readyNodeCount = extra.readyNodeCount;
+      metadata.readyNodeCount = extra.readyNodeCount;
     }
     if (extra?.managerNodeCount !== undefined) {
-      data.managerNodeCount = extra.managerNodeCount;
+      metadata.managerNodeCount = extra.managerNodeCount;
     }
     if (extra?.serviceCount !== undefined) {
-      data.serviceCount = extra.serviceCount;
+      metadata.serviceCount = extra.serviceCount;
     }
     if (extra?.taskCount !== undefined) {
-      data.taskCount = extra.taskCount;
+      metadata.taskCount = extra.taskCount;
     }
     if (extra?.runningTaskCount !== undefined) {
-      data.runningTaskCount = extra.runningTaskCount;
+      metadata.runningTaskCount = extra.runningTaskCount;
     }
     if (extra?.stackCount !== undefined) {
-      data.stackCount = extra.stackCount;
+      metadata.stackCount = extra.stackCount;
     }
     if (extra?.networkCount !== undefined) {
-      data.networkCount = extra.networkCount;
+      metadata.networkCount = extra.networkCount;
     }
 
     /*
-     * Heartbeat write: a single-statement UPDATE with no hooks and no
-     * `version` bump, avoiding the hot-row Postgres lock convoy that the
-     * full updateOneById pipeline causes. See ServiceService.updateLastSeen.
+     * One gated, non-blocking heartbeat write. The gates, the fail-open /
+     * fail-closed split and the liveness-only fallback all live in
+     * ResourceHeartbeat — see there for why this row's throttle used to
+     * provide no throttling at all.
      */
-    await this.updateColumnsByIdWithoutHooks({
+    await ResourceHeartbeat.write({
+      service: this,
       id: clusterId,
-      data: data,
+      cacheNamespace: LAST_SEEN_CACHE_NAMESPACE,
+      throttleInSeconds: LAST_SEEN_THROTTLE_SECONDS,
+      liveness: liveness,
+      metadata: metadata,
+      fingerprint: extrasFingerprint,
+      describe: `docker swarm cluster ${clusterId.toString()}`,
     });
   }
 

package/Server/Services/DockerSwarmResourceService.ts

@@ -1,9 +1,14 @@
 import DatabaseService from "./DatabaseService";
 import Model from "../../Models/DatabaseModels/DockerSwarmResource";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ColumnLength from "../../Types/Database/ColumnLength";
 import ObjectID from "../../Types/ObjectID";
 import OneUptimeDate from "../../Types/Date";
 import { JSONObject } from "../../Types/JSON";
+import {
+  truncateLongText,
+  truncateShortText,
+} from "../Utils/Database/TruncateColumnValue";
 import logger from "../Utils/Logger";
 
 /*
@@ -95,6 +100,33 @@ const UPSERT_COLUMNS: Array<string> = [
   "version",
 ];
 
+/*
+ * DockerSwarmResource's text columns are bounded varchars — image at
+ * 500 chars, everything else at 100. The bulk paths below go through
+ * manager.query(), which skips the length validation DatabaseService
+ * applies to ordinary writes, so a single oversized value aborts the
+ * whole 500-row INSERT chunk it rides in. Clamp per value instead, so
+ * one pathological task can never drop the rest of the snapshot.
+ */
+function sanitizeResource(
+  r: ParsedDockerSwarmResource,
+): ParsedDockerSwarmResource {
+  return {
+    ...r,
+    kind: truncateShortText(r.kind),
+    externalId: truncateShortText(r.externalId),
+    name: truncateShortText(r.name),
+    state: truncateShortText(r.state),
+    role: truncateShortText(r.role),
+    serviceMode: truncateShortText(r.serviceMode),
+    image: truncateLongText(r.image),
+    stackName: truncateShortText(r.stackName),
+    serviceName: truncateShortText(r.serviceName),
+    nodeHostname: truncateShortText(r.nodeHostname),
+    driver: truncateShortText(r.driver),
+  };
+}
+
 export class Service extends DatabaseService<Model> {
   public constructor() {
     super(Model);
@@ -120,8 +152,20 @@ export class Service extends DatabaseService<Model> {
       return;
     }
 
-    for (let i: number = 0; i < data.resources.length; i += UPSERT_BATCH_SIZE) {
-      const chunk: Array<ParsedDockerSwarmResource> = data.resources.slice(
+    const resources: Array<ParsedDockerSwarmResource> = data.resources.map(
+      (r: ParsedDockerSwarmResource) => {
+        const sanitized: ParsedDockerSwarmResource = sanitizeResource(r);
+        if (sanitized.externalId !== r.externalId) {
+          logger.warn(
+            `DockerSwarmResource externalId exceeds ${ColumnLength.ShortText} chars; truncated to "${sanitized.externalId}" (cluster ${data.dockerSwarmClusterId.toString()}).`,
+          );
+        }
+        return sanitized;
+      },
+    );
+
+    for (let i: number = 0; i < resources.length; i += UPSERT_BATCH_SIZE) {
+      const chunk: Array<ParsedDockerSwarmResource> = resources.slice(
         i,
         i + UPSERT_BATCH_SIZE,
       );
@@ -231,9 +275,14 @@ export class Service extends DatabaseService<Model> {
         valueFragments.push(
           `($${paramIndex++}, $${paramIndex++}, $${paramIndex++}::numeric, $${paramIndex++}::bigint, $${paramIndex++}::bigint, $${paramIndex++}::numeric, $${paramIndex++}::timestamptz)`,
         );
+        /*
+         * The identity clamps MUST match bulkUpsert's, or this mirror
+         * UPDATE would silently miss the row the upsert just wrote
+         * under the truncated externalId.
+         */
         params.push(
-          m.kind,
-          m.externalId,
+          truncateShortText(m.kind),
+          truncateShortText(m.externalId),
           m.cpuPercent !== null && m.cpuPercent !== undefined
             ? m.cpuPercent
             : null,

package/Server/Services/HostService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/Host";
 import Label from "../../Models/DatabaseModels/Label";
 import { OnCreate } from "../Types/Database/Hooks";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ResourceHeartbeat from "../Utils/Telemetry/ResourceHeartbeat";
 import ObjectID from "../../Types/ObjectID";
 import QueryHelper from "../Types/Database/QueryHelper";
 import OneUptimeDate from "../../Types/Date";
@@ -212,111 +213,93 @@ export class Service extends DatabaseService<Model> {
      * once per throttle window. If any extra value changed (e.g. cpuCores
      * updated, IP address changed), bust the cache and write immediately.
      */
-    const cacheKey: string = hostId.toString();
     const extrasFingerprint: string = this.fingerprintExtras(extra);
-    let cached: string | null = null;
-    try {
-      cached = await GlobalCache.getString(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-    } catch {
-      /*
-       * Cache unavailable — fail open and refresh lastSeenAt anyway. A
-       * cache error must never skip the DB write below, otherwise the
-       * resource is wrongly marked "disconnected" while telemetry is
-       * still flowing. Mirrors shouldRunMaintenance's fail-open stance.
-       */
-      cached = null;
-    }
-
-    if (cached === extrasFingerprint) {
-      return; // same data was written recently
-    }
-
-    try {
-      await GlobalCache.setString(
-        LAST_SEEN_CACHE_NAMESPACE,
-        cacheKey,
-        extrasFingerprint,
-        { expiresInSeconds: LAST_SEEN_THROTTLE_SECONDS },
-      );
-    } catch {
-      // Best-effort throttle write; proceed with the DB update regardless.
-    }
 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const data: any = {
+    const liveness: any = {
       lastSeenAt: OneUptimeDate.getCurrentDate(),
       otelCollectorStatus: "connected",
     };
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const metadata: any = {};
+
     if (extra?.osType) {
-      data.osType = extra.osType;
+      metadata.osType = extra.osType;
     }
     if (extra?.osVersion) {
-      data.osVersion = extra.osVersion;
+      metadata.osVersion = extra.osVersion;
     }
     if (extra?.hostId) {
-      data.hostId = extra.hostId;
+      metadata.hostId = extra.hostId;
     }
     if (extra?.hostArch) {
-      data.hostArch = extra.hostArch;
+      metadata.hostArch = extra.hostArch;
     }
     if (extra?.hostType) {
-      data.hostType = extra.hostType;
+      metadata.hostType = extra.hostType;
     }
     if (extra?.hostIpAddresses) {
-      data.hostIpAddresses = extra.hostIpAddresses;
+      metadata.hostIpAddresses = extra.hostIpAddresses;
     }
     if (extra?.cpuCores !== undefined) {
-      data.cpuCores = extra.cpuCores;
+      metadata.cpuCores = extra.cpuCores;
     }
     if (extra?.totalMemoryBytes !== undefined) {
-      data.totalMemoryBytes = extra.totalMemoryBytes;
+      metadata.totalMemoryBytes = extra.totalMemoryBytes;
     }
     if (extra?.processCount !== undefined) {
-      data.processCount = extra.processCount;
+      metadata.processCount = extra.processCount;
     }
     if (extra?.containerRuntime) {
-      data.containerRuntime = extra.containerRuntime;
+      metadata.containerRuntime = extra.containerRuntime;
     }
     if (extra?.dockerHostId) {
-      data.dockerHostId = extra.dockerHostId;
+      metadata.dockerHostId = extra.dockerHostId;
     }
     if (extra?.kubernetesClusterId) {
-      data.kubernetesClusterId = extra.kubernetesClusterId;
+      metadata.kubernetesClusterId = extra.kubernetesClusterId;
     }
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
     if (extra?.deploymentEnvironment) {
-      data.deploymentEnvironment = extra.deploymentEnvironment;
+      metadata.deploymentEnvironment = extra.deploymentEnvironment;
     }
     if (extra?.runtimeName) {
-      data.runtimeName = extra.runtimeName;
+      metadata.runtimeName = extra.runtimeName;
     }
     if (extra?.runtimeVersion) {
-      data.runtimeVersion = extra.runtimeVersion;
+      metadata.runtimeVersion = extra.runtimeVersion;
     }
     if (extra?.cloudProvider) {
-      data.cloudProvider = extra.cloudProvider;
+      metadata.cloudProvider = extra.cloudProvider;
     }
     if (extra?.cloudPlatform) {
-      data.cloudPlatform = extra.cloudPlatform;
+      metadata.cloudPlatform = extra.cloudPlatform;
     }
     if (extra?.cloudRegion) {
-      data.cloudRegion = extra.cloudRegion;
+      metadata.cloudRegion = extra.cloudRegion;
     }
     if (extra?.cloudAccountId) {
-      data.cloudAccountId = extra.cloudAccountId;
+      metadata.cloudAccountId = extra.cloudAccountId;
     }
 
     /*
-     * Heartbeat write: a single-statement UPDATE with no hooks and no
-     * `version` bump, avoiding the hot-row Postgres lock convoy that the
-     * full updateOneById pipeline causes. See ServiceService.updateLastSeen.
+     * One gated, non-blocking heartbeat write. The gates, the fail-open /
+     * fail-closed split and the liveness-only fallback all live in
+     * ResourceHeartbeat — see there for why this row's throttle used to
+     * provide no throttling at all.
      */
-    await this.updateColumnsByIdWithoutHooks({
+    await ResourceHeartbeat.write({
+      service: this,
       id: hostId,
-      data: data,
+      cacheNamespace: LAST_SEEN_CACHE_NAMESPACE,
+      throttleInSeconds: LAST_SEEN_THROTTLE_SECONDS,
+      liveness: liveness,
+      metadata: metadata,
+      fingerprint: extrasFingerprint,
+      describe: `host ${hostId.toString()}`,
     });
   }
 
@@ -349,9 +332,16 @@ export class Service extends DatabaseService<Model> {
       hostArch: extra?.hostArch ?? null,
       hostType: extra?.hostType ?? null,
       hostIpAddresses: extra?.hostIpAddresses ?? null,
-      cpuCores: extra?.cpuCores ?? null,
-      totalMemoryBytes: extra?.totalMemoryBytes ?? null,
-      processCount: extra?.processCount ?? null,
+      /*
+       * cpuCores / totalMemoryBytes / processCount are DELIBERATELY not
+       * hashed. They are per-scrape gauges, and `system.processes.count` in
+       * particular is partitioned by process.status and summed, so it changes
+       * on essentially every scrape. Hashing them made the throttle key differ
+       * every time and the 60s window never engaged — for exactly the hosts
+       * producing the most batches, which is the worst possible place to lose
+       * a throttle. The columns are still written; they simply ride along on
+       * whatever write the throttle admits rather than forcing one.
+       */
       containerRuntime: extra?.containerRuntime ?? null,
       dockerHostId: extra?.dockerHostId?.toString() ?? null,
       kubernetesClusterId: extra?.kubernetesClusterId?.toString() ?? null,

package/Server/Services/IncidentStateTimelineService.ts

@@ -25,6 +25,7 @@ import IncidentStateTimeline from "../../Models/DatabaseModels/IncidentStateTime
 import IncidentMember from "../../Models/DatabaseModels/IncidentMember";
 import IncidentRole from "../../Models/DatabaseModels/IncidentRole";
 import { IsBillingEnabled } from "../EnvironmentConfig";
+import ProjectScopedReferenceValidator from "../Utils/Database/ProjectScopedReferenceValidator";
 import logger, { LogAttributes } from "../Utils/Logger";
 import IncidentFeedService from "./IncidentFeedService";
 import AIIncidentPostmortemRunner from "../Utils/AI/SRE/IncidentPostmortemRunner";
@@ -128,6 +129,25 @@ export class Service extends DatabaseService<IncidentStateTimeline> {
         throw new BadDataException("incidentStateId is null");
       }
 
+      /*
+       * Same guard, same reason, as MonitorStatusTimelineService: an id that
+       * exists nowhere (or belongs to another project) used to reach Postgres
+       * and come back as a raw foreign key violation. The ordering check below
+       * does look the state up, but only when there IS a preceding row with an
+       * order, so the first timeline row for an incident went through unchecked.
+       */
+      await ProjectScopedReferenceValidator.validateReferencesBelongToProject({
+        projectId: createBy.props.tenantId || createBy.data.projectId,
+        subject: "incident state timeline",
+        references: [
+          {
+            modelName: "Incident State",
+            id: incidentStateId,
+            service: IncidentStateService,
+          },
+        ],
+      });
+
       // Execute queries for before and after states in parallel for better performance
       const [stateBeforeThis, stateAfterThis] = await Promise.all([
         this.findOneBy({

package/Server/Services/Index.ts

@@ -177,6 +177,7 @@ import StatusPageOwnerUserService from "./StatusPageOwnerUserService";
 import StatusPagePrivateUserService from "./StatusPagePrivateUserService";
 import StatusPagePrivateUserSessionService from "./StatusPagePrivateUserSessionService";
 import StatusPageResourceService from "./StatusPageResourceService";
+import StatusPageMonitorRuleService from "./StatusPageMonitorRuleService";
 // Status Page
 import StatusPageService from "./StatusPageService";
 import StatusPageSsoService from "./StatusPageSsoService";
@@ -438,6 +439,7 @@ const services: Array<BaseService> = [
   StatusPagePrivateUserService,
   StatusPagePrivateUserSessionService,
   StatusPageResourceService,
+  StatusPageMonitorRuleService,
   StatusPageService,
   StatusPageSsoService,
   StatusPageOidcService,

package/Server/Services/IoTDeviceService.ts

@@ -5,6 +5,7 @@ import ColumnLength from "../../Types/Database/ColumnLength";
 import ObjectID from "../../Types/ObjectID";
 import OneUptimeDate from "../../Types/Date";
 import { clampIoTTimestamp } from "../Utils/Telemetry/IoTSnapshotScan";
+import { truncateShortText } from "../Utils/Database/TruncateColumnValue";
 import logger from "../Utils/Logger";
 
 /*
@@ -59,23 +60,6 @@ export interface IoTInventorySummary {
 const UPSERT_BATCH_SIZE: number = 500;
 const STALE_DELETE_WARN_THRESHOLD: number = 100;
 
-/*
- * The identity/text columns are ShortText (100 chars). A single value
- * over the column limit fails the whole multi-row INSERT chunk it rides
- * in — truncate per value instead so one malformed device can never
- * drop the other rows of its chunk.
- */
-function truncateShortText(value: string): string;
-function truncateShortText(value: string | null): string | null;
-function truncateShortText(value: string | null): string | null {
-  if (value === null) {
-    return value;
-  }
-  return value.length > ColumnLength.ShortText
-    ? value.substring(0, ColumnLength.ShortText)
-    : value;
-}
-
 /*
  * Column order used by bulkUpsert() and its generated parameter tuples.
  * Keep this and the INSERT column list in perfect sync.

package/Server/Services/IoTFleetService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/IoTFleet";
 import Label from "../../Models/DatabaseModels/Label";
 import { OnCreate } from "../Types/Database/Hooks";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ResourceHeartbeat from "../Utils/Telemetry/ResourceHeartbeat";
 import ObjectID from "../../Types/ObjectID";
 import QueryHelper from "../Types/Database/QueryHelper";
 import OneUptimeDate from "../../Types/Date";
@@ -173,7 +174,6 @@ export class Service extends DatabaseService<Model> {
       onlineDeviceCount?: number | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = fleetId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -185,59 +185,41 @@ export class Service extends DatabaseService<Model> {
       )
       .digest("hex");
 
-    let cached: string | null = null;
-    try {
-      cached = await GlobalCache.getString(LAST_SEEN_CACHE_NAMESPACE, cacheKey);
-    } catch {
-      /*
-       * Cache unavailable — fail open and refresh lastSeenAt anyway. A
-       * cache error must never skip the DB write below, otherwise the
-       * resource is wrongly marked "disconnected" while telemetry is
-       * still flowing. Mirrors shouldRunMaintenance's fail-open stance.
-       */
-      cached = null;
-    }
-
-    if (cached === extrasFingerprint) {
-      return; // same data was written recently
-    }
-
-    try {
-      await GlobalCache.setString(
-        LAST_SEEN_CACHE_NAMESPACE,
-        cacheKey,
-        extrasFingerprint,
-        { expiresInSeconds: LAST_SEEN_THROTTLE_SECONDS },
-      );
-    } catch {
-      // Best-effort throttle write; proceed with the DB update regardless.
-    }
-
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const data: any = {
+    const liveness: any = {
       lastSeenAt: OneUptimeDate.getCurrentDate(),
       otelCollectorStatus: "connected",
     };
 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const metadata: any = {};
+
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
     // Counts: 0 is a legitimate value — gate on undefined, not falsiness.
     if (extra?.deviceCount !== undefined) {
-      data.deviceCount = extra.deviceCount;
+      metadata.deviceCount = extra.deviceCount;
     }
     if (extra?.onlineDeviceCount !== undefined) {
-      data.onlineDeviceCount = extra.onlineDeviceCount;
+      metadata.onlineDeviceCount = extra.onlineDeviceCount;
     }
 
     /*
-     * Heartbeat write: a single-statement UPDATE with no hooks and no
-     * `version` bump, avoiding the hot-row Postgres lock convoy that the
-     * full updateOneById pipeline causes. See ServiceService.updateLastSeen.
+     * One gated, non-blocking heartbeat write. The gates, the fail-open /
+     * fail-closed split and the liveness-only fallback all live in
+     * ResourceHeartbeat — see there for why this row's throttle used to
+     * provide no throttling at all.
      */
-    await this.updateColumnsByIdWithoutHooks({
+    await ResourceHeartbeat.write({
+      service: this,
       id: fleetId,
-      data: data,
+      cacheNamespace: LAST_SEEN_CACHE_NAMESPACE,
+      throttleInSeconds: LAST_SEEN_THROTTLE_SECONDS,
+      liveness: liveness,
+      metadata: metadata,
+      fingerprint: extrasFingerprint,
+      describe: `iot fleet ${fleetId.toString()}`,
     });
   }