autotel-devtools 5.1.0 → 6.0.1

package/README.md

@@ -113,10 +113,10 @@ const myFunction = trace((ctx) => async () => {
 - **HTTP Routes** - OTLP receivers for traces/logs/metrics (JSON + protobuf)
 - **Exporters** - OpenTelemetry span/log exporters
 
-### Widget (Preact)
+### Widget (Svelte 5)
 
 - **Shadow DOM** - Isolated styles, no conflicts with app CSS
-- **Preact Signals** - Reactive state management
+- **Svelte 5 runes** - Reactive state via a signal shim that preserves a `.value` API
 - **Views** - Traces, Logs, Metrics, Errors, Resources, Service Map
 
 ## Features
@@ -152,12 +152,17 @@ AUTOTEL_DEVTOOLS_TITLE="My App"  # Dashboard title (optional)
 ### CLI Options
 
 ```bash
+npx autotel-devtools 4319                      # port as a bare positional
 npx autotel-devtools --port 4319 --host 0.0.0.0
 ```
 
+Arguments:
+
+- `[port]` - Port to listen on, shorthand for `--port` (an explicit `--port` always wins)
+
 Options:
 
-- `--port, -p` - Port to listen on (default: 4318)
+- `--port, -p` - Port to listen on (default: 4318). If the port is taken, the receiver walks forward to the next free port and prints a warning.
 - `--host, -H` - Host to bind to (default: 127.0.0.1)
 - `--title, -t` - Dashboard title
 

package/dist/cli.cjs

@@ -365,12 +365,17 @@ var DevtoolsServer = class {
   limits;
   verbose;
   _port;
+  onData;
   constructor(options = {}) {
     this.limits = resolveTelemetryLimits(options);
     this.verbose = options.verbose ?? false;
     this._port = options.port ?? 4318;
+    this.onData = options.onData;
     this.httpServer = options.server ?? http.createServer();
     this.wss = new ws.WebSocketServer({ server: this.httpServer, path: options.path ?? "/ws" });
+    this.wss.on("error", (err) => {
+      if (this.httpServer.listening) throw err;
+    });
     this.wss.on("connection", (ws) => {
       this.clients.add(ws);
       this.log(`Client connected (${this.clients.size} total)`);
@@ -462,6 +467,12 @@ var DevtoolsServer = class {
         client.send(msg);
       }
     }
+    if (this.onData) {
+      try {
+        this.onData(data);
+      } catch {
+      }
+    }
   }
   log(message) {
     if (this.verbose) console.log(`[autotel-devtools] ${message}`);
@@ -515,7 +526,10 @@ function flattenAttributes(attrs) {
 }
 function nanoToMs(nano) {
   if (!nano) return 0;
-  return Number(BigInt(nano) / 1000000n);
+  const ns = BigInt(nano);
+  const ms = ns / 1000000n;
+  const remNs = ns % 1000000n;
+  return Number(ms) + Number(remNs) / 1e6;
 }
 var SPAN_KIND_MAP = {
   0: "INTERNAL",
@@ -553,6 +567,7 @@ function parseOtlpTraces(payload) {
     const service = String(resourceAttrs["service.name"] || "unknown");
     const scopeSpans = rs.scopeSpans || [];
     for (const ss of scopeSpans) {
+      const scope = ss.scope?.name ? { name: ss.scope.name, version: ss.scope.version || void 0 } : void 0;
       for (const span of ss.spans || []) {
         const traceId = normalizeHexId(span.traceId);
         if (!traceId) continue;
@@ -577,7 +592,13 @@ function parseOtlpTraces(payload) {
             name: e.name || "",
             timestamp: nanoToMs(e.timeUnixNano),
             attributes: flattenAttributes(e.attributes)
-          }))
+          })),
+          links: (span.links || []).map((l) => ({
+            traceId: normalizeHexId(l.traceId),
+            spanId: normalizeHexId(l.spanId),
+            attributes: flattenAttributes(l.attributes)
+          })),
+          scope
         };
         const existing = traceMap.get(traceId);
         if (existing) {
@@ -1016,43 +1037,79 @@ function attachDevtoolsRoutes(httpServer, devtools) {
   });
 }
 var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var DEFAULT_MAX_PORT_TRIES = 20;
 function formatAddress(host, port) {
   return host.includes(":") ? `[${host}]:${port}` : `${host}:${port}`;
 }
 function listenLoopbackDualStack(args) {
-  const { primary, port, host, attachSecondary } = args;
+  const { primary, port, host, attachSecondary, maxTries } = args;
+  const maxAttempts = Math.max(1, maxTries ?? DEFAULT_MAX_PORT_TRIES);
   let sibling;
   const ready = new Promise(
-    (resolve3) => {
+    (resolve3, reject) => {
       const addresses = [];
       const warnings = [];
       const primaryHost = host === "localhost" ? "127.0.0.1" : host;
-      primary.listen(port, primaryHost, () => {
+      let candidate = port;
+      let attempt = 0;
+      const bindFailed = (atPort, msg) => reject(
+        new Error(`could not bind ${formatAddress(primaryHost, atPort)}: ${msg}`)
+      );
+      const onError = (e) => {
+        if (e.code !== "EADDRINUSE") return bindFailed(candidate, e.message);
+        if (++attempt >= maxAttempts) {
+          reject(
+            new Error(
+              `could not bind ${formatAddress(primaryHost, port)}: ${maxAttempts} consecutive ports in use`
+            )
+          );
+          return;
+        }
+        candidate++;
+        listen();
+      };
+      const onListening = () => {
+        primary.removeListener("error", onError);
+        if (candidate !== port) {
+          warnings.push(`port ${port} was busy; using ${candidate} instead`);
+        }
         const addr = primary.address();
-        const resolvedPort = addr && typeof addr === "object" ? addr.port : port;
+        const resolvedPort = addr && typeof addr === "object" ? addr.port : candidate;
         addresses.push(formatAddress(primaryHost, resolvedPort));
         if (!LOOPBACK.has(host)) {
-          resolve3({ addresses, warnings });
+          resolve3({ addresses, port: resolvedPort, warnings });
           return;
         }
         const siblingHost = primaryHost === "::1" ? "127.0.0.1" : "::1";
         const s = http.createServer();
         attachSecondary(s);
-        const onError = (e) => {
+        const onSiblingError = (se) => {
           s.close();
           warnings.push(
-            `could not also bind ${formatAddress(siblingHost, resolvedPort)} (${e.message}); clients using the ${siblingHost === "::1" ? "IPv6" : "IPv4"} form of "localhost" may not connect.`
+            `could not also bind ${formatAddress(siblingHost, resolvedPort)} (${se.message}); clients using the ${siblingHost === "::1" ? "IPv6" : "IPv4"} form of "localhost" may not connect.`
           );
-          resolve3({ addresses, warnings });
+          resolve3({ addresses, port: resolvedPort, warnings });
         };
-        s.once("error", onError);
+        s.once("error", onSiblingError);
         s.listen(resolvedPort, siblingHost, () => {
-          s.off("error", onError);
+          s.off("error", onSiblingError);
           sibling = s;
           addresses.push(formatAddress(siblingHost, resolvedPort));
-          resolve3({ addresses, warnings });
+          resolve3({ addresses, port: resolvedPort, warnings });
         });
-      });
+      };
+      const listen = () => {
+        try {
+          primary.listen(candidate, primaryHost);
+        } catch (e) {
+          primary.removeListener("error", onError);
+          primary.removeListener("listening", onListening);
+          bindFailed(candidate, e.message);
+        }
+      };
+      primary.on("error", onError);
+      primary.once("listening", onListening);
+      listen();
     }
   );
   return {
@@ -1069,10 +1126,14 @@ function printHelp() {
   process.stdout.write(
     `autotel-devtools - Standalone OTLP receiver with web devtools UI
 
-Usage: autotel-devtools [options]
+Usage: autotel-devtools [port] [options]
+
+Arguments:
+  port                 Port to listen on (shorthand for --port; must be a positive integer)
 
 Options:
-  -p, --port <port>    Port to listen on (default: 4318, env: AUTOTEL_DEVTOOLS_PORT)
+  -p, --port <port>    Port to listen on (default: 4318, env: AUTOTEL_DEVTOOLS_PORT).
+                       If the port is taken, the next free port is used and a warning is shown.
   -H, --host <host>    Host to bind to (default: 127.0.0.1, env: AUTOTEL_DEVTOOLS_HOST)
   -t, --title <title>  Dashboard title (env: AUTOTEL_DEVTOOLS_TITLE)
   Env limits:          AUTOTEL_MAX_TRACE_COUNT, AUTOTEL_MAX_LOG_COUNT, AUTOTEL_MAX_METRIC_COUNT
@@ -1092,7 +1153,8 @@ Endpoints:
 
 Examples:
   npx autotel-devtools
-  npx autotel-devtools -p 4319
+  npx autotel-devtools 4319
+  npx autotel-devtools -p 4319 -H 0.0.0.0
 
 Then point your app:
   OTEL_EXPORTER_OTLP_PROTOCOL=http/json OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 node app.js
@@ -1119,10 +1181,12 @@ function printVersion() {
 }
 function parseArgs(argv) {
   const options = {
-    port: Number(process.env.AUTOTEL_DEVTOOLS_PORT || 4318),
+    port: parsePort(process.env.AUTOTEL_DEVTOOLS_PORT || "4318"),
     host: process.env.AUTOTEL_DEVTOOLS_HOST || "127.0.0.1",
     title: process.env.AUTOTEL_DEVTOOLS_TITLE
   };
+  let portWasExplicit = false;
+  let positionalPortConsumed = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     const next = argv[i + 1];
@@ -1135,7 +1199,8 @@ function parseArgs(argv) {
       return null;
     }
     if ((arg === "--port" || arg === "-p") && next) {
-      options.port = Number(next);
+      options.port = parsePort(next);
+      portWasExplicit = true;
       i++;
       continue;
     }
@@ -1149,9 +1214,23 @@ function parseArgs(argv) {
       i++;
       continue;
     }
+    if (/^\d+$/.test(arg) && !positionalPortConsumed) {
+      if (!portWasExplicit) options.port = parsePort(arg);
+      positionalPortConsumed = true;
+      continue;
+    }
   }
   return options;
 }
+function parsePort(value) {
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 0 || n > 65535) {
+    process.stderr.write(`[autotel-devtools] invalid port: ${value}
+`);
+    process.exit(2);
+  }
+  return n;
+}
 async function main() {
   const options = parseArgs(process.argv.slice(2));
   if (!options) {
@@ -1166,8 +1245,8 @@ async function main() {
     host: options.host,
     attachSecondary: (s) => attachDevtoolsRoutes(s, wsServer)
   });
-  const { addresses, warnings } = await listeners.ready;
-  const uiBase = `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${options.port}`;
+  const { addresses, warnings, port: boundPort } = await listeners.ready;
+  const uiBase = `http://${options.host === "localhost" ? "127.0.0.1" : options.host}:${boundPort}`;
   const title = options.title || "autotel-devtools";
   process.stdout.write(`
   ${title}
@@ -1175,18 +1254,34 @@ async function main() {
 `);
   process.stdout.write(`  Listening: ${addresses.join("  +  ")}
 `);
-  process.stdout.write(`  UI:        ${uiBase}
+  process.stdout.write(`  UI:        ${uiBase}   (open in a browser)
 `);
-  process.stdout.write(`  Widget:    <script src="${uiBase}/widget.js"></script>
+  process.stdout.write(`  OTLP:      ${uiBase}/v1/traces
 `);
   process.stdout.write(`  WebSocket: ${uiBase.replace("http", "ws")}/ws
+
 `);
-  process.stdout.write(`  OTLP:      ${uiBase}/v1/traces
+  process.stdout.write(
+    `  Embed in your app \u2014 paste into your HTML; a floating panel appears automatically:
+`
+  );
+  process.stdout.write(`    <script src="${uiBase}/widget.js"></script>
 
 `);
-  process.stdout.write(`  Set OTEL_EXPORTER_OTLP_PROTOCOL=http/json
+  process.stdout.write(
+    `    full screen instead:  <script src="${uiBase}/widget.js?mode=fullpage"></script>
+`
+  );
+  process.stdout.write(
+    `    choose where it goes: add <autotel-devtools></autotel-devtools> to your markup
+
+`
+  );
+  process.stdout.write(`  Or point any OTLP exporter at this receiver:
+`);
+  process.stdout.write(`    OTEL_EXPORTER_OTLP_PROTOCOL=http/json
 `);
-  process.stdout.write(`  Set OTEL_EXPORTER_OTLP_ENDPOINT=${uiBase}
+  process.stdout.write(`    OTEL_EXPORTER_OTLP_ENDPOINT=${uiBase}
 
 `);
   process.stdout.write(`  Verify ingestion: curl -s ${uiBase}/v1/traces