@atolljs/devtools 0.1.7 → 0.1.8

package/dist/server.js

@@ -1,3 +1,10 @@
+import {
+  OtelMapper,
+  createOtelPipeline,
+  createOtlpSender,
+  sessionResource
+} from "./chunk-WIL2P7HG.js";
+
 // src/server.ts
 import { createServer } from "node:http";
 import { existsSync, readFileSync } from "node:fs";
@@ -167,6 +174,22 @@ function createDevtoolsServer(opts = {}) {
   const closedCap = 20;
   const closedTtlMs = opts.closedTtlMs ?? 30 * 60 * 1e3;
   const tail = [];
+  const pendingControl = /* @__PURE__ */ new Map();
+  let otlp = null;
+  const otlpSessions = /* @__PURE__ */ new Map();
+  if (opts.otlp) {
+    const o = opts.otlp;
+    otlp = createOtelPipeline({
+      sender: createOtlpSender(o),
+      signals: o.signals,
+      flushIntervalMs: o.flushIntervalMs,
+      maxBatch: o.maxBatch,
+      newMapper: (id) => new OtelMapper({
+        resource: sessionResource(otlpSessions.get(id) ?? { id, runtime: "browser" }, o.serviceName, o.resource),
+        signals: o.signals
+      })
+    });
+  }
   const sessionList = () => [...sessions.values(), ...closedSessions];
   const evictClosed = (sessionId) => {
     const i = closedSessions.findIndex((s) => s.id === sessionId);
@@ -204,7 +227,10 @@ function createDevtoolsServer(opts = {}) {
     if (head?.length) socket.unshift(head);
     if (url.pathname === "/view") {
       viewers.add(conn);
-      conn.onClose = () => viewers.delete(conn);
+      conn.onClose = () => {
+        viewers.delete(conn);
+        for (const [id, v] of pendingControl) if (v === conn) pendingControl.delete(id);
+      };
       conn.onMessage = (text) => {
         let msg;
         try {
@@ -221,6 +247,20 @@ function createDevtoolsServer(opts = {}) {
           if (!s || s.pinned === msg.pinned) return;
           s.pinned = msg.pinned;
           broadcast({ type: "sessions", sessions: sessionList() });
+        } else if (msg.type === "control") {
+          const app = [...sessions].find(([, s]) => s.id === msg.sessionId)?.[0];
+          if (!app) {
+            conn.send(JSON.stringify({
+              type: "control-result",
+              sessionId: msg.sessionId,
+              id: msg.id,
+              ok: false,
+              error: "session is not live"
+            }));
+            return;
+          }
+          pendingControl.set(msg.id, conn);
+          app.send(JSON.stringify(msg));
         }
       };
       conn.send(JSON.stringify({ type: "sessions", sessions: sessionList() }));
@@ -242,11 +282,26 @@ function createDevtoolsServer(opts = {}) {
         return;
       }
       if (msg.type === "batch" && greeted) {
-        broadcast({ type: "batch", session: sessions.get(conn), events: msg.events });
+        const session = sessions.get(conn);
+        broadcast({ type: "batch", session, events: msg.events });
+        if (otlp && Array.isArray(msg.events)) {
+          otlpSessions.set(session.id, session);
+          const recv = Date.now();
+          for (const ev of msg.events) otlp.ingest(ev, recv, session.id);
+        }
+      }
+      if (msg.type === "control-result") {
+        const viewer = pendingControl.get(msg.id);
+        pendingControl.delete(msg.id);
+        if (viewer && viewers.has(viewer)) viewer.send(JSON.stringify(msg));
       }
     };
     conn.onClose = () => {
       const info = sessions.get(conn);
+      if (info && otlp) {
+        otlp.release(info.id);
+        otlpSessions.delete(info.id);
+      }
       if (sessions.delete(conn) && info) {
         info.closed = true;
         info.closedAt = Date.now();
@@ -285,7 +340,10 @@ function createDevtoolsServer(opts = {}) {
           clearInterval(sweep);
           for (const v of viewers) v.close();
           for (const c of sessions.keys()) c.close();
-          server.close(() => done());
+          server.close(() => {
+            if (otlp) void otlp.close().then(() => done());
+            else done();
+          });
         })
       });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atolljs/devtools",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Devtools transport + local dashboard server for AtollJS instrumentation events",
   "homepage": "https://jwhenry3.github.io/atolljs/consumer/quickstart/",
   "type": "module",
@@ -13,6 +13,10 @@
       "types": "./dist/node.d.ts",
       "default": "./dist/node.js"
     },
+    "./otel": {
+      "types": "./dist/otel.d.ts",
+      "default": "./dist/otel.js"
+    },
     "./server": {
       "types": "./dist/server.d.ts",
       "default": "./dist/server.js"
@@ -35,7 +39,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "peerDependencies": {
-    "@atolljs/core": "0.1.7"
+    "@atolljs/core": "0.1.8"
   },
   "repository": {
     "type": "git",

package/src/bin.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/** `atoll-devtools [--port N]` — boot the local devtools server + dashboard. */
+/** `atoll-devtools [--port N] [--otlp URL]` — boot the local devtools server + dashboard. */
 import { createDevtoolsServer } from './server';
 
 const arg = (name: string): string | undefined => {
@@ -7,17 +7,42 @@ const arg = (name: string): string | undefined => {
   return i >= 0 ? process.argv[i + 1] : undefined;
 };
 
+/** `k=v,k2=v2` (the OTEL_EXPORTER_OTLP_HEADERS format) → a header record. */
+const parseHeaders = (list = ''): Record<string, string> =>
+  Object.fromEntries(
+    list
+      .split(',')
+      .filter((h) => h.includes('='))
+      .map((h) => [h.slice(0, h.indexOf('=')).trim(), h.slice(h.indexOf('=') + 1).trim()])
+      .filter(([k]) => k !== ''),
+  );
+
 if (process.argv.includes('--help') || process.argv.includes('-h')) {
-  console.log('usage: atoll-devtools [--port N]  — serve the devtools dashboard + event ingest (default port 4780)');
+  console.log(
+    'usage: atoll-devtools [--port N] [--otlp URL [--otlp-headers k=v,k2=v2] [--otlp-service NAME]]\n' +
+      '  serve the devtools dashboard + event ingest (default port 4780);\n' +
+      '  --otlp also forwards every session to an OTLP/HTTP endpoint (e.g. http://localhost:4318)',
+  );
   process.exit(0);
 }
 
 const port = Number(arg('port') ?? 4780);
+const otlpEndpoint = arg('otlp');
+const headers = parseHeaders(arg('otlp-headers'));
 const server = await createDevtoolsServer({
   port: Number.isFinite(port) ? port : 4780,
+  otlp: otlpEndpoint
+    ? {
+        endpoint: otlpEndpoint,
+        headers,
+        serviceName: arg('otlp-service'),
+        onError: (err) => console.warn(`otlp: ${err.message}`),
+      }
+    : undefined,
 });
 
 console.log(`atoll devtools → ${server.url}`);
 console.log('  dashboard: ' + server.url);
 console.log('  ingest:    ' + server.url.replace('http://', 'ws://') + '/events');
+if (otlpEndpoint) console.log('  otlp:      ' + otlpEndpoint);
 console.log('\nIn the app:  import { connectDevtools } from \'@atolljs/devtools\'; connectDevtools()');

package/src/broadcast.ts

@@ -15,6 +15,8 @@ import {
   setDevtoolsSink,
   type EmittedDevtoolsEvent,
 } from '@atolljs/core';
+import { answerControl } from './control';
+import { installJankProbe } from './probes';
 import { DEVTOOLS_CHANNEL, type BroadcastMessage, type SessionInfo } from './protocol';
 import type { ConnectDevtoolsOptions, DevtoolsConnection } from './client';
 
@@ -54,6 +56,8 @@ export function connectBroadcast(
     if (m.data?.type === 'view') {
       hello();
       for (const events of tail) post({ type: 'batch', session, events });
+    } else if (m.data?.type === 'control' && m.data.sessionId === session.id) {
+      void answerControl(m.data, (res) => post(res));
     }
   };
 
@@ -69,6 +73,7 @@ export function connectBroadcast(
 
   if (opts.network !== false) installFetchProbe(globalThis);
   if (opts.memory !== false) installMemoryProbe(globalThis);
+  const releaseJank = opts.jank !== false ? installJankProbe() : () => {};
 
   setDevtoolsSink((event) => {
     if (closed) return;
@@ -90,6 +95,7 @@ export function connectBroadcast(
       bye();
       setDevtoolsSink(null);
       clearInterval(timer);
+      releaseJank();
       if (typeof removeEventListener === 'function') removeEventListener('pagehide', onHide);
       bc.close();
     },

package/src/client.ts

@@ -24,7 +24,9 @@ import {
   type EmittedDevtoolsEvent,
 } from '@atolljs/core';
 import { connectBroadcast } from './broadcast';
-import type { ClientMessage, SessionInfo } from './protocol';
+import { answerControl, captureEnv } from './control';
+import { installJankProbe } from './probes';
+import type { AppMessage, ClientMessage, SessionInfo } from './protocol';
 
 export interface ConnectDevtoolsOptions {
   /**
@@ -37,7 +39,7 @@ export interface ConnectDevtoolsOptions {
   /** Server ingest endpoint — implies websocket transport. */
   url?: string;
   /** Session identity shown in the dashboard. */
-  session?: { name?: string; hint?: string };
+  session?: { name?: string; hint?: string; framework?: string };
   /** Batch flush interval ms (default 100). */
   flushMs?: number;
   /** Events buffered while disconnected (default 50_000 — oldest dropped). */
@@ -48,6 +50,12 @@ export interface ConnectDevtoolsOptions {
   network?: boolean;
   /** Sample JS heap usage periodically — Chrome/Blink only (default true). */
   memory?: boolean;
+  /**
+   * Main-thread jank probe (default true): long frames (`runtime:longframe`,
+   * Long Animation Frames or `longtask`) and a rAF fps sampler
+   * (`runtime:frames`). Browser main thread only.
+   */
+  jank?: boolean;
 }
 
 export interface DevtoolsConnection {
@@ -70,8 +78,10 @@ const makeSession = (opts: ConnectDevtoolsOptions): SessionInfo => {
   return {
     id: `s-${Date.now().toString(36)}-${++sessionSeq}`,
     name: opts.session?.name,
+    framework: opts.session?.framework,
     runtime,
     hint,
+    env: captureEnv(),
   };
 };
 
@@ -118,6 +128,16 @@ function connectWebSocket(opts: ConnectDevtoolsOptions, session: SessionInfo): D
     flush();
   };
 
+  const onMessage = (text: string) => {
+    let msg: AppMessage;
+    try {
+      msg = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (msg.type === 'control') void answerControl(msg, (res) => send(res));
+  };
+
   const isNode = typeof window === 'undefined' || typeof window.document === 'undefined';
   if (typeof WebSocket !== 'undefined') {
     const ws = new WebSocket(url);
@@ -129,6 +149,7 @@ function connectWebSocket(opts: ConnectDevtoolsOptions, session: SessionInfo): D
       close: () => ws.close(),
     };
     ws.onopen = onOpen;
+    ws.onmessage = (m: MessageEvent) => onMessage(String(m.data));
     ws.onclose = () => clearInterval(timer);
     ws.onerror = () => ws.close();
   } else if (isNode) {
@@ -142,6 +163,7 @@ function connectWebSocket(opts: ConnectDevtoolsOptions, session: SessionInfo): D
       const ws = m.connectNodeWebSocket(url);
       sock = ws;
       ws.onOpen = onOpen;
+      ws.onMessage = onMessage;
       ws.onClose = () => clearInterval(timer);
     }).catch(() => {
       /* no net available — sink stays installed but dead */
@@ -154,6 +176,7 @@ function connectWebSocket(opts: ConnectDevtoolsOptions, session: SessionInfo): D
 
   if (opts.network !== false) installFetchProbe(globalThis);
   if (opts.memory !== false) installMemoryProbe(globalThis);
+  const releaseJank = opts.jank !== false ? installJankProbe() : () => {};
 
   setDevtoolsSink((event) => {
     if (closed) return;
@@ -173,6 +196,7 @@ function connectWebSocket(opts: ConnectDevtoolsOptions, session: SessionInfo): D
       flush();
       sock?.close();
       clearInterval(timer);
+      releaseJank();
     },
   };
 }

package/src/control.ts

@@ -0,0 +1,51 @@
+/**
+ * App side of the control channel: answer a dashboard `control` frame by
+ * running the named command (`registerDevtoolsCommand` in @atolljs/core)
+ * and replying with a `control-result`. Both transports share this.
+ */
+import { runDevtoolsCommand } from '@atolljs/core';
+import type { ControlRequest, ControlResult, SessionEnv } from './protocol';
+
+/** Make a command result transport-safe: JSON round-trip, functions dropped. */
+const jsonSafe = (v: unknown): unknown => {
+  if (v === undefined) return undefined;
+  try {
+    return JSON.parse(JSON.stringify(v));
+  } catch {
+    return String(v);
+  }
+};
+
+export const answerControl = async (
+  req: ControlRequest,
+  reply: (res: ControlResult) => void,
+): Promise<void> => {
+  try {
+    const result = await runDevtoolsCommand(req.cmd, req.args ?? {});
+    reply({ type: 'control-result', sessionId: req.sessionId, id: req.id, ok: true, result: jsonSafe(result) });
+  } catch (err) {
+    reply({
+      type: 'control-result',
+      sessionId: req.sessionId,
+      id: req.id,
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+};
+
+/** Runtime facts for the session's `env` — what the audits panel reasons over. */
+export const captureEnv = (): SessionEnv => {
+  const g = globalThis as {
+    crossOriginIsolated?: boolean;
+    navigator?: { hardwareConcurrency?: number; userAgent?: string };
+    process?: { version?: string };
+  };
+  return {
+    crossOriginIsolated: g.crossOriginIsolated,
+    sharedArrayBuffer: typeof SharedArrayBuffer !== 'undefined',
+    hardwareConcurrency: g.navigator?.hardwareConcurrency,
+    userAgent: g.navigator?.userAgent,
+    node: g.navigator ? undefined : g.process?.version,
+  };
+};

package/src/nodeWs.ts

@@ -21,6 +21,7 @@ export interface NodeWebSocket {
   close(): void;
   onOpen: (() => void) | null;
   onClose: (() => void) | null;
+  onMessage: ((text: string) => void) | null;
 }
 
 /** Connect a WebSocket to `url` — handshake, then framed text IO. */
@@ -62,6 +63,7 @@ export function connectNodeWebSocket(url: string): NodeWebSocket {
     },
     onOpen: null,
     onClose: null,
+    onMessage: null,
   };
 
   const die = () => {
@@ -108,7 +110,11 @@ export function connectNodeWebSocket(url: string): NodeWebSocket {
       if (opcode === OPCODES.pong) continue;
       if (opcode === OPCODES.text || opcode === OPCODES.continuation) {
         fragments.push(payload);
-        if (fin) fragments = []; // client.ts never reads frames — drain only
+        if (fin) {
+          const text = Buffer.concat(fragments).toString('utf8');
+          fragments = [];
+          conn.onMessage?.(text);
+        }
       }
     }
   });

package/src/otel.ts

@@ -0,0 +1,140 @@
+/**
+ * `@atolljs/devtools/otel` — ship atoll instrumentation to any OpenTelemetry
+ * backend (Collector, Jaeger, Tempo, Honeycomb, Grafana) over OTLP/HTTP
+ * with JSON encoding. Zero dependencies: `fetch` + the mapping in otelMap.ts.
+ *
+ *   import { exportOtel } from '@atolljs/devtools/otel';
+ *   const otel = exportOtel({ serviceName: 'my-app' }); // → http://localhost:4318
+ *
+ * Installs as an additive devtools listener (`addDevtoolsSink`), so it runs
+ * alongside `connectDevtools()` or alone. Call it before pools spawn: like
+ * the dashboard transports, worker-side events forward only when a
+ * listener existed at the worker's INIT handshake.
+ */
+import { addDevtoolsSink, installFetchProbe, installMemoryProbe } from '@atolljs/core';
+import { OtelMapper, type OtelMapperOptions, type OtelSignals } from './otelMap';
+import {
+  createOtelPipeline,
+  createOtlpSender,
+  localResource,
+  type OtlpSenderOptions,
+  type ResourceAttributes,
+} from './otelTransport';
+import { installJankProbe } from './probes';
+
+export interface ExportOtelOptions extends OtlpSenderOptions {
+  /** Resource `service.name` (default 'unknown_service'). */
+  serviceName?: string;
+  /** Extra resource attributes, merged over the detected ones. */
+  resource?: ResourceAttributes;
+  /** Signals to export: all on by default. */
+  signals?: OtelSignals;
+  /** Periodic flush interval (default 5000ms). */
+  flushIntervalMs?: number;
+  /** Spans / log records per request (default 512). */
+  maxBatch?: number;
+  /** Queued spans and log records each before the oldest drop (default 2048). */
+  maxQueue?: number;
+  /** Series per metric before new attribute sets drop (default 2000). */
+  maxSeries?: number;
+  /** Patch global fetch for `net:fetch` spans (default true). */
+  network?: boolean;
+  /** Sample JS heap for `atoll.runtime.heap` (default true). */
+  memory?: boolean;
+  /** Browser main thread: long-frame / fps probe (default true). */
+  jank?: boolean;
+}
+
+export interface OtelExporter {
+  /** Ship everything queued now (plus a metrics snapshot). Never rejects. */
+  flush(): Promise<void>;
+  /** Uninstall the listener and lifecycle hooks, then flush. Never rejects. */
+  close(): Promise<void>;
+}
+
+export function exportOtel(opts: ExportOtelOptions = {}): OtelExporter {
+  // The sender captures the global fetch now, before the probe below wraps
+  // it, so the exporter's own posts never become net:fetch spans.
+  const sender = createOtlpSender(opts);
+  const endpoint = sender.endpoint;
+  const perf = globalThis.performance;
+  const originMs = perf.timeOrigin ?? Date.now() - perf.now();
+  const mapperOpts: OtelMapperOptions = {
+    resource: localResource(opts.serviceName, opts.resource),
+    originMs,
+    signals: opts.signals,
+    maxQueue: opts.maxQueue,
+    maxSeries: opts.maxSeries,
+    // An earlier probe (connectDevtools) may already wrap the captured fetch.
+    ignoreUrl: (url) => url.startsWith(endpoint),
+  };
+  const pipeline = createOtelPipeline({
+    sender,
+    newMapper: () => new OtelMapper(mapperOpts),
+    flushIntervalMs: opts.flushIntervalMs,
+    maxBatch: opts.maxBatch,
+    signals: opts.signals,
+  });
+
+  const remove = addDevtoolsSink((ev) => pipeline.ingest(ev, originMs + perf.now()));
+
+  if (opts.network !== false) installFetchProbe(globalThis);
+  if (opts.memory !== false) installMemoryProbe(globalThis);
+  const releaseJank = opts.jank !== false ? installJankProbe() : () => {};
+
+  // Last-chance flushes: keepalive fetch survives page unload (sendBeacon
+  // can't carry auth headers or a JSON content-type cross-origin).
+  type Listenable = {
+    addEventListener?: (t: string, l: () => void) => void;
+    removeEventListener?: (t: string, l: () => void) => void;
+  };
+  const g = globalThis as Listenable & {
+    document?: Listenable & { visibilityState?: string };
+    process?: {
+      once?: (e: string, l: () => void) => void;
+      off?: (e: string, l: () => void) => void;
+      versions?: { node?: string };
+    };
+  };
+  const onHide = () => {
+    if (g.document?.visibilityState === 'hidden') void pipeline.flush({ keepalive: true });
+  };
+  const onPageHide = () => void pipeline.flush({ keepalive: true });
+  const inBrowser = typeof g.document !== 'undefined' && typeof g.addEventListener === 'function';
+  if (inBrowser) {
+    g.addEventListener!('pagehide', onPageHide);
+    g.document!.addEventListener?.('visibilitychange', onHide);
+  }
+  const onBeforeExit = () => void pipeline.flush();
+  const inNode = !inBrowser && typeof g.process?.once === 'function' && g.process.versions?.node !== undefined;
+  if (inNode) g.process!.once!('beforeExit', onBeforeExit);
+
+  let closed = false;
+  return {
+    flush: () => pipeline.flush(),
+    async close() {
+      if (closed) return;
+      closed = true;
+      remove();
+      releaseJank();
+      if (inBrowser) {
+        g.removeEventListener?.('pagehide', onPageHide);
+        g.document?.removeEventListener?.('visibilitychange', onHide);
+      }
+      if (inNode) g.process!.off?.('beforeExit', onBeforeExit);
+      await pipeline.close();
+    },
+  };
+}
+
+export { OtelMapper, SEVERITY, newSpanId, newTraceId, toUnixNano } from './otelMap';
+export type { KeyValue, OtelMapperOptions, OtelSignals, OtlpLogRecord, OtlpMetric, OtlpSpan } from './otelMap';
+export { createOtelPipeline, createOtlpSender, localResource, sessionResource } from './otelTransport';
+export type {
+  OtelPipeline,
+  OtelPipelineOptions,
+  OtlpSender,
+  OtlpSenderOptions,
+  OtlpSignal,
+  ResourceAttributes,
+} from './otelTransport';