@checkstack/healthcheck-ssh-backend 0.2.34 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,90 @@
 # @checkstack/healthcheck-ssh-backend
 
+## 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
+  - @checkstack/healthcheck-ssh-common@0.1.23
+
+## 0.2.35
+
+### Patch Changes
+
+- Updated dependencies [2ec8f64]
+  - @checkstack/backend-api@0.24.1
+
 ## 0.2.34
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-ssh-backend",
-  "version": "0.2.34",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -17,10 +17,10 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.24.0",
-    "@checkstack/common": "0.16.0",
-    "@checkstack/healthcheck-common": "1.7.1",
-    "@checkstack/healthcheck-ssh-common": "0.1.22",
+    "@checkstack/backend-api": "0.25.0",
+    "@checkstack/common": "0.17.0",
+    "@checkstack/healthcheck-common": "1.8.0",
+    "@checkstack/healthcheck-ssh-common": "0.1.23",
     "ssh2": "1.16.0"
   },
   "devDependencies": {
@@ -28,7 +28,7 @@
     "@types/ssh2": "1.15.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.6.2"
+    "@checkstack/scripts": "0.6.3"
   },
   "description": "Checkstack healthcheck-ssh-backend plugin",
   "author": {

package/src/command-collector.ts

@@ -37,8 +37,12 @@ const commandResultSchema = healthResultSchema({
   exitCode: healthResultNumber({
     "x-chart-type": "counter",
     "x-chart-label": "Exit Code",
-    "x-anomaly-enabled": true,
-    "x-anomaly-direction": "dominance",
+    // Disabled by default: the command is arbitrary and user-supplied, so the
+    // exit code has no learnable baseline (many commands legitimately return
+    // non-zero, and the meaningful "did it succeed" signal is already carried
+    // by the aggregated successRate). Treating exit-code changes as anomalies
+    // is a classic alert-fatigue source. Still chartable; users can opt in.
+    "x-anomaly-enabled": false,
   }),
   stdout: healthResultString({
     "x-chart-type": "text",
@@ -73,6 +77,12 @@ const commandAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Latency: err wider and require sustained slowdown plus practical floors
+    // so small jitter on fast commands never alerts.
+    "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",
@@ -80,6 +90,10 @@ const commandAggregatedFields = {
     "x-chart-unit": "%",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "higher-is-better",
+    // Availability percent: confirm a sustained drop and require a few percent
+    // of real movement before alerting.
+    "x-anomaly-confirmation-window": 3,
+    "x-anomaly-min-absolute-delta": 5,
   }),
 };
 

package/src/strategy.test.ts

@@ -45,6 +45,8 @@ describe("SshHealthCheckStrategy", () => {
       expect(connectedClient.client).toBeDefined();
       expect(connectedClient.client.exec).toBeDefined();
       expect(connectedClient.close).toBeDefined();
+      // The SSH handshake phase is measured up front in createClient.
+      expect(connectedClient.timings?.connectMs).toBeGreaterThanOrEqual(0);
 
       connectedClient.close();
     });
@@ -84,6 +86,8 @@ describe("SshHealthCheckStrategy", () => {
 
       expect(result.exitCode).toBe(0);
       expect(result.stdout).toBe("OK");
+      // exec records the command duration as processingMs (last-command-wins).
+      expect(connectedClient.timings?.processingMs).toBeGreaterThanOrEqual(0);
 
       connectedClient.close();
     });

package/src/strategy.ts

@@ -15,6 +15,7 @@ import {
   z,
   configString,
   type ConnectedClient,
+  type TransportTimings,
   type InferAggregatedResult,
   baseStrategyConfigSchema,
 } from "@checkstack/backend-api";
@@ -90,13 +91,22 @@ const sshAggregatedFields = {
     "x-chart-unit": "ms",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "lower-is-better",
+    // Latency: err wider and require a sustained, practically-significant
+    // slowdown so small jitter never alerts.
+    "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",
+    // A per-bucket max is the most outlier-sensitive aggregate: a single slow
+    // run drives it, so baselining it produces noisy alerts. The average twin
+    // already covers sustained latency regressions, so keep this off by default
+    // (still chartable for tail-latency inspection).
+    "x-anomaly-enabled": false,
   }),
   successRate: aggregatedRate({
     "x-chart-type": "gauge",
@@ -104,12 +114,19 @@ const sshAggregatedFields = {
     "x-chart-unit": "%",
     "x-anomaly-enabled": true,
     "x-anomaly-direction": "higher-is-better",
+    // Availability percent: confirm a sustained drop and require a few percent
+    // of real movement before alerting.
+    "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",
+    // Disabled by default: an absolute error count per bucket scales with the
+    // number of samples in the bucket, so its baseline drifts with traffic
+    // volume rather than with a real problem. Availability is already covered
+    // by successRate (the percent form), so prefer that and keep this off.
+    "x-anomaly-enabled": false,
   }),
 };
 
@@ -265,6 +282,10 @@ export class SshHealthCheckStrategy implements HealthCheckStrategy<
   ): Promise<ConnectedClient<SshTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
+    // The SSH handshake (TCP connect + auth + channel ready) is a single
+    // measurable phase up front; record it as connectMs. The per-command exec
+    // time is filled in below as processingMs (last-command-wins).
+    const connectStart = performance.now();
     const connection = await this.sshClient.connect({
       host: validatedConfig.host,
       port: validatedConfig.port,
@@ -274,11 +295,23 @@ export class SshHealthCheckStrategy implements HealthCheckStrategy<
       passphrase: validatedConfig.passphrase,
       readyTimeout: validatedConfig.timeout,
     });
+    const timings: TransportTimings = {
+      connectMs: Math.max(0, Math.round(performance.now() - connectStart)),
+    };
 
     return {
       client: {
-        exec: (command: string) => connection.exec(command),
+        exec: async (command: string): Promise<SshCommandResult> => {
+          const start = performance.now();
+          const result = await connection.exec(command);
+          timings.processingMs = Math.max(
+            0,
+            Math.round(performance.now() - start),
+          );
+          return result;
+        },
       },
+      timings,
       close: () => connection.end(),
     };
   }