@reliantlabs/forge-web-runtime 0.9.2 → 0.10.1

package/README.md

@@ -157,6 +157,70 @@ object, embed` are blocked, images are not inlined and fonts are not collected.
 fetch/XHR spans have their `http.url` / `url.full` stripped of query string and
 fragment; request and response bodies and headers are not captured.
 
+## Node and Electron-main telemetry (`/node`)
+
+`initNodeTelemetry` is the browser entry's twin for a Node process — an
+Electron app's main process, a CLI. It ships logs, errors and spans as
+OTLP/JSON to the same ingest, normally the keyed one
+(`https://<ingest host>/k/<key>`), using Node built-ins only: no
+OpenTelemetry SDK packages to install beside `@opentelemetry/api`.
+
+```js
+import { app } from "electron";
+import {
+  flushOnQuit,
+  frontendServiceName,
+  initNodeTelemetry,
+} from "@reliantlabs/forge-web-runtime/node";
+
+const telemetry = initNodeTelemetry({
+  serviceName: frontendServiceName("shop", "desktop"), // "<project>-<frontend>", as forge derives it
+  serviceVersion: app.getVersion(),
+  environment: "prod",
+  appClient: "electron",
+  endpoint: "https://ingest.example.dev/k/pk_live_…", // unset, "" or "off": telemetry is off
+  origin: "app://bundle", // the keyed ingest admits only an allowlisted Origin
+  appRoot: app.getAppPath(), // stack paths are reported relative to it
+});
+flushOnQuit(app); // hold before-quit until the queue is out (2s at most)
+
+telemetry?.logger.warn("renderer gone", { reason: "oom" });
+telemetry?.reportError(err, { "settings.section": "privacy" });
+telemetry?.tracer.startActiveSpan("backend.start", (span) => {
+  /* … */ span.end();
+});
+```
+
+- **Uncaught exceptions and unhandled rejections** become ERROR records with
+  `exception.type`, `exception.message`, `exception.stacktrace` and
+  `code.function.name` — the keys forge/pkg/observe writes for a server error —
+  and no `rum.sessionId`, so `forge obs issues` groups them with sfp1.
+  `code.function.name` is the innermost application frame (not Node, Electron or
+  `node_modules`), written `fn (src/file.js)`.
+- **The process's fate is unchanged.** Exceptions are watched with
+  `uncaughtExceptionMonitor`. When the runtime's `unhandledRejection` listener is
+  the only one, it flushes, then raises the rejection as Node would have
+  (`--unhandled-rejections` is honoured). In plain Node with no
+  `uncaughtException` handler, it flushes and then exits as Node does; under
+  Electron nothing is installed there. `captureProcessErrors: false` turns all
+  of this off.
+- **Batching:** records wait up to `batchDelayMs` (5s) or `maxBatchSize` (256);
+  at most `maxQueueSize` (2048) per signal are held. Timers are unref'd. A fatal
+  record is sent at once, and an idle process flushes on `beforeExit`.
+  `flush(ms)` / `shutdown(ms)` resolve by their timeout whatever the network
+  does. An app that already defers `before-quit` for its own shutdown awaits
+  `telemetry.flush()` as the last step of it instead of calling `flushOnQuit`.
+- **Privacy:** an exception keeps its message's first line, with credential
+  shapes redacted (the patterns `track()` uses) and at most 1024 chars; the
+  stack is rebuilt from that line and its frames, with the home directory, the
+  install path and `app.asar` removed from every path. String attributes and
+  bodies are redacted and bounded, and object-valued attributes are dropped.
+  `setUser(id)` stamps the opaque `userId` the browser entry stamps. Nothing
+  else about the machine is sent: no host name, IP, argv or environment.
+- The global `@opentelemetry/api` tracer, AsyncLocalStorage context manager and
+  W3C `traceparent` propagator are this runtime's unless `registerGlobal: false`.
+  `reportException` from the barrel reports through it once it is running.
+
 ## The DOM-free interceptors entry point
 
 ```ts

package/dist/node-exception.d.ts

@@ -0,0 +1,73 @@
+/** Log attribute keys an ERROR record carries; the same keys observe writes. */
+export declare const EXCEPTION_TYPE = "exception.type";
+export declare const EXCEPTION_MESSAGE = "exception.message";
+export declare const EXCEPTION_STACKTRACE = "exception.stacktrace";
+export declare const CODE_FUNCTION = "code.function.name";
+export declare const CODE_FILE = "code.file.path";
+export declare const CODE_LINE = "code.line.number";
+/** Pins a record to a named issue whatever its call site (observe.ErrorGroup). */
+export declare const ERROR_GROUP = "error.group";
+/** Longest exception.message, in characters: observe's MaxExceptionMessage. */
+export declare const MAX_EXCEPTION_MESSAGE_CHARS = 1024;
+/** Longest exception.stacktrace, in characters: observe's maxStacktrace. */
+export declare const MAX_STACKTRACE_CHARS: number;
+/** Most frames kept from a stack. V8 records 10 by default. */
+export declare const MAX_FRAMES = 64;
+/** How paths in a stack are rewritten. */
+export interface PathScrub {
+    /** Files below it are reported relative to it (Electron: app.getAppPath()). */
+    appRoot?: string;
+    /** Files below it that are not below appRoot start with `~`. */
+    homeDir?: string;
+    /** Compare paths case-insensitively (win32). */
+    caseInsensitive?: boolean;
+}
+/** One parsed V8 stack frame. */
+export interface StackFrame {
+    /** The function as V8 names it, without `async `, `new ` or `[as alias]`; "" when anonymous. */
+    fn: string;
+    /** The file, already rewritten by the PathScrub. */
+    file: string;
+    line: number;
+    column: number;
+}
+/**
+ * The path a record may carry for `file`: relative below the app root, from
+ * inside an Electron archive, `~`-rooted below the home directory, otherwise
+ * unchanged. Pure; exported for tests.
+ */
+export declare function scrubPath(file: string, scrub: PathScrub): string;
+/** Parse a V8 stack's frame lines. Lines that are not frames are skipped. */
+export declare function parseStack(stack: string, scrub: PathScrub): StackFrame[];
+/**
+ * Whether a frame is the application's own code: not Node or Electron
+ * internals, not a dependency, not eval. The innermost such frame is where a
+ * failure "began" for grouping, as observe takes the innermost application
+ * frame of a Go stack.
+ */
+export declare function isApplicationFrame(frame: StackFrame): boolean;
+/**
+ * code.function.name for a frame: V8's own frame shape without line and
+ * column, `createWindow (src/main.js)`. The file is part of it because sfp1
+ * hashes this attribute and not code.file.path, and two `handle` functions in
+ * two files are two places.
+ */
+export declare function frameFunction(frame: StackFrame): string;
+/** Cut to `max` characters, ellipsis included. */
+export declare function bound(value: string, max: number): string;
+/** First line, credential shapes redacted, bounded: what a message may say. */
+export declare function boundMessage(message: string): string;
+/**
+ * exception.type for a thrown value: the class name for an Error (a subclass
+ * that never set `name` still reports its class), `typeof` for anything else.
+ */
+export declare function exceptionType(value: unknown): string;
+/** Attribute values an ERROR record carries. */
+export type ExceptionRecordAttributes = Record<string, string | number>;
+/**
+ * The attributes an ERROR record about `value` carries: exception.type,
+ * exception.message, and — when the value has a stack — exception.stacktrace
+ * and the code.* location of its innermost application frame. Pure given
+ * `scrub`; never throws.
+ */
+export declare function exceptionAttributes(value: unknown, scrub: PathScrub): ExceptionRecordAttributes;

package/dist/node-exception.js

@@ -0,0 +1,278 @@
+// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.
+//
+// What a Node / Electron-main ERROR record carries so the issues pipeline
+// groups it: the Node twin of forge/pkg/observe's error_inputs.go.
+//
+// A record from `/node` has no `rum.sessionId`, so the control plane's issue
+// view treats it as a SERVER error and fingerprints it with sfp1
+// (forge/pkg/obsquery/fingerprint.go). sfp1 hashes the service, then
+//
+//	code.function.name   where the failure began (never a line number)
+//	norm(Body)           the message template ("uncaught exception", ...)
+//	exception.type       the kind of failure
+//
+// so this module derives exactly those keys, under the same names observe
+// writes, plus exception.message, exception.stacktrace, code.file.path and
+// code.line.number for whoever reads the issue.
+//
+// ── Two installs must group as one ───────────────────────────────────────
+//
+// A stack frame names a file on the user's disk: /Users/<name>/..., or
+// C:\Users\<name>\AppData\... on Windows. That is a username, and it would
+// also split one bug into an issue per machine, because code.function.name
+// carries the file. So every path is rewritten before it leaves: below the
+// app root it becomes relative (`src/main.js`), inside an Electron archive it
+// starts after `app.asar/`, and anything else under the home directory starts
+// with `~`. The same rewrite runs over the whole stack text.
+//
+// ── What leaves, and what does not ───────────────────────────────────────
+//
+// The message is cut to its first line, has credential shapes redacted (the
+// same patterns `track()` uses, redactSecrets in track.ts) and is bounded.
+// The stack is REBUILT as "<type>: <that message>" plus the frame lines, so a
+// multi-line message (stderr, tool output, a file's contents) cannot ride in
+// through the stack's first line. A thrown non-Error object contributes its
+// type and a string `message` property only: an object literal is where a
+// payload hides, and it is never serialized.
+import { redactSecrets } from "./track.js";
+/** Log attribute keys an ERROR record carries; the same keys observe writes. */
+export const EXCEPTION_TYPE = "exception.type";
+export const EXCEPTION_MESSAGE = "exception.message";
+export const EXCEPTION_STACKTRACE = "exception.stacktrace";
+export const CODE_FUNCTION = "code.function.name";
+export const CODE_FILE = "code.file.path";
+export const CODE_LINE = "code.line.number";
+/** Pins a record to a named issue whatever its call site (observe.ErrorGroup). */
+export const ERROR_GROUP = "error.group";
+/** Longest exception.message, in characters: observe's MaxExceptionMessage. */
+export const MAX_EXCEPTION_MESSAGE_CHARS = 1024;
+/** Longest exception.stacktrace, in characters: observe's maxStacktrace. */
+export const MAX_STACKTRACE_CHARS = 16 * 1024;
+/** Most frames kept from a stack. V8 records 10 by default. */
+export const MAX_FRAMES = 64;
+const ELLIPSIS = "…";
+// `    at fn (file:line:col)`, `    at file:line:col`, `    at async fn (...)`.
+// The file part is greedy up to the LAST :line:col, so a Windows drive letter
+// (C:\...) or a URL scheme (file:///...) stays in it.
+const FRAME_RE = /^\s*at (?:(.*?) \()?(.+):(\d+):(\d+)\)?\s*$/;
+/** Normalize separators so one comparison serves POSIX and Windows paths. */
+function slashes(p) {
+    return p.replace(/\\/g, "/");
+}
+function stripFileUrl(p) {
+    if (!p.startsWith("file://")) {
+        return p;
+    }
+    let rest = p.slice("file://".length);
+    // file:///C:/x -> C:/x ; file:///home/x -> /home/x
+    if (/^\/[A-Za-z]:\//.test(rest)) {
+        rest = rest.slice(1);
+    }
+    try {
+        return decodeURIComponent(rest);
+    }
+    catch {
+        return rest;
+    }
+}
+function under(path, root, ci) {
+    if (!root) {
+        return null;
+    }
+    let r = slashes(root).replace(/\/+$/, "");
+    if (r === "") {
+        return null;
+    }
+    let p = path;
+    if (ci) {
+        r = r.toLowerCase();
+        p = path.toLowerCase();
+    }
+    if (p === r) {
+        return "";
+    }
+    if (p.startsWith(r + "/")) {
+        return path.slice(r.length + 1);
+    }
+    return null;
+}
+/**
+ * The path a record may carry for `file`: relative below the app root, from
+ * inside an Electron archive, `~`-rooted below the home directory, otherwise
+ * unchanged. Pure; exported for tests.
+ */
+export function scrubPath(file, scrub) {
+    const ci = scrub.caseInsensitive ?? false;
+    const p = slashes(stripFileUrl(file));
+    const rel = under(p, scrub.appRoot, ci);
+    if (rel !== null) {
+        return rel;
+    }
+    const asar = p.search(/\/app\.asar(?:\.unpacked)?\//);
+    if (asar !== -1) {
+        return p.slice(p.indexOf("/", asar + 1) + 1);
+    }
+    const home = under(p, scrub.homeDir, ci);
+    if (home !== null) {
+        return home === "" ? "~" : `~/${home}`;
+    }
+    return p;
+}
+/** Parse a V8 stack's frame lines. Lines that are not frames are skipped. */
+export function parseStack(stack, scrub) {
+    const frames = [];
+    for (const line of stack.split("\n")) {
+        if (frames.length >= MAX_FRAMES) {
+            break;
+        }
+        const m = FRAME_RE.exec(line);
+        if (!m) {
+            continue;
+        }
+        // `Timeout.explode [as _onTimeout]`: the alias is the property the
+        // function was reached through, which changes with the caller.
+        const fn = (m[1] ?? "")
+            .replace(/^(?:async |new )/, "")
+            .replace(/ \[as [^\]]*\]$/, "")
+            .trim();
+        frames.push({
+            fn,
+            file: scrubPath(m[2] ?? "", scrub),
+            line: Number(m[3]),
+            column: Number(m[4]),
+        });
+    }
+    return frames;
+}
+/**
+ * Whether a frame is the application's own code: not Node or Electron
+ * internals, not a dependency, not eval. The innermost such frame is where a
+ * failure "began" for grouping, as observe takes the innermost application
+ * frame of a Go stack.
+ */
+export function isApplicationFrame(frame) {
+    const f = frame.file;
+    if (f === "" || f === "<anonymous>" || f === "native") {
+        return false;
+    }
+    if (f.startsWith("node:") ||
+        f.startsWith("internal/") ||
+        f.startsWith("electron/")) {
+        return false;
+    }
+    if (f.includes("node_modules/") || f.includes("node_modules.asar")) {
+        return false;
+    }
+    if (f.includes("electron.asar") || f.includes("electron/js2c")) {
+        return false;
+    }
+    return true;
+}
+/**
+ * code.function.name for a frame: V8's own frame shape without line and
+ * column, `createWindow (src/main.js)`. The file is part of it because sfp1
+ * hashes this attribute and not code.file.path, and two `handle` functions in
+ * two files are two places.
+ */
+export function frameFunction(frame) {
+    return `${frame.fn || "<anonymous>"} (${frame.file})`;
+}
+/** Cut to `max` characters, ellipsis included. */
+export function bound(value, max) {
+    if (value.length <= max) {
+        return value;
+    }
+    return value.slice(0, Math.max(0, max - ELLIPSIS.length)) + ELLIPSIS;
+}
+/** First line, credential shapes redacted, bounded: what a message may say. */
+export function boundMessage(message) {
+    const nl = message.indexOf("\n");
+    const first = (nl === -1 ? message : message.slice(0, nl)).replace(/\s+$/, "");
+    // Cut before redacting so the scan is bounded, with headroom so a secret
+    // straddling the final cut is still seen whole.
+    return bound(redactSecrets(first.slice(0, MAX_EXCEPTION_MESSAGE_CHARS * 2)), MAX_EXCEPTION_MESSAGE_CHARS);
+}
+/**
+ * exception.type for a thrown value: the class name for an Error (a subclass
+ * that never set `name` still reports its class), `typeof` for anything else.
+ */
+export function exceptionType(value) {
+    if (value instanceof Error) {
+        const ctor = value.constructor
+            ?.name;
+        if (typeof ctor === "string" &&
+            ctor !== "" &&
+            ctor !== "Error" &&
+            ctor !== "Object") {
+            return ctor;
+        }
+        return typeof value.name === "string" && value.name !== ""
+            ? value.name
+            : "Error";
+    }
+    if (value === null) {
+        return "null";
+    }
+    return typeof value;
+}
+function rawMessage(value) {
+    if (value instanceof Error) {
+        return typeof value.message === "string" ? value.message : "";
+    }
+    switch (typeof value) {
+        case "string":
+            return value;
+        case "number":
+        case "boolean":
+        case "bigint":
+        case "symbol":
+            return String(value);
+        case "object": {
+            // Never serialized: an object literal is where a payload hides.
+            const m = value?.message;
+            return typeof m === "string" ? m : "";
+        }
+        default:
+            return "";
+    }
+}
+/**
+ * The attributes an ERROR record about `value` carries: exception.type,
+ * exception.message, and — when the value has a stack — exception.stacktrace
+ * and the code.* location of its innermost application frame. Pure given
+ * `scrub`; never throws.
+ */
+export function exceptionAttributes(value, scrub) {
+    const type = exceptionType(value);
+    const message = boundMessage(rawMessage(value));
+    const out = {
+        [EXCEPTION_TYPE]: type,
+        [EXCEPTION_MESSAGE]: message,
+    };
+    let stack;
+    try {
+        stack = value?.stack;
+    }
+    catch {
+        stack = undefined;
+    }
+    if (typeof stack !== "string" || stack === "") {
+        return out;
+    }
+    const frames = parseStack(stack, scrub);
+    if (frames.length === 0) {
+        return out;
+    }
+    const header = message === "" ? type : `${type}: ${message}`;
+    const lines = frames.map((f) => `    at ${f.fn ? `${f.fn} (${f.file}:${f.line}:${f.column})` : `${f.file}:${f.line}:${f.column}`}`);
+    // The top of the stack — where it failed — is the part kept.
+    out[EXCEPTION_STACKTRACE] = bound(redactSecrets([header, ...lines].join("\n")), MAX_STACKTRACE_CHARS);
+    const origin = frames.find(isApplicationFrame) ?? frames[0];
+    if (origin) {
+        out[CODE_FUNCTION] = frameFunction(origin);
+        out[CODE_FILE] = origin.file;
+        out[CODE_LINE] = origin.line;
+    }
+    return out;
+}
+//# sourceMappingURL=node-exception.js.map

package/dist/node-exception.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-exception.js","sourceRoot":"","sources":["../src/node-exception.ts"],"names":[],"mappings":"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","sourcesContent":["// Part of @reliantlabs/forge-web-runtime — the web twin of forge/pkg.\n//\n// What a Node / Electron-main ERROR record carries so the issues pipeline\n// groups it: the Node twin of forge/pkg/observe's error_inputs.go.\n//\n// A record from `/node` has no `rum.sessionId`, so the control plane's issue\n// view treats it as a SERVER error and fingerprints it with sfp1\n// (forge/pkg/obsquery/fingerprint.go). sfp1 hashes the service, then\n//\n//\tcode.function.name   where the failure began (never a line number)\n//\tnorm(Body)           the message template (\"uncaught exception\", ...)\n//\texception.type       the kind of failure\n//\n// so this module derives exactly those keys, under the same names observe\n// writes, plus exception.message, exception.stacktrace, code.file.path and\n// code.line.number for whoever reads the issue.\n//\n// ── Two installs must group as one ───────────────────────────────────────\n//\n// A stack frame names a file on the user's disk: /Users/<name>/..., or\n// C:\\Users\\<name>\\AppData\\... on Windows. That is a username, and it would\n// also split one bug into an issue per machine, because code.function.name\n// carries the file. So every path is rewritten before it leaves: below the\n// app root it becomes relative (`src/main.js`), inside an Electron archive it\n// starts after `app.asar/`, and anything else under the home directory starts\n// with `~`. The same rewrite runs over the whole stack text.\n//\n// ── What leaves, and what does not ───────────────────────────────────────\n//\n// The message is cut to its first line, has credential shapes redacted (the\n// same patterns `track()` uses, redactSecrets in track.ts) and is bounded.\n// The stack is REBUILT as \"<type>: <that message>\" plus the frame lines, so a\n// multi-line message (stderr, tool output, a file's contents) cannot ride in\n// through the stack's first line. A thrown non-Error object contributes its\n// type and a string `message` property only: an object literal is where a\n// payload hides, and it is never serialized.\nimport { redactSecrets } from \"./track.js\";\n\n/** Log attribute keys an ERROR record carries; the same keys observe writes. */\nexport const EXCEPTION_TYPE = \"exception.type\";\nexport const EXCEPTION_MESSAGE = \"exception.message\";\nexport const EXCEPTION_STACKTRACE = \"exception.stacktrace\";\nexport const CODE_FUNCTION = \"code.function.name\";\nexport const CODE_FILE = \"code.file.path\";\nexport const CODE_LINE = \"code.line.number\";\n/** Pins a record to a named issue whatever its call site (observe.ErrorGroup). */\nexport const ERROR_GROUP = \"error.group\";\n\n/** Longest exception.message, in characters: observe's MaxExceptionMessage. */\nexport const MAX_EXCEPTION_MESSAGE_CHARS = 1024;\n/** Longest exception.stacktrace, in characters: observe's maxStacktrace. */\nexport const MAX_STACKTRACE_CHARS = 16 * 1024;\n/** Most frames kept from a stack. V8 records 10 by default. */\nexport const MAX_FRAMES = 64;\n\nconst ELLIPSIS = \"…\";\n\n/** How paths in a stack are rewritten. */\nexport interface PathScrub {\n  /** Files below it are reported relative to it (Electron: app.getAppPath()). */\n  appRoot?: string;\n  /** Files below it that are not below appRoot start with `~`. */\n  homeDir?: string;\n  /** Compare paths case-insensitively (win32). */\n  caseInsensitive?: boolean;\n}\n\n/** One parsed V8 stack frame. */\nexport interface StackFrame {\n  /** The function as V8 names it, without `async `, `new ` or `[as alias]`; \"\" when anonymous. */\n  fn: string;\n  /** The file, already rewritten by the PathScrub. */\n  file: string;\n  line: number;\n  column: number;\n}\n\n// `    at fn (file:line:col)`, `    at file:line:col`, `    at async fn (...)`.\n// The file part is greedy up to the LAST :line:col, so a Windows drive letter\n// (C:\\...) or a URL scheme (file:///...) stays in it.\nconst FRAME_RE = /^\\s*at (?:(.*?) \\()?(.+):(\\d+):(\\d+)\\)?\\s*$/;\n\n/** Normalize separators so one comparison serves POSIX and Windows paths. */\nfunction slashes(p: string): string {\n  return p.replace(/\\\\/g, \"/\");\n}\n\nfunction stripFileUrl(p: string): string {\n  if (!p.startsWith(\"file://\")) {\n    return p;\n  }\n  let rest = p.slice(\"file://\".length);\n  // file:///C:/x -> C:/x ; file:///home/x -> /home/x\n  if (/^\\/[A-Za-z]:\\//.test(rest)) {\n    rest = rest.slice(1);\n  }\n  try {\n    return decodeURIComponent(rest);\n  } catch {\n    return rest;\n  }\n}\n\nfunction under(\n  path: string,\n  root: string | undefined,\n  ci: boolean,\n): string | null {\n  if (!root) {\n    return null;\n  }\n  let r = slashes(root).replace(/\\/+$/, \"\");\n  if (r === \"\") {\n    return null;\n  }\n  let p = path;\n  if (ci) {\n    r = r.toLowerCase();\n    p = path.toLowerCase();\n  }\n  if (p === r) {\n    return \"\";\n  }\n  if (p.startsWith(r + \"/\")) {\n    return path.slice(r.length + 1);\n  }\n  return null;\n}\n\n/**\n * The path a record may carry for `file`: relative below the app root, from\n * inside an Electron archive, `~`-rooted below the home directory, otherwise\n * unchanged. Pure; exported for tests.\n */\nexport function scrubPath(file: string, scrub: PathScrub): string {\n  const ci = scrub.caseInsensitive ?? false;\n  const p = slashes(stripFileUrl(file));\n  const rel = under(p, scrub.appRoot, ci);\n  if (rel !== null) {\n    return rel;\n  }\n  const asar = p.search(/\\/app\\.asar(?:\\.unpacked)?\\//);\n  if (asar !== -1) {\n    return p.slice(p.indexOf(\"/\", asar + 1) + 1);\n  }\n  const home = under(p, scrub.homeDir, ci);\n  if (home !== null) {\n    return home === \"\" ? \"~\" : `~/${home}`;\n  }\n  return p;\n}\n\n/** Parse a V8 stack's frame lines. Lines that are not frames are skipped. */\nexport function parseStack(stack: string, scrub: PathScrub): StackFrame[] {\n  const frames: StackFrame[] = [];\n  for (const line of stack.split(\"\\n\")) {\n    if (frames.length >= MAX_FRAMES) {\n      break;\n    }\n    const m = FRAME_RE.exec(line);\n    if (!m) {\n      continue;\n    }\n    // `Timeout.explode [as _onTimeout]`: the alias is the property the\n    // function was reached through, which changes with the caller.\n    const fn = (m[1] ?? \"\")\n      .replace(/^(?:async |new )/, \"\")\n      .replace(/ \\[as [^\\]]*\\]$/, \"\")\n      .trim();\n    frames.push({\n      fn,\n      file: scrubPath(m[2] ?? \"\", scrub),\n      line: Number(m[3]),\n      column: Number(m[4]),\n    });\n  }\n  return frames;\n}\n\n/**\n * Whether a frame is the application's own code: not Node or Electron\n * internals, not a dependency, not eval. The innermost such frame is where a\n * failure \"began\" for grouping, as observe takes the innermost application\n * frame of a Go stack.\n */\nexport function isApplicationFrame(frame: StackFrame): boolean {\n  const f = frame.file;\n  if (f === \"\" || f === \"<anonymous>\" || f === \"native\") {\n    return false;\n  }\n  if (\n    f.startsWith(\"node:\") ||\n    f.startsWith(\"internal/\") ||\n    f.startsWith(\"electron/\")\n  ) {\n    return false;\n  }\n  if (f.includes(\"node_modules/\") || f.includes(\"node_modules.asar\")) {\n    return false;\n  }\n  if (f.includes(\"electron.asar\") || f.includes(\"electron/js2c\")) {\n    return false;\n  }\n  return true;\n}\n\n/**\n * code.function.name for a frame: V8's own frame shape without line and\n * column, `createWindow (src/main.js)`. The file is part of it because sfp1\n * hashes this attribute and not code.file.path, and two `handle` functions in\n * two files are two places.\n */\nexport function frameFunction(frame: StackFrame): string {\n  return `${frame.fn || \"<anonymous>\"} (${frame.file})`;\n}\n\n/** Cut to `max` characters, ellipsis included. */\nexport function bound(value: string, max: number): string {\n  if (value.length <= max) {\n    return value;\n  }\n  return value.slice(0, Math.max(0, max - ELLIPSIS.length)) + ELLIPSIS;\n}\n\n/** First line, credential shapes redacted, bounded: what a message may say. */\nexport function boundMessage(message: string): string {\n  const nl = message.indexOf(\"\\n\");\n  const first = (nl === -1 ? message : message.slice(0, nl)).replace(\n    /\\s+$/,\n    \"\",\n  );\n  // Cut before redacting so the scan is bounded, with headroom so a secret\n  // straddling the final cut is still seen whole.\n  return bound(\n    redactSecrets(first.slice(0, MAX_EXCEPTION_MESSAGE_CHARS * 2)),\n    MAX_EXCEPTION_MESSAGE_CHARS,\n  );\n}\n\n/**\n * exception.type for a thrown value: the class name for an Error (a subclass\n * that never set `name` still reports its class), `typeof` for anything else.\n */\nexport function exceptionType(value: unknown): string {\n  if (value instanceof Error) {\n    const ctor = (value as { constructor?: { name?: unknown } }).constructor\n      ?.name;\n    if (\n      typeof ctor === \"string\" &&\n      ctor !== \"\" &&\n      ctor !== \"Error\" &&\n      ctor !== \"Object\"\n    ) {\n      return ctor;\n    }\n    return typeof value.name === \"string\" && value.name !== \"\"\n      ? value.name\n      : \"Error\";\n  }\n  if (value === null) {\n    return \"null\";\n  }\n  return typeof value;\n}\n\nfunction rawMessage(value: unknown): string {\n  if (value instanceof Error) {\n    return typeof value.message === \"string\" ? value.message : \"\";\n  }\n  switch (typeof value) {\n    case \"string\":\n      return value;\n    case \"number\":\n    case \"boolean\":\n    case \"bigint\":\n    case \"symbol\":\n      return String(value);\n    case \"object\": {\n      // Never serialized: an object literal is where a payload hides.\n      const m = (value as { message?: unknown } | null)?.message;\n      return typeof m === \"string\" ? m : \"\";\n    }\n    default:\n      return \"\";\n  }\n}\n\n/** Attribute values an ERROR record carries. */\nexport type ExceptionRecordAttributes = Record<string, string | number>;\n\n/**\n * The attributes an ERROR record about `value` carries: exception.type,\n * exception.message, and — when the value has a stack — exception.stacktrace\n * and the code.* location of its innermost application frame. Pure given\n * `scrub`; never throws.\n */\nexport function exceptionAttributes(\n  value: unknown,\n  scrub: PathScrub,\n): ExceptionRecordAttributes {\n  const type = exceptionType(value);\n  const message = boundMessage(rawMessage(value));\n  const out: ExceptionRecordAttributes = {\n    [EXCEPTION_TYPE]: type,\n    [EXCEPTION_MESSAGE]: message,\n  };\n  let stack: unknown;\n  try {\n    stack = (value as { stack?: unknown } | null)?.stack;\n  } catch {\n    stack = undefined;\n  }\n  if (typeof stack !== \"string\" || stack === \"\") {\n    return out;\n  }\n  const frames = parseStack(stack, scrub);\n  if (frames.length === 0) {\n    return out;\n  }\n  const header = message === \"\" ? type : `${type}: ${message}`;\n  const lines = frames.map(\n    (f) =>\n      `    at ${f.fn ? `${f.fn} (${f.file}:${f.line}:${f.column})` : `${f.file}:${f.line}:${f.column}`}`,\n  );\n  // The top of the stack — where it failed — is the part kept.\n  out[EXCEPTION_STACKTRACE] = bound(\n    redactSecrets([header, ...lines].join(\"\\n\")),\n    MAX_STACKTRACE_CHARS,\n  );\n  const origin = frames.find(isApplicationFrame) ?? frames[0];\n  if (origin) {\n    out[CODE_FUNCTION] = frameFunction(origin);\n    out[CODE_FILE] = origin.file;\n    out[CODE_LINE] = origin.line;\n  }\n  return out;\n}\n"]}

package/dist/node-otlp.d.ts

@@ -0,0 +1,168 @@
+/** An attribute value a record or span may carry. */
+export type AttributeValue = string | number | boolean | ReadonlyArray<string> | ReadonlyArray<number> | ReadonlyArray<boolean>;
+export type Attributes = Record<string, AttributeValue | undefined>;
+/** Most attributes on one record or span; the rest are dropped. */
+export declare const MAX_ATTRIBUTES = 128;
+/** Longest string attribute value. */
+export declare const MAX_ATTRIBUTE_CHARS = 4096;
+interface AnyValue {
+    stringValue?: string;
+    boolValue?: boolean;
+    intValue?: string;
+    doubleValue?: number;
+    arrayValue?: {
+        values: AnyValue[];
+    };
+}
+export interface KeyValue {
+    key: string;
+    value: AnyValue;
+}
+/** OTLP KeyValues for `attrs`: bounded, unencodable values dropped. */
+export declare function encodeAttributes(attrs: Attributes | undefined): KeyValue[];
+/** Nanoseconds since the epoch for `ms` (fractional ms allowed), as OTLP's decimal string. */
+export declare function unixNanos(ms: number): string;
+/** Now, in epoch milliseconds with sub-millisecond precision. */
+export declare function nowMs(): number;
+/** OTel severity numbers (logs data model). */
+export declare const SEVERITY: {
+    readonly DEBUG: 5;
+    readonly INFO: 9;
+    readonly WARN: 13;
+    readonly ERROR: 17;
+};
+export type SeverityText = keyof typeof SEVERITY;
+/** One log record, as OTLP/JSON. */
+export interface LogRecord {
+    timeUnixNano: string;
+    observedTimeUnixNano: string;
+    severityNumber: number;
+    severityText: SeverityText;
+    body: {
+        stringValue: string;
+    };
+    attributes: KeyValue[];
+    traceId?: string;
+    spanId?: string;
+    flags?: number;
+}
+/** One finished span, as OTLP/JSON. */
+export interface SpanRecord {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: KeyValue[];
+    droppedAttributesCount?: number;
+    events: Array<{
+        timeUnixNano: string;
+        name: string;
+        attributes: KeyValue[];
+    }>;
+    links: Array<{
+        traceId: string;
+        spanId: string;
+        attributes: KeyValue[];
+    }>;
+    status: {
+        code: number;
+        message?: string;
+    };
+    /** Grouping key for scopeSpans; not on the wire. */
+    scope: Scope;
+}
+export interface Scope {
+    name: string;
+    version?: string;
+}
+/** The ExportLogsServiceRequest body for one batch. */
+export declare function logsPayload(resource: KeyValue[], scope: Scope, records: LogRecord[]): {
+    resourceLogs: {
+        resource: {
+            attributes: KeyValue[];
+        };
+        scopeLogs: {
+            scope: Scope;
+            logRecords: LogRecord[];
+        }[];
+    }[];
+};
+/** The ExportTraceServiceRequest body for one batch, spans grouped by scope. */
+export declare function tracesPayload(resource: KeyValue[], spans: SpanRecord[]): {
+    resourceSpans: {
+        resource: {
+            attributes: KeyValue[];
+        };
+        scopeSpans: {
+            scope: Scope;
+            spans: Omit<SpanRecord, "scope">[];
+        }[];
+    }[];
+};
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+}>;
+export interface ExporterOptions {
+    /** The OTLP base: `${endpoint}/v1/logs`, `${endpoint}/v1/traces`. */
+    endpoint: string;
+    /** Sent on every request. The keyed ingest requires an allowlisted `Origin`. */
+    headers: Record<string, string>;
+    fetch: FetchLike;
+    /** One request's budget. */
+    timeoutMs: number;
+    /** Retries after the first attempt, on a network error, 429 or 5xx gateway answer. */
+    retries: number;
+    /** Told about a batch that was dropped; never about one that landed. */
+    onError?: (error: Error) => void;
+    /** Test seam for the backoff wait. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Longest backoff between attempts, whatever Retry-After asks for. */
+export declare const MAX_RETRY_DELAY_MS = 5000;
+/**
+ * Posts one OTLP/JSON body to `${endpoint}/v1/<signal>`. Resolves true when
+ * the collector accepted it, false when it was dropped (after the retries);
+ * never rejects.
+ */
+export declare function exportSignal(opts: ExporterOptions, signal: "logs" | "traces", body: unknown): Promise<boolean>;
+export interface BatchOptions<T> {
+    /** Most items held; a push beyond it is dropped and counted. */
+    maxQueue: number;
+    /** Most items in one export. */
+    maxBatch: number;
+    /** How long an item may wait for a batch to fill. */
+    delayMs: number;
+    send(items: T[]): Promise<unknown>;
+}
+/**
+ * A bounded queue that exports in batches: when a batch fills, when the delay
+ * after the first queued item elapses, or on flush(). Its timer is unref'd, so
+ * a pending batch never keeps a process alive by itself.
+ */
+export declare class BatchQueue<T> {
+    private readonly opts;
+    private items;
+    private timer;
+    private inflight;
+    /** Items refused because the queue was full. */
+    dropped: number;
+    constructor(opts: BatchOptions<T>);
+    get size(): number;
+    push(item: T): void;
+    /** Start exporting everything queued now, without waiting for it. */
+    drain(): void;
+    /** Export everything queued and wait for every export in flight. */
+    flush(): Promise<void>;
+}
+export {};