feat(telemetry): gate ssh.network.sampled changes behind a 15s cooldown

Latency changes now must clear both the 25 ms absolute and 20 % relative
thresholds (previously either), and all change triggers (p2p flip, DERP
change, latency swing) share a 15 s cooldown since the last emission.
Suppressed changes coalesce into the next eligible emission instead of
being lost; the 60 s heartbeat is unchanged. Worst-case emission rate
drops from 28.8k to 5.76k events/day per connection.

Author: EhabY

src/instrumentation/EVENTS.md

@@ -382,9 +382,10 @@ Emitted by `SshTelemetry`.
 
 #### `ssh.network.sampled`
 
-Tunnel network sample. Emitted on a p2p flip, a preferred-DERP change, a
-meaningful latency change (at least 25 ms or 20 %), or a roughly 60 s
-heartbeat.
+Tunnel network sample. Emitted on a roughly 60 s heartbeat, or on a p2p
+flip, a preferred-DERP change, or a meaningful latency change (at least
+25 ms and at least 20 %). Change-triggered emissions are limited to one per
+15 s; a change that persists past that cooldown is emitted when it expires.
 
 | Attribute                      | Values                                                             |
 | ------------------------------ | ------------------------------------------------------------------ |

src/instrumentation/ssh.ts

@@ -2,6 +2,7 @@ import type { NetworkInfo } from "../remote/sshProcess";
 import type { TelemetryReporter } from "../telemetry/reporter";
 
 const NETWORK_SAMPLE_INTERVAL_MS = 60_000;
+const NETWORK_CHANGE_COOLDOWN_MS = 15_000;
 const NETWORK_LATENCY_CHANGE_RATIO = 0.2;
 const NETWORK_LATENCY_MIN_ABSOLUTE_CHANGE_MS = 25;
 
@@ -141,15 +142,22 @@ export class SshTelemetry {
 	}
 }
 
-/** Emit on p2p flip, DERP change, large latency swing, or heartbeat interval. */
+/** Emit on the heartbeat interval, or on a p2p flip, DERP change, or large
+ * latency swing once the change cooldown has elapsed. Suppression leaves the
+ * last emitted sample in place, so a change that persists through the
+ * cooldown is emitted when it expires rather than lost. */
 function shouldEmitSample(
 	previous: NetworkSample,
 	current: NetworkInfo,
 	now: number,
 ): boolean {
-	if (now - previous.emittedAtMs >= NETWORK_SAMPLE_INTERVAL_MS) {
+	const sinceLastEmit = now - previous.emittedAtMs;
+	if (sinceLastEmit >= NETWORK_SAMPLE_INTERVAL_MS) {
 		return true;
 	}
+	if (sinceLastEmit < NETWORK_CHANGE_COOLDOWN_MS) {
+		return false;
+	}
 	if (current.p2p !== previous.p2p) {
 		return true;
 	}
@@ -168,7 +176,7 @@ function hasMeaningfulLatencyChange(
 	}
 	const absoluteChange = Math.abs(current - previous);
 	return (
-		absoluteChange >= NETWORK_LATENCY_MIN_ABSOLUTE_CHANGE_MS ||
+		absoluteChange >= NETWORK_LATENCY_MIN_ABSOLUTE_CHANGE_MS &&
 		absoluteChange / Math.abs(previous) >= NETWORK_LATENCY_CHANGE_RATIO
 	);
 }

test/unit/instrumentation/ssh.test.ts

@@ -187,35 +187,56 @@ describe("SshTelemetry", () => {
 				name: "latency change below both thresholds (50 -> 51)",
 				prev: {},
 				next: { latency: 51 },
-				advanceMs: 1_000,
+				advanceMs: 15_000,
 				expected: 1,
 			},
 			{
-				name: "ratio branch only (50 -> 70)",
+				name: "latency change meeting only the ratio threshold (50 -> 70)",
 				prev: {},
 				next: { latency: 70 },
-				advanceMs: 1_000,
-				expected: 2,
+				advanceMs: 15_000,
+				expected: 1,
 			},
 			{
-				name: "absolute branch only (200 -> 230)",
+				name: "latency change meeting only the absolute threshold (200 -> 230)",
 				prev: { latency: 200 },
 				next: { latency: 230 },
+				advanceMs: 15_000,
+				expected: 1,
+			},
+			{
+				name: "latency change meeting both thresholds (50 -> 80)",
+				prev: {},
+				next: { latency: 80 },
+				advanceMs: 15_000,
+				expected: 2,
+			},
+			{
+				name: "latency change within the cooldown (50 -> 80)",
+				prev: {},
+				next: { latency: 80 },
 				advanceMs: 1_000,
+				expected: 1,
+			},
+			{
+				name: "p2p flip after the cooldown",
+				prev: {},
+				next: { p2p: false },
+				advanceMs: 15_000,
 				expected: 2,
 			},
 			{
-				name: "p2p flip",
+				name: "p2p flip within the cooldown",
 				prev: {},
 				next: { p2p: false },
 				advanceMs: 1_000,
-				expected: 2,
+				expected: 1,
 			},
 			{
-				name: "DERP region change",
+				name: "DERP region change after the cooldown",
 				prev: {},
 				next: { preferred_derp: "SFO" },
-				advanceMs: 1_000,
+				advanceMs: 15_000,
 				expected: 2,
 			},
 			{
@@ -229,7 +250,7 @@ describe("SshTelemetry", () => {
 				name: "baseline established from zero-latency placeholder (0 -> 5)",
 				prev: { latency: 0 },
 				next: { latency: 5 },
-				advanceMs: 1_000,
+				advanceMs: 15_000,
 				expected: 2,
 			},
 		])(
@@ -245,6 +266,20 @@ describe("SshTelemetry", () => {
 			},
 		);
 
+		it("coalesces a change suppressed by the cooldown into a later emission", () => {
+			const { ssh, sink } = setup();
+
+			ssh.networkSampled(makeNetworkInfo());
+			vi.advanceTimersByTime(3_000);
+			ssh.networkSampled(makeNetworkInfo({ p2p: false }));
+			vi.advanceTimersByTime(12_000);
+			ssh.networkSampled(makeNetworkInfo({ p2p: false }));
+
+			const samples = sink.eventsNamed("ssh.network.sampled");
+			expect(samples).toHaveLength(2);
+			expect(samples[1].properties.p2p).toBe("false");
+		});
+
 		it("includes p2p, preferred_derp, latency, and bandwidth in the emitted sample", () => {
 			const { ssh, sink } = setup();