@oneuptime/common 12.0.1 → 12.0.3

package/Server/Services/CephClusterService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/CephCluster";
 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";
@@ -181,7 +182,6 @@ export class Service extends DatabaseService<Model> {
       capacityUsedPercent?: number | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = clusterId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -200,83 +200,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?.cephVersion) {
-      data.cephVersion = extra.cephVersion;
+      metadata.cephVersion = extra.cephVersion;
     }
     if (extra?.fsid) {
-      data.fsid = extra.fsid;
+      metadata.fsid = extra.fsid;
     }
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
     /*
      * Counts and health: 0 is a legitimate value (healthStatus 0 = OK,
      * osdUpCount 0 = every OSD down) — gate on undefined, not falsiness.
      */
     if (extra?.monCount !== undefined) {
-      data.monCount = extra.monCount;
+      metadata.monCount = extra.monCount;
     }
     if (extra?.osdCount !== undefined) {
-      data.osdCount = extra.osdCount;
+      metadata.osdCount = extra.osdCount;
     }
     if (extra?.osdUpCount !== undefined) {
-      data.osdUpCount = extra.osdUpCount;
+      metadata.osdUpCount = extra.osdUpCount;
     }
     if (extra?.osdInCount !== undefined) {
-      data.osdInCount = extra.osdInCount;
+      metadata.osdInCount = extra.osdInCount;
     }
     if (extra?.poolCount !== undefined) {
-      data.poolCount = extra.poolCount;
+      metadata.poolCount = extra.poolCount;
     }
     if (extra?.healthStatus !== undefined) {
-      data.healthStatus = extra.healthStatus;
+      metadata.healthStatus = extra.healthStatus;
     }
     if (extra?.capacityUsedPercent !== undefined) {
-      data.capacityUsedPercent = extra.capacityUsedPercent;
+      metadata.capacityUsedPercent = extra.capacityUsedPercent;
     }
 
     /*
-     * 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: `ceph cluster ${clusterId.toString()}`,
     });
   }
 

package/Server/Services/CephResourceService.ts

@@ -1,8 +1,10 @@
 import DatabaseService from "./DatabaseService";
 import Model from "../../Models/DatabaseModels/CephResource";
 import CaptureSpan from "../Utils/Telemetry/CaptureSpan";
+import ColumnLength from "../../Types/Database/ColumnLength";
 import ObjectID from "../../Types/ObjectID";
 import OneUptimeDate from "../../Types/Date";
+import { truncateShortText } from "../Utils/Database/TruncateColumnValue";
 import logger from "../Utils/Logger";
 
 /*
@@ -86,6 +88,26 @@ const UPSERT_COLUMNS: Array<string> = [
   "version",
 ];
 
+/*
+ * CephResource's text columns are all ShortText (100 chars). 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 daemon can never drop
+ * the rest of the scrape.
+ */
+function sanitizeResource(r: ParsedCephResource): ParsedCephResource {
+  return {
+    ...r,
+    kind: truncateShortText(r.kind),
+    externalId: truncateShortText(r.externalId),
+    name: truncateShortText(r.name),
+    hostname: truncateShortText(r.hostname),
+    daemonVersion: truncateShortText(r.daemonVersion),
+    deviceClass: truncateShortText(r.deviceClass),
+  };
+}
+
 export class Service extends DatabaseService<Model> {
   public constructor() {
     super(Model);
@@ -112,9 +134,21 @@ export class Service extends DatabaseService<Model> {
       return;
     }
 
+    const resources: Array<ParsedCephResource> = data.resources.map(
+      (r: ParsedCephResource) => {
+        const sanitized: ParsedCephResource = sanitizeResource(r);
+        if (sanitized.externalId !== r.externalId) {
+          logger.warn(
+            `CephResource externalId exceeds ${ColumnLength.ShortText} chars; truncated to "${sanitized.externalId}" (cluster ${data.cephClusterId.toString()}).`,
+          );
+        }
+        return sanitized;
+      },
+    );
+
     // Chunk to keep individual statement parameter counts reasonable.
-    for (let i: number = 0; i < data.resources.length; i += UPSERT_BATCH_SIZE) {
-      const chunk: Array<ParsedCephResource> = data.resources.slice(
+    for (let i: number = 0; i < resources.length; i += UPSERT_BATCH_SIZE) {
+      const chunk: Array<ParsedCephResource> = resources.slice(
         i,
         i + UPSERT_BATCH_SIZE,
       );
@@ -218,9 +252,14 @@ export class Service extends DatabaseService<Model> {
         valueFragments.push(
           `($${paramIndex++}, $${paramIndex++}, $${paramIndex++}::bigint, $${paramIndex++}::bigint, $${paramIndex++}::numeric, $${paramIndex++}::numeric, $${paramIndex++}::integer, $${paramIndex++}::bigint, $${paramIndex++}::bigint, $${paramIndex++}::bigint, $${paramIndex++}::bigint, $${paramIndex++}::bigint, $${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),
           bigintOrNull(m.statBytes),
           bigintOrNull(m.statBytesUsed),
           m.applyLatencyMs !== null && m.applyLatencyMs !== undefined

package/Server/Services/CloudResourceService.ts

@@ -2,6 +2,7 @@ import DatabaseService from "./DatabaseService";
 import Model from "../../Models/DatabaseModels/CloudResource";
 import Label from "../../Models/DatabaseModels/Label";
 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";
@@ -154,7 +155,6 @@ export class Service extends DatabaseService<Model> {
       runtimeVersion?: string | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = cloudResourceId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -170,70 +170,52 @@ 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;
     }
     if (extra?.cloudPlatform) {
-      data.cloudPlatform = extra.cloudPlatform;
+      metadata.cloudPlatform = extra.cloudPlatform;
     }
     if (extra?.cloudProvider) {
-      data.cloudProvider = extra.cloudProvider;
+      metadata.cloudProvider = extra.cloudProvider;
     }
     if (extra?.cloudRegion) {
-      data.cloudRegion = extra.cloudRegion;
+      metadata.cloudRegion = extra.cloudRegion;
     }
     if (extra?.cloudAccountId) {
-      data.cloudAccountId = extra.cloudAccountId;
+      metadata.cloudAccountId = extra.cloudAccountId;
     }
     if (extra?.runtimeName) {
-      data.runtimeName = extra.runtimeName;
+      metadata.runtimeName = extra.runtimeName;
     }
     if (extra?.runtimeVersion) {
-      data.runtimeVersion = extra.runtimeVersion;
+      metadata.runtimeVersion = extra.runtimeVersion;
     }
 
     /*
-     * 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: cloudResourceId,
-      data: data,
+      cacheNamespace: LAST_SEEN_CACHE_NAMESPACE,
+      throttleInSeconds: LAST_SEEN_THROTTLE_SECONDS,
+      liveness: liveness,
+      metadata: metadata,
+      fingerprint: extrasFingerprint,
+      describe: `cloud resource ${cloudResourceId.toString()}`,
     });
   }
 

package/Server/Services/DatabaseService.ts

@@ -1046,6 +1046,61 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
     return data;
   }
 
+  /*
+   * Clamp string values to the max length their column declares, instead of
+   * rejecting the whole write the way checkMaxLengthOfFields does.
+   *
+   * For machine-stamped metadata harvested from OpenTelemetry resource
+   * attributes there is no user to show a validation error to, and the
+   * write these values ride along with also carries liveness columns
+   * (lastSeenAt / otelCollectorStatus). Letting one oversized optional
+   * attribute abort that statement strands a healthy resource as
+   * "disconnected" — the failure mode in issue #3006. A clipped display
+   * string is strictly better than a lost heartbeat.
+   *
+   * Only string values on columns with a declared max length are touched;
+   * `text` columns (VeryLongText and friends) declare none and pass
+   * through untouched, as do numbers, dates and ObjectIDs.
+   *
+   * The raw, hook-free write paths (updateColumnsByIdWithoutHooks and
+   * atomicAddToColumnsByIdWithoutHooks) call this themselves, so callers do
+   * NOT need to — and must not rely on being able to skip it by writing a
+   * new raw path of their own. It is NOT a substitute for sizing a column
+   * correctly: if a field is legitimately long, widen the column.
+   */
+  public truncateStringColumnsToMaxLength(
+    data: Record<string, unknown>,
+  ): Record<string, unknown> {
+    for (const column of Object.keys(data)) {
+      const value: unknown = data[column];
+
+      if (typeof value !== "string" || value.length === 0) {
+        continue;
+      }
+
+      /*
+       * Returns undefined for an unmapped column name despite its type —
+       * leave those alone and let the write path complain about them.
+       */
+      const metadata: TableColumnMetadata | undefined =
+        this.model.getTableColumnMetadata(column);
+
+      if (!metadata?.type) {
+        continue;
+      }
+
+      const maxLength: number | undefined = getMaxLengthFromTableColumnType(
+        metadata.type,
+      );
+
+      if (maxLength !== undefined && value.length > maxLength) {
+        data[column] = value.substring(0, maxLength);
+      }
+    }
+
+    return data;
+  }
+
   private async checkTotalItemsBy(
     createdBy: CreateBy<TBaseModel>,
   ): Promise<void> {
@@ -2248,6 +2303,17 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
    * the caller), and every value is bound as a parameter, so this is not an
    * injection surface. Use ONLY for trusted, internal, side-effect-free
    * column writes where the full pipeline is pure overhead.
+   *
+   * Oversized strings are CLAMPED here (truncateStringColumnsToMaxLength)
+   * rather than rejected. Skipping the hooks also skips
+   * checkMaxLengthOfFields, so before this an over-long value reached
+   * Postgres raw and failed the ENTIRE statement — including whatever else
+   * rode along with it. On the telemetry liveness writes that is fatal: one
+   * over-long OpenTelemetry resource attribute took `lastSeenAt` down with
+   * it and markDisconnected* stranded a healthy resource as "disconnected"
+   * 15 minutes later while its data kept arriving (issue #3006). Clamping
+   * in here, at the choke point, is what makes that unforgettable — every
+   * caller of this path gets it, including ones not written yet.
    */
   @CaptureSpan()
   public async updateColumnsByIdWithoutHooks(input: {
@@ -2273,9 +2339,16 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
     const setClauses: Array<string> = [];
     const params: Array<unknown> = [];
 
-    for (const [propertyName, value] of Object.entries(
-      input.data as ObjectLiteral,
-    )) {
+    /*
+     * Clamp on a shallow COPY: callers must not have their own object
+     * mutated behind their back (a liveness-only retry, for instance,
+     * rebuilds its payload from the same source values).
+     */
+    const data: ObjectLiteral = this.truncateStringColumnsToMaxLength({
+      ...(input.data as ObjectLiteral),
+    });
+
+    for (const [propertyName, value] of Object.entries(data)) {
       const column: ColumnMetadata | undefined =
         metadata.findColumnWithPropertyName(propertyName);
       if (!column) {
@@ -2327,6 +2400,117 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
     await repository.manager.query(sql, params);
   }
 
+  /*
+   * Same single-statement, hook-free, no-version-bump write as
+   * `updateColumnsByIdWithoutHooks`, except it YIELDS instead of queueing:
+   * if another transaction already holds the row's lock, this write is
+   * abandoned and the method returns false. It never waits.
+   *
+   * Why this exists. A single-statement UPDATE holds its row lock for a very
+   * short time, but "short" does not mean "safe" once the arrival rate on ONE
+   * row exceeds the service rate. Postgres queues lock waiters strictly, so
+   * every waiter pins a backend for the sum of everyone ahead of it — the
+   * classic convoy. In the outage this was written for, ~25K concurrent
+   * ingest jobs across 100 worker pods funnelled onto ~2,300 Service rows and
+   * produced 1,017 active connections with 892 of them parked on row locks;
+   * the tail had been waiting 3.7 hours. Nothing about that is fixable by
+   * making the statement faster, and no Postgres tier changes it: the queue
+   * is the bug.
+   *
+   * `FOR UPDATE SKIP LOCKED` inverts it. A contended writer does zero work
+   * and returns immediately, so the number of backends blocked on any single
+   * row is capped at ONE no matter how many workers arrive together. The
+   * convoy cannot form — and cannot form even if every upstream throttle
+   * fails open at once (Redis down, fence bug, cache flush). That is the
+   * point: this is the structural backstop underneath the throttles, not a
+   * second copy of them.
+   *
+   * Use ONLY where losing the write is harmless because a concurrent writer
+   * is writing the same thing — liveness timestamps and other idempotent
+   * bookkeeping, whose contended value is by construction the value the
+   * winner is already storing. It is the WRONG primitive for a write carrying
+   * information the winner does not have (a changed attribute); for those the
+   * caller must re-attempt, and `false` is the signal to do it. Returning a
+   * boolean rather than swallowing the skip is deliberate: a silent drop here
+   * would be indistinguishable from a successful write at the call site,
+   * which is exactly how a "reliable" heartbeat quietly stops beating.
+   *
+   * Returns true when the row was updated, false when it was locked (or no
+   * longer exists).
+   */
+  @CaptureSpan()
+  public async updateColumnsByIdIfUnlockedWithoutHooks(input: {
+    id: ObjectID;
+    data: PartialEntity<TBaseModel>;
+    skipUpdateDateColumn?: boolean;
+  }): Promise<boolean> {
+    if (!input.id) {
+      throw new BadDataException("id is required");
+    }
+
+    const repository: Repository<TBaseModel> = this.getRepository();
+    const metadata: EntityMetadata = repository.metadata;
+    const driver: Driver = repository.manager.connection.driver;
+
+    const setClauses: Array<string> = [];
+    const params: Array<unknown> = [];
+
+    // Clamp on a shallow COPY — see updateColumnsByIdWithoutHooks.
+    const data: ObjectLiteral = this.truncateStringColumnsToMaxLength({
+      ...(input.data as ObjectLiteral),
+    });
+
+    for (const [propertyName, value] of Object.entries(data)) {
+      const column: ColumnMetadata | undefined =
+        metadata.findColumnWithPropertyName(propertyName);
+      if (!column) {
+        throw new BadDataException(
+          `updateColumnsByIdIfUnlockedWithoutHooks: unknown column "${propertyName}" on "${metadata.tableName}"`,
+        );
+      }
+      if (typeof value === "function") {
+        throw new BadDataException(
+          `updateColumnsByIdIfUnlockedWithoutHooks: SQL-expression values are not supported (column "${propertyName}"); pass a literal value.`,
+        );
+      }
+      params.push(driver.preparePersistentValue(value, column));
+      setClauses.push(`"${column.databaseName}" = $${params.length}`);
+    }
+
+    if (setClauses.length === 0) {
+      return false;
+    }
+
+    if (metadata.updateDateColumn && !input.skipUpdateDateColumn) {
+      setClauses.push(
+        `"${metadata.updateDateColumn.databaseName}" = CURRENT_TIMESTAMP`,
+      );
+    }
+
+    const primaryColumnName: string =
+      metadata.primaryColumns[0]?.databaseName || "_id";
+    params.push(input.id.toString());
+
+    /*
+     * The lock is taken by the sub-SELECT and inherited by the UPDATE within
+     * the same implicit transaction, so the outer write never blocks either.
+     * RETURNING is how the affected-row count comes back: TypeORM's `query()`
+     * surfaces the driver's rows and a bare UPDATE returns none, so without it
+     * a skipped write is indistinguishable from an applied one.
+     */
+    const sql: string = `UPDATE "${metadata.tableName}" SET ${setClauses.join(
+      ", ",
+    )} WHERE "${primaryColumnName}" IN (SELECT "${primaryColumnName}" FROM "${
+      metadata.tableName
+    }" WHERE "${primaryColumnName}" = $${
+      params.length
+    } FOR UPDATE SKIP LOCKED) RETURNING "${primaryColumnName}"`;
+
+    const result: unknown = await repository.manager.query(sql, params);
+
+    return Array.isArray(result) && result.length > 0;
+  }
+
   /*
    * Atomically add to numeric columns and set literal columns for one row,
    * in a SINGLE auto-committed UPDATE, with no hooks and no `version` bump.
@@ -2347,6 +2531,11 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
    * caller) and every value is bound as a parameter, so this is not an
    * injection surface. Use ONLY for trusted, internal, side-effect-free
    * column writes.
+   *
+   * `set` values are clamped to their column widths for the same reason
+   * updateColumnsByIdWithoutHooks clamps: this path also skips
+   * checkMaxLengthOfFields, and an over-long string here would abort the
+   * counter increments riding in the same statement.
    */
   @CaptureSpan()
   public async atomicAddToColumnsByIdWithoutHooks(input: {
@@ -2393,9 +2582,12 @@ class DatabaseService<TBaseModel extends BaseModel> extends BaseService {
       setClauses.push(`${quoted} = COALESCE(${quoted}, 0) + $${params.length}`);
     }
 
-    for (const [propertyName, value] of Object.entries(
-      (input.set || {}) as ObjectLiteral,
-    )) {
+    // Shallow copy — never mutate the caller's object. See the clamp note above.
+    const set: ObjectLiteral = this.truncateStringColumnsToMaxLength({
+      ...((input.set || {}) as ObjectLiteral),
+    });
+
+    for (const [propertyName, value] of Object.entries(set)) {
       if (typeof value === "function") {
         throw new BadDataException(
           `atomicAddToColumnsByIdWithoutHooks: SQL-expression values are not supported (column "${propertyName}"); pass a literal value.`,

package/Server/Services/DockerHostService.ts

@@ -5,6 +5,7 @@ import Model from "../../Models/DatabaseModels/DockerHost";
 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";
@@ -180,7 +181,6 @@ export class Service extends DatabaseService<Model> {
       agentVersion?: string | undefined;
     },
   ): Promise<void> {
-    const cacheKey: string = hostId.toString();
     const extrasFingerprint: string = crypto
       .createHash("sha1")
       .update(
@@ -192,58 +192,40 @@ 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?.osType) {
-      data.osType = extra.osType;
+      metadata.osType = extra.osType;
     }
     if (extra?.osVersion) {
-      data.osVersion = extra.osVersion;
+      metadata.osVersion = extra.osVersion;
     }
     if (extra?.agentVersion) {
-      data.agentVersion = extra.agentVersion;
+      metadata.agentVersion = extra.agentVersion;
     }
 
     /*
-     * 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: `docker host ${hostId.toString()}`,
     });
   }