effect-inspect 0.1.0 → 0.1.1

package/README.md

@@ -66,7 +66,7 @@ Options, all optional:
 Inspect.layer({
   url: 'ws://localhost:34437', // where the collector listens
   programName: 'my-service', // what the session list shows; defaults to the entry script's file name
-  bufferSize: 8192, // outbound queue, in messages
+  bufferSize: 131072, // outbound queue, in messages (~34 MB at the measured mean)
 })
 ```
 
@@ -89,9 +89,10 @@ someone else.
 **Adding the layer is safe anywhere.** If no collector is listening, the program
 runs exactly as it would have — no hang, no error, no delay. If the collector
 goes away mid-run the program keeps going and reconnects in the background,
-resuming the same session. If you outrun the socket, the oldest messages are
-dropped and the gap is reported as a warning in the trace, rather than pushing
-backpressure into your fibers.
+resuming the same session. If you outrun the socket, the buffer refuses the
+newest messages once it is full and reports the gap as a warning in the trace,
+rather than pushing backpressure into your fibers — so what you lose is the tail
+of a burst, never a span's start or end that already made it into the buffer.
 
 The one consequence: when the collector is down you get silence, not an error.
 The examples probe for it first and print a hint — worth copying if you hit

package/app/dist/server/assets/{_tanstack-start-manifest_v-Co953HeC.js → _tanstack-start-manifest_v-CFQ3DEVN.js}

@@ -1,7 +1,7 @@
 //#region \0tanstack-start-manifest:v
 var tsrStartManifest = () => ({ routes: {
 	__root__: {
-		filePath: "/Users/juliaortiz/Documents/dev.nosync/effect-inspect/app/src/routes/__root.tsx",
+		filePath: "/home/runner/work/effect-inspect/effect-inspect/app/src/routes/__root.tsx",
 		children: ["/"],
 		preloads: ["/assets/index-smV05cfr.js", "/assets/rolldown-runtime-CbXtAM7H.js"],
 		scripts: [{ attrs: {
@@ -11,7 +11,7 @@ var tsrStartManifest = () => ({ routes: {
 		} }]
 	},
 	"/": {
-		filePath: "/Users/juliaortiz/Documents/dev.nosync/effect-inspect/app/src/routes/index.tsx",
+		filePath: "/home/runner/work/effect-inspect/effect-inspect/app/src/routes/index.tsx",
 		children: void 0,
 		preloads: ["/assets/routes-TKgeFdSW.js"]
 	}

package/app/dist/server/server.js

@@ -91,7 +91,7 @@ var HEADERS = { TSS_SHELL: "X-TSS_SHELL" };
 * the dev styles URL for route-scoped CSS collection.
 */
 async function getStartManifest(matchedRoutes) {
-	const { tsrStartManifest } = await import("./assets/_tanstack-start-manifest_v-Co953HeC.js");
+	const { tsrStartManifest } = await import("./assets/_tanstack-start-manifest_v-CFQ3DEVN.js");
 	const startManifest = tsrStartManifest();
 	let routes = startManifest.routes;
 	routes[rootRouteId];

package/dist/client/Client.d.ts

@@ -4,12 +4,25 @@
  *
  * The guarantee that shapes this module is that instrumenting a program must
  * never break or slow it. So the producer side is a synchronous, non-blocking
- * {@link InspectClient} `sendUnsafe` onto a sliding queue, and every transport
+ * {@link InspectClient} `sendUnsafe` onto a dropping queue, and every transport
  * concern — no collector listening, a mid-run disconnect, a consumer slower
  * than the program — is confined to a background fiber whose failures are
- * swallowed and retried. When the program outruns the socket the queue drops
- * its oldest messages and reports the count, rather than growing without bound
+ * swallowed and retried. When the program outruns the socket the queue refuses
+ * the newest messages and reports the count, rather than growing without bound
  * or pushing backpressure into the fibers being traced.
+ *
+ * Dropping rather than sliding, because *which* message is lost is the whole
+ * problem. A sliding queue evicts its oldest entries, so a burst threw away the
+ * `SpanEnd` of a span still running — and the session's `Hello`, the first
+ * message there is — while keeping the unrelated messages that caused the
+ * overrun. A span whose end was dropped renders as never-ending. Refusing at
+ * the tail instead keeps every message already accepted, so loss is a suffix of
+ * the burst rather than a hole punched through the session's history.
+ *
+ * The drain writes each dequeued batch as one newline-delimited frame rather
+ * than one frame per message, because a per-message write is what made the
+ * socket slow enough for a realistic burst to overrun the queue in the first
+ * place.
  */
 import { Context, Effect, type Scope } from 'effect';
 import type { Socket } from 'effect/unstable/socket';
@@ -30,7 +43,7 @@ export declare class InspectClient extends InspectClient_base {
 export interface Options {
     /** Name shown for this program in the webapp. Defaults to the entry script's file name. */
     readonly programName?: string | undefined;
-    /** Outbound queue capacity, in messages. Defaults to 8192. */
+    /** Outbound queue capacity, in messages. Defaults to 131072 (~34 MB). */
     readonly bufferSize?: number | undefined;
     /**
      * How often to sample `process.memoryUsage()`, in milliseconds. Defaults to

package/dist/client/Client.js

@@ -4,19 +4,51 @@
  *
  * The guarantee that shapes this module is that instrumenting a program must
  * never break or slow it. So the producer side is a synchronous, non-blocking
- * {@link InspectClient} `sendUnsafe` onto a sliding queue, and every transport
+ * {@link InspectClient} `sendUnsafe` onto a dropping queue, and every transport
  * concern — no collector listening, a mid-run disconnect, a consumer slower
  * than the program — is confined to a background fiber whose failures are
- * swallowed and retried. When the program outruns the socket the queue drops
- * its oldest messages and reports the count, rather than growing without bound
+ * swallowed and retried. When the program outruns the socket the queue refuses
+ * the newest messages and reports the count, rather than growing without bound
  * or pushing backpressure into the fibers being traced.
+ *
+ * Dropping rather than sliding, because *which* message is lost is the whole
+ * problem. A sliding queue evicts its oldest entries, so a burst threw away the
+ * `SpanEnd` of a span still running — and the session's `Hello`, the first
+ * message there is — while keeping the unrelated messages that caused the
+ * overrun. A span whose end was dropped renders as never-ending. Refusing at
+ * the tail instead keeps every message already accepted, so loss is a suffix of
+ * the burst rather than a hole punched through the session's history.
+ *
+ * The drain writes each dequeued batch as one newline-delimited frame rather
+ * than one frame per message, because a per-message write is what made the
+ * socket slow enough for a realistic burst to overrun the queue in the first
+ * place.
  */
-import { Context, Duration, Effect, Latch, Queue, Schedule } from 'effect';
+import { Context, Duration, Effect, Latch, Queue, Result, Schedule } from 'effect';
 import { Socket as SocketService } from 'effect/unstable/socket';
 import { clientCodec } from '../protocol/Codec.js';
 import * as Protocol from '../protocol/Schema.js';
-/** How many messages may be buffered before the oldest are dropped. */
-const defaultBufferSize = 8192;
+/**
+ * How many messages may be buffered before new ones are refused.
+ *
+ * ponytail: the ceiling is counted in messages, not bytes. A message is a plain
+ * object held un-encoded, and the honest unit would be its retained size — but
+ * the only way to know that in `sendUnsafe` is to encode there, on the hot path
+ * of every traced span, duplicating work the drain already does. Measured
+ * instead: the reference workload's messages retain ~273 B each (and encode to
+ * ~275 B), so this bound is ~34 MB of queued telemetry. That is the documented
+ * ceiling — for *realistic* messages. Attribute values are user-supplied and
+ * unbounded, so a program annotating spans with megabyte strings can exceed it;
+ * the upgrade path is to track encoded bytes at the `writeBatch` boundary and
+ * feed that back as a byte budget, which costs a shared counter and is worth it
+ * only once someone actually hits it.
+ *
+ * 131,072 rather than the old 8,192 because batching the socket writes made the
+ * drain ~2.4x faster, so a deeper queue is cheap: it holds the entire 115,310
+ * message reference session at once, against a 31,563 msg/s peak that used to
+ * overrun 8,192 in a fifth of a second.
+ */
+const defaultBufferSize = 131072;
 /** How often a `Ping` is sent, so the collector can see a quiet program is alive. */
 const pingInterval = Duration.seconds(3);
 /** How often `process.memoryUsage()` is sampled, unless told otherwise. */
@@ -28,6 +60,28 @@ const defaultMemoryIntervalMillis = 100;
  * exit, and that is the worse failure.
  */
 const flushTimeout = Duration.millis(250);
+/**
+ * How many encoded bytes may ride in one socket frame.
+ *
+ * The drain writes a whole `takeAll` batch as one newline-delimited frame,
+ * which is the point — but a batch is unbounded, and the measured peak second
+ * is ~8.5 MB, so one write could otherwise hand the WebSocket a single
+ * multi-megabyte buffer to hold and copy. 256 KiB is roughly a thousand
+ * messages at the measured ~275 B mean: large enough that the per-write cost
+ * this change exists to remove is amortised away, small enough that the
+ * transient copy stays a normal allocation rather than a heap spike. The
+ * collector splits on newlines across chunk boundaries, so where a frame is
+ * cut has no effect on what it parses.
+ */
+const maxFrameBytes = 256 * 1024;
+/**
+ * How many messages may ride in one socket frame, whatever their size.
+ *
+ * A second bound for the pathological case the byte budget misses: a batch of
+ * very small messages would otherwise build one enormous array of strings
+ * before the join.
+ */
+const maxFrameMessages = 4096;
 /** Reconnect backoff: doubling from 250ms, capped so a late collector is still found. */
 const reconnectSchedule = Schedule.exponential(Duration.millis(250)).pipe(Schedule.modifyDelay(({ output }) => Effect.succeed(Duration.min(output, Duration.seconds(5)))));
 /**
@@ -116,24 +170,31 @@ const forkMemorySampler = (deps) => Effect.suspend(() => {
 export const make = (options) => Effect.gen(function* () {
     const socket = yield* SocketService.Socket;
     const capacity = options?.bufferSize ?? defaultBufferSize;
-    const queue = yield* Queue.sliding(capacity);
+    const queue = yield* Queue.dropping(capacity);
     // Effect's `Crypto` can fail with a PlatformError and nothing on this path
     // is allowed to fail; a session id needs uniqueness, not strength.
     // oxlint-disable-next-line effecttsgo/crypto-random-uuid-in-effect
     const sessionId = crypto.randomUUID();
     // Tracked here rather than inside the queue so a drop survives a
     // reconnect: it is reported on the next `Hello`, which every reconnect
-    // re-sends. A sliding `offerUnsafe` always succeeds, so a full queue is
-    // the only drop signal there is.
+    // re-sends.
     // Open exactly while the queue is empty, so shutdown can ask "is everything
     // on the wire?" rather than guessing with a sleep.
     const flushed = Latch.makeUnsafe(true);
     let dropped = 0;
     let reported = 0;
+    // Total and non-blocking by construction, and it has to stay that way: this
+    // runs inside `Tracer.span`, `span.end` and a `Logger`, none of which can
+    // suspend or fail. A dropping `offerUnsafe` returns `false` when the queue
+    // is full instead of suspending, which is the entire reason the queue is
+    // dropping rather than a backpressuring `bounded` — refusing a message is a
+    // gap in a trace, whereas parking the fiber that emitted it is the traced
+    // program running slower because it is being watched.
     const sendUnsafe = (message) => {
-        if (Queue.sizeUnsafe(queue) >= capacity)
+        if (!Queue.offerUnsafe(queue, message)) {
             dropped += 1;
-        Queue.offerUnsafe(queue, message);
+            return;
+        }
         flushed.closeUnsafe();
     };
     const hello = Effect.clockWith((clock) => Effect.succeed({
@@ -196,6 +257,41 @@ const connection = (deps) => Effect.gen(function* () {
     const reader = yield* deps.socket.reader;
     const writer = yield* deps.socket.writer;
     const write = (message) => Effect.suspend(() => writer.write(clientCodec.encode(message)));
+    /**
+     * Writes a batch as newline-delimited frames instead of one frame each.
+     *
+     * The codec already terminates every line with `\n`, so a frame is just
+     * the concatenation of its lines and the collector's line splitter carries
+     * an unterminated remainder across frames — batching needs no protocol
+     * change. Frames are cut at {@link maxFrameBytes} / {@link maxFrameMessages}
+     * so one huge batch cannot become one unbounded write.
+     *
+     * `encodeResult` rather than `encode`: `encode` throws, and a throw here
+     * would abandon the rest of an already-dequeued batch and tear down the
+     * connection over one out-of-domain field. A message that will not encode
+     * is dropped on its own and the batch carries on.
+     */
+    const writeBatch = (batch) => Effect.suspend(() => {
+        const frames = [];
+        let lines = [];
+        let bytes = 0;
+        for (const message of batch) {
+            const encoded = Result.getOrUndefined(clientCodec.encodeResult(message));
+            if (encoded === undefined)
+                continue;
+            if (lines.length > 0 &&
+                (bytes + encoded.length > maxFrameBytes || lines.length >= maxFrameMessages)) {
+                frames.push(lines.join(''));
+                lines = [];
+                bytes = 0;
+            }
+            lines.push(encoded);
+            bytes += encoded.length;
+        }
+        if (lines.length > 0)
+            frames.push(lines.join(''));
+        return Effect.forEach(frames, (frame) => writer.write(frame), { discard: true });
+    });
     yield* Effect.flatMap(deps.hello, write);
     // Keeps the connection warm and surfaces a half-open socket as a write
     // failure, which is what triggers the reconnect.
@@ -206,7 +302,7 @@ const connection = (deps) => Effect.gen(function* () {
         const gap = yield* deps.reportDropped;
         if (gap !== undefined)
             yield* write(gap);
-        yield* Effect.forEach(batch, write);
+        yield* writeBatch(batch);
         // Everything offered so far is on the wire. `sendUnsafe` closes the latch
         // again on the next message, so this tracks the queue rather than latching
         // permanently on the first quiet moment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-inspect",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "A live inspector for Effect programs",
   "repository": {