@rebasepro/server 0.24.0 → 0.24.1-canary.g19596ef

package/dist/metrics/pool-wait.d.ts

@@ -0,0 +1,50 @@
+/**
+ * How long queries wait for a pooled database connection.
+ *
+ * A write holds its connection — and its transaction, and the locks it has
+ * taken — for as long as its callbacks run: `beforeSave` runs after the
+ * transaction has begun, `afterSave` before it commits. Callbacks that await
+ * something slow therefore take connections out of the pool for that long, and
+ * once enough of them run at once every other request queues for one. Measured
+ * with the default pool of 20: 25 concurrent saves whose `beforeSave` awaited
+ * 300 ms made an unrelated one-row read wait 290 ms for a connection.
+ *
+ * Nothing else shows that queue. Request latency rises, but so it does for a
+ * slow query; this histogram says how much of a request was spent waiting for
+ * a connection at all. Near zero is a healthy pool.
+ *
+ * @module
+ */
+import { type MetricsRegistry } from "./index.js";
+/** `pg.Pool`'s callback form of `connect`, which `pool.query` uses internally. */
+type ConnectCallback = (err: Error | undefined, client: unknown, done: (release?: unknown) => void) => void;
+/**
+ * `connect` as a `pg.Pool` has it: a promise without a callback, the callback
+ * with one. Both are timed — transactions check out with the first,
+ * `pool.query` with the second.
+ */
+export type PoolConnect = (callback?: ConnectCallback) => Promise<unknown> | void;
+/**
+ * Time every checkout from `pool`, from the call to the moment a connection is
+ * handed over, and report it to `record` in milliseconds. A failed checkout is
+ * not recorded: it is an error, not a wait.
+ *
+ * Wraps `connect` on this pool object only. `false` when the pool has no
+ * `connect` to time (a driver that is not pool-based) or is timed already.
+ */
+export declare function timePoolCheckouts(pool: {
+    connect?: PoolConnect;
+}, record: (waitMs: number) => void): boolean;
+/**
+ * Time the checkouts of every pool-based data source into `registry`'s
+ * {@link DB_POOL_WAIT_METRIC} histogram, labelled by the source's key.
+ */
+export declare function recordPoolWaits(registry: MetricsRegistry, sources: readonly {
+    key: string;
+    connection: {
+        pool?: {
+            connect?: PoolConnect;
+        };
+    };
+}[]): void;
+export {};