@checkstack/healthcheck-postgres-backend 0.2.35 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @checkstack/healthcheck-postgres-backend
 
+## 0.3.1
+
+### Patch Changes
+
+- Updated dependencies [2e20792]
+- Updated dependencies [2e20792]
+  - @checkstack/backend-api@0.26.0
+  - @checkstack/healthcheck-common@1.8.1
+  - @checkstack/common@0.17.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 8cad340: Add a finer per-run transport timing breakdown to health checks.
+
+  Each run now records an optional structured `metadata.timings` (DNS, connect,
+  TLS, wait/time-to-first-byte, transfer, and a `processing` catch-all for
+  non-HTTP operation time). The run-detail view renders the phases it has, in
+  transport order, and falls back to the previous Connection + Processing split
+  for older runs that lack the finer data.
+
+  For HTTP the request is issued verbatim through `fetch` (original URL, headers,
+  and body), so request behavior is identical to a plain `fetch`. The timing is
+  measured around it: `fetch` resolves at the response headers, so wait
+  (time-to-first-byte) and transfer (body) are measured exactly on the request,
+  DNS is timed at the resolve step, and connect/TLS come from a short-lived,
+  best-effort raw `net`/`tls` probe to the same already-validated IP (the request
+  socket exposes no connect/handshake events on the Bun runtime). The probe is
+  timing-only and never fails the check. The probe validates the TLS certificate
+  (against the original hostname via SNI) like the real request does - it does not
+  disable certificate validation; an unverifiable cert simply yields no TLS-phase
+  timing rather than aborting. Other transports surface the connect and operation
+  times they already measure.
+
+  The SSRF guard now validates the resolved host (rejecting cloud-metadata /
+  link-local and operator-denied ranges) as a pre-flight check and no longer pins
+  the request to the resolved IP. Pinning rewrote the URL to the IP literal and
+  moved the host to the `Host` header, which breaks HTTP/2 origins (their
+  authority comes from the URL's `:authority`, not `Host`) - that is why real
+  hosts such as `google.com` started answering 404/429 instead of 200. The
+  pre-flight validation keeps blocking static metadata/link-local targets and
+  direct denied IP literals; the only thing dropped is DNS-rebind TOCTOU
+  protection (a narrow window that pinning closed at the cost of breaking
+  legitimate HTTP/2 requests).
+
+  The run-detail "slowest" badge no longer collides with the timing bar, and a
+  genuinely sub-millisecond phase reads as "<1 ms" instead of a bare "0 ms".
+
+### Patch Changes
+
+- 8cad340: Retune anomaly-detection defaults across every health-check strategy and the
+  hardware collector for a low-noise, problem-focused out-of-the-box experience.
+
+  The detection engine already learns a per-metric baseline, debounces with a
+  confirmation window, and applies practical-significance floors. This pass tunes
+  the per-metric **defaults** so a fresh install alerts only on genuine,
+  statistically-significant, problem-mapping deviations instead of flooding on
+  every metric that wiggles. 264 metrics were reviewed:
+
+  - **Default-disabled** the high-noise and un-baselineable classes that were
+    alerting for no good reason: raw identifiers and counts (status codes, error
+    and row counts, build counts, player and executor counts), config echoes and
+    near-constants (probe packet counts, CPU core count, total/swap memory),
+    payload-size and other run-to-run-volatile values, and deterministic values
+    like certificate days-remaining (governed by the check's own static-threshold
+    health logic, not statistics). These stay chartable and can be re-enabled per
+    field.
+  - **Hardened** the signals that should alert - latency/response/execution time
+    and availability/success/saturation percentages - with confirmation windows
+    and absolute + relative floors so brief spikes and sub-threshold jitter no
+    longer flap, and prefer percentage metrics over their absolute twins.
+
+  No detection-engine or schema changes; only per-metric `x-anomaly-*` defaults.
+  Users who had opted into any now-disabled metric keep their explicit override.
+
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+- Updated dependencies [8cad340]
+  - @checkstack/backend-api@0.25.0
+  - @checkstack/healthcheck-common@1.8.0
+  - @checkstack/common@0.17.0
+
 ## 0.2.35
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-postgres-backend",
-  "version": "0.2.35",
+  "version": "0.3.1",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,9 +14,9 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.24.1",
-    "@checkstack/common": "0.16.0",
-    "@checkstack/healthcheck-common": "1.7.1",
+    "@checkstack/backend-api": "0.26.0",
+    "@checkstack/common": "0.17.0",
+    "@checkstack/healthcheck-common": "1.8.1",
     "pg": "^8.11.0"
   },
   "devDependencies": {
@@ -24,7 +24,7 @@
     "@types/pg": "^8.11.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.6.2"
+    "@checkstack/scripts": "0.6.4"
   },
   "description": "Checkstack healthcheck-postgres-backend plugin",
   "author": {

package/src/query-collector.ts

@@ -37,10 +37,12 @@ const queryResultSchema = healthResultSchema({
   rowCount: healthResultNumber({
     "x-chart-type": "counter",
     "x-chart-label": "Row Count",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "deviation",
-    "x-anomaly-min-absolute-delta": 1,
-    "x-anomaly-min-relative-delta": 0.25,
+    // Row counts of arbitrary user-supplied SQL have no stable, universal
+    // baseline (a JOIN, a COUNT(*), a paginated SELECT all behave wildly
+    // differently) and no inherent good/bad direction. Baselining this would
+    // fire on routine data growth, so it is off by default. Still chartable
+    // and opt-in per check.
+    "x-anomaly-enabled": false,
   }),
   executionTimeMs: healthResultNumber({
     "x-chart-type": "line",
@@ -71,6 +73,12 @@ const queryAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Latency saturation signal. Err wider and require sustained drift plus a
+    // practical floor so a fast query is not flagged on sub-perceptible jitter.
+    "x-anomaly-sensitivity": 2,
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 50,
+    "x-anomaly-min-relative-delta": 0.5,
   }),
   successRate: aggregatedRate({
     "x-chart-type": "gauge",
@@ -78,6 +86,10 @@ const queryAggregatedFields = {
     "x-chart-unit": "%",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "higher-is-better",
+    // Availability percent. Require a few consecutive degraded buckets and a
+    // meaningful absolute drop so a single transient failure does not alert.
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 5,
   }),
 };
 

package/src/strategy.ts

@@ -17,6 +17,7 @@ import {
   configNumber,
   configBoolean,
   type ConnectedClient,
+  type TransportTimings,
   type InferAggregatedResult,
   baseStrategyConfigSchema,
 } from "@checkstack/backend-api";
@@ -96,13 +97,22 @@ const postgresAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Connection latency saturation. Err wider and require sustained drift plus
+    // a practical floor so a fast handshake is not flagged on small jitter.
+    "x-anomaly-sensitivity": 2,
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 50,
+    "x-anomaly-min-relative-delta": 0.5,
   }),
   maxConnectionTime: aggregatedMinMax({
     "x-chart-type": "line",
     "x-chart-label": "Max Connection Time",
     "x-chart-unit": "ms",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "lower-is-better",
+    // The per-bucket maximum is inherently spiky: one slow handshake (GC pause,
+    // transient network blip) moves it sharply, so baselining it produces noisy
+    // alerts. Average connection time already covers the latency-saturation
+    // signal, so the max is off by default and remains chartable.
+    "x-anomaly-enabled": false,
   }),
   successRate: aggregatedRate({
     "x-chart-type": "gauge",
@@ -110,12 +120,19 @@ const postgresAggregatedFields = {
     "x-chart-unit": "%",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "higher-is-better",
+    // Availability percent. Require a few consecutive degraded buckets and a
+    // meaningful absolute drop so a single transient failure does not alert.
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 5,
   }),
   errorCount: aggregatedCounter({
     "x-chart-type": "counter",
     "x-chart-label": "Errors",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "lower-is-better",
+    // Raw error count per bucket scales with check frequency and bucket size,
+    // so it has no stable universal baseline. Success rate already expresses
+    // failures as a normalized percent, so this absolute twin is off by default
+    // to avoid duplicate, volume-sensitive alerts.
+    "x-anomaly-enabled": false,
   }),
 };
 
@@ -237,6 +254,7 @@ export class PostgresHealthCheckStrategy implements HealthCheckStrategy<
   ): Promise<ConnectedClient<PostgresTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
+    const connectStart = performance.now();
     const connection = await this.dbClient.connect({
       host: validatedConfig.host,
       port: validatedConfig.port,
@@ -246,11 +264,19 @@ export class PostgresHealthCheckStrategy implements HealthCheckStrategy<
       ssl: validatedConfig.ssl ? { rejectUnauthorized: false } : undefined,
       connectionTimeoutMillis: validatedConfig.timeout,
     });
+    const timings: TransportTimings = {
+      connectMs: Math.max(0, Math.round(performance.now() - connectStart)),
+    };
 
     const client: PostgresTransportClient = {
       async exec(request: SqlQueryRequest): Promise<SqlQueryResult> {
         try {
+          const queryStart = performance.now();
           const result = await connection.query(request.query);
+          timings.processingMs = Math.max(
+            0,
+            Math.round(performance.now() - queryStart),
+          );
           return { rowCount: result.rowCount ?? 0 };
         } catch (error) {
           return {
@@ -263,6 +289,7 @@ export class PostgresHealthCheckStrategy implements HealthCheckStrategy<
 
     return {
       client,
+      timings,
       close: () => {
         connection.end().catch(() => {
           // Ignore close errors