@logbrew/sdk 0.1.30 → 0.1.32

package/README.md

@@ -697,6 +697,8 @@ await logbrewTransport.flush();
 
 The Winston adapter receives Winston `info` objects, maps `debug`/`silly` to LogBrew `info`, `warn` to `warning`, `error` to `error`, `fatal`/`critical` to `critical`, and other common Winston levels to `info`. It captures primitive info fields as `context.*`, captures nested `err`/`error` objects or formatted error stack name/message, omits stack text unless `includeErrorStack: true` is set, and exposes `onError` for capture failures. It does not mutate Winston globals or replace the app's logger.
 
+Each Winston message is also kept as an issue breadcrumb (category `log.winston`, message capped at 512 characters, no info fields), so the next issue shows the log lines that led to it. With `@logbrew/node`, breadcrumbs written during a request stay with that request's issues. Pass `breadcrumbs: false` to turn this off.
+
 Use the same `traceProvider: getActiveLogBrewTrace` option with LogBrew Node/framework helpers when you want Winston logs to carry the active request trace. The adapter only copies normalized W3C-shaped IDs and sampled state; it does not patch Winston globally or serialize arbitrary active context.
 
 Use a clearly fake placeholder like `LOGBREW_API_KEY` in examples. Call `flush` or `shutdown` to send queued events through a transport, and use `previewJson()` when you want a stable local JSON preview before sending anything.

package/browser-breadcrumbs.cjs

@@ -0,0 +1,194 @@
+"use strict";
+
+const MAX_MESSAGE_LENGTH = 512;
+const MAX_URL_LENGTH = 256;
+const CONSOLE_LEVELS = Object.freeze({
+  debug: "debug",
+  error: "error",
+  info: "info",
+  log: "info",
+  warn: "warning"
+});
+
+// Records console calls, fetch and XHR requests, and route changes as issue breadcrumbs.
+// Browser-safe and shared by @logbrew/browser and @logbrew/next/client. Returns an uninstall function
+// that puts back every patched method it still owns.
+function installBrowserBreadcrumbs(browserWindow, client, {
+  console: captureConsole = true,
+  ignoredUrls = [],
+  navigation = true,
+  network = true
+} = {}) {
+  const ignored = new Set(ignoredUrls.map((url) => sanitizeUrl(url, browserWindow)).filter(Boolean));
+  const add = (breadcrumb) => {
+    try {
+      client.addBreadcrumb(breadcrumb);
+    } catch {
+      // Breadcrumbs are advisory and never reach application code.
+    }
+  };
+  const restores = [];
+  if (captureConsole) {
+    restores.push(...patchConsole(browserWindow.console ?? globalThis.console, add));
+  }
+  if (network) {
+    restores.push(...patchFetch(browserWindow, add, ignored), ...patchXhr(browserWindow, add, ignored));
+  }
+  if (navigation) {
+    restores.push(...patchNavigation(browserWindow, add));
+  }
+  return () => {
+    for (const restore of restores.splice(0).reverse()) {
+      restore();
+    }
+  };
+}
+
+function patchConsole(target, add) {
+  if (!target) {
+    return [];
+  }
+  return Object.entries(CONSOLE_LEVELS).flatMap(([method, level]) => replaceMethod(target, method, (original) => (
+    function logBrewConsoleBreadcrumb(...args) {
+      const message = boundedText(consoleTemplate(args), MAX_MESSAGE_LENGTH);
+      if (message) {
+        add({ type: "debug", category: "console", level, message });
+      }
+      return original.apply(this, args);
+    }
+  )));
+}
+
+function patchFetch(browserWindow, add, ignored) {
+  return replaceMethod(browserWindow, "fetch", (original) => async function logBrewFetchBreadcrumb(input, init) {
+    const method = String(init?.method ?? input?.method ?? "GET").toUpperCase();
+    const url = sanitizeUrl(typeof input === "string" || input instanceof URL ? input : input?.url, browserWindow);
+    try {
+      const response = await original.call(this, input, init);
+      if (!ignored.has(url)) {
+        add(httpBreadcrumb("fetch", method, url, response?.status));
+      }
+      return response;
+    } catch (error) {
+      if (!ignored.has(url)) {
+        add({ ...httpBreadcrumb("fetch", method, url), level: "error" });
+      }
+      throw error;
+    }
+  });
+}
+
+function patchXhr(browserWindow, add, ignored) {
+  const prototype = browserWindow.XMLHttpRequest?.prototype;
+  if (!prototype) {
+    return [];
+  }
+  const state = new WeakMap();
+  return [
+    ...replaceMethod(prototype, "open", (original) => function logBrewXhrOpen(method, url, ...rest) {
+      state.set(this, { method: String(method ?? "GET").toUpperCase(), url: sanitizeUrl(url, browserWindow) });
+      return original.call(this, method, url, ...rest);
+    }),
+    ...replaceMethod(prototype, "send", (original) => function logBrewXhrSend(...args) {
+      const request = state.get(this);
+      if (request && !ignored.has(request.url) && typeof this.addEventListener === "function") {
+        this.addEventListener("loadend", () => {
+          add(httpBreadcrumb("xhr", request.method, request.url, this.status || undefined));
+        });
+      }
+      return original.apply(this, args);
+    })
+  ];
+}
+
+function patchNavigation(browserWindow, add) {
+  const history = browserWindow.history;
+  if (!history) {
+    return [];
+  }
+  let from = currentPath(browserWindow);
+  const record = () => {
+    const to = currentPath(browserWindow);
+    if (to && to !== from) {
+      add({ type: "navigation", category: "navigation", data: { ...(from ? { from } : {}), to } });
+      from = to;
+    }
+  };
+  const restores = ["pushState", "replaceState"].flatMap((method) => replaceMethod(history, method, (original) => (
+    function logBrewNavigationBreadcrumb(...args) {
+      const result = original.apply(this, args);
+      record();
+      return result;
+    }
+  )));
+  if (typeof browserWindow.addEventListener === "function") {
+    browserWindow.addEventListener("popstate", record);
+    restores.push(() => browserWindow.removeEventListener?.("popstate", record));
+  }
+  return restores;
+}
+
+function replaceMethod(target, name, wrap) {
+  const original = target?.[name];
+  if (typeof original !== "function") {
+    return [];
+  }
+  const replacement = wrap(original);
+  target[name] = replacement;
+  return [() => {
+    if (target[name] === replacement) {
+      target[name] = original;
+    }
+  }];
+}
+
+function httpBreadcrumb(category, method, url, status) {
+  const statusCode = Number.isInteger(status) && status > 0 ? status : undefined;
+  return {
+    type: "http",
+    category,
+    level: statusCode === undefined || statusCode < 400 ? "info" : statusCode >= 500 ? "error" : "warning",
+    data: {
+      method: method.slice(0, 16) || "GET",
+      ...(url ? { url } : {}),
+      ...(statusCode === undefined ? {} : { status_code: statusCode })
+    }
+  };
+}
+
+// Records the message template, never the interpolated arguments.
+function consoleTemplate(args) {
+  const [first] = args;
+  if (typeof first === "string") {
+    return first;
+  }
+  return first instanceof Error ? first.name || "Error" : "";
+}
+
+function currentPath(browserWindow) {
+  const pathname = browserWindow.location?.pathname;
+  return typeof pathname === "string" ? boundedText(pathname, MAX_URL_LENGTH) : undefined;
+}
+
+// Keeps scheme, host, and path; drops user info, query, and fragment.
+function sanitizeUrl(value, browserWindow) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  try {
+    const url = new URL(String(value), String(browserWindow.location?.href ?? "http://localhost/"));
+    return boundedText(`${url.protocol}//${url.host}${url.pathname}`, MAX_URL_LENGTH) || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function boundedText(value, limit) {
+  const characters = Array.from(String(value), (character) => {
+    const code = character.codePointAt(0);
+    return code <= 31 || (code >= 127 && code <= 159) ? " " : character;
+  });
+  return Array.from(characters.join("").replace(/\s+/gu, " ").trim()).slice(0, limit).join("");
+}
+
+module.exports = { installBrowserBreadcrumbs };

package/core.cjs

@@ -97,6 +97,8 @@ const MAX_CLIENT_REPORT_COUNT = 1_000_000_000;
 const DELIVERY_HEALTH_SCHEMA_VERSION = 1;
 const EVENT_QUEUE_FACTORY = Symbol.for("@logbrew/sdk.eventQueueFactory");
 const CONTEXT_PROVIDER = Symbol.for("@logbrew/sdk.contextProvider");
+// Runtime packages supply request-scoped breadcrumbs through this seam; core merges them into issues.
+const BREADCRUMB_PROVIDER = Symbol.for("@logbrew/sdk.breadcrumbProvider");
 const MAX_ERROR_CAUSES = 5;
 const BUILTIN_ERROR_NAMES = new Set([
   "AggregateError",
@@ -216,6 +218,7 @@ class LogBrewClient {
     sdkVersion,
     context,
     [CONTEXT_PROVIDER]: contextProvider,
+    [BREADCRUMB_PROVIDER]: breadcrumbProvider,
     maxRetries = 2,
     eventFilter,
     maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
@@ -237,6 +240,9 @@ class LogBrewClient {
     if (contextProvider !== undefined && typeof contextProvider !== "function") {
       throw new SdkError("validation_error", "context provider must be a function");
     }
+    if (breadcrumbProvider !== undefined && typeof breadcrumbProvider !== "function") {
+      throw new SdkError("validation_error", "breadcrumb provider must be a function");
+    }
     requireNonNegativeInteger("maxRetries", maxRetries);
     if (eventFilter !== undefined && typeof eventFilter !== "function") {
       throw new SdkError("validation_error", "eventFilter must be a function");
@@ -286,6 +292,7 @@ class LogBrewClient {
       onEventDropped,
       context: clientContext,
       contextProvider,
+      breadcrumbProvider,
       sdk: {
         name: sdkName,
         language: "javascript",
@@ -308,6 +315,7 @@ class LogBrewClient {
     onEventDropped,
     context,
     contextProvider,
+    breadcrumbProvider,
     eventStore,
     eventQueueFactory,
     transport,
@@ -327,6 +335,7 @@ class LogBrewClient {
     this.onEventDropped = onEventDropped;
     this.context = cloneTelemetryContext(context);
     this.contextProvider = contextProvider;
+    this.breadcrumbProvider = breadcrumbProvider;
     this.transport = transport;
     this.sdk = sdk;
     this.maxRetries = maxRetries;
@@ -632,20 +641,46 @@ class LogBrewClient {
   }
 
   #pushIssue(id, timestamp, attributes) {
-    const withBreadcrumbs = attributes.breadcrumbs !== undefined || this.issueBreadcrumbs.length === 0
+    if (attributes.breadcrumbs !== undefined) {
+      return this.#pushEvent("issue", id, timestamp, validateIssue(attributes));
+    }
+    const provided = this.#providedBreadcrumbs();
+    const merged = provided.breadcrumbs.length === 0
+      ? this.issueBreadcrumbs
+      : [...this.issueBreadcrumbs, ...provided.breadcrumbs]
+        .sort((left, right) => Date.parse(left.timestamp) - Date.parse(right.timestamp));
+    const breadcrumbs = merged.slice(-MAX_ISSUE_BREADCRUMBS);
+    const truncated = attributes.breadcrumbsTruncated === true || this.issueBreadcrumbsTruncated
+      || provided.truncated || merged.length > breadcrumbs.length;
+    const withBreadcrumbs = breadcrumbs.length === 0
       ? attributes
-      : {
-          ...attributes,
-          breadcrumbs: this.issueBreadcrumbs,
-          ...(
-            attributes.breadcrumbsTruncated === true || this.issueBreadcrumbsTruncated
-              ? { breadcrumbsTruncated: true }
-              : {}
-          )
-        };
+      : { ...attributes, breadcrumbs, ...(truncated ? { breadcrumbsTruncated: true } : {}) };
     return this.#pushEvent("issue", id, timestamp, validateIssue(withBreadcrumbs));
   }
 
+  // Provider failures and invalid entries never cost the issue itself.
+  #providedBreadcrumbs() {
+    let provided;
+    try {
+      provided = this.breadcrumbProvider?.();
+    } catch {
+      return { breadcrumbs: [], truncated: false };
+    }
+    if (!provided || !Array.isArray(provided.breadcrumbs)) {
+      return { breadcrumbs: [], truncated: false };
+    }
+    const breadcrumbs = [];
+    let truncated = provided.truncated === true || provided.breadcrumbs.length > MAX_ISSUE_BREADCRUMBS;
+    for (const breadcrumb of provided.breadcrumbs.slice(-MAX_ISSUE_BREADCRUMBS)) {
+      try {
+        breadcrumbs.push(validateIssueBreadcrumb(breadcrumb));
+      } catch {
+        truncated = true;
+      }
+    }
+    return { breadcrumbs, truncated };
+  }
+
   #pushEvent(eventType, id, timestamp, attributes) {
     if (this.closed) {
       throw new SdkError("shutdown_error", "client is already shut down");
@@ -2829,8 +2864,11 @@ function formatConsoleArgument(value, includeErrorStack) {
   }
 }
 
+const { installBrowserBreadcrumbs } = require("./browser-breadcrumbs.cjs");
+
 module.exports = {
   PRODUCT_ANALYTICS_KINDS,
+  installBrowserBreadcrumbs,
   PRODUCT_ANALYTICS_SCHEMA_VERSION,
   createBaggage,
   createIssueAttributesFromError,

package/index.d.ts

@@ -535,6 +535,8 @@ export type WinstonLogInfo = Record<string, unknown> & {
 /** Configuration for the dependency-free Winston transport adapter. */
 export type WinstonTransportConfig = {
   client: LogBrewClient;
+  /** Record each Winston message as an issue breadcrumb (category `log.winston`). Defaults to true. */
+  breadcrumbs?: boolean;
   logger?: string;
   metadata?: Metadata;
   traceProvider?: () => LogCorrelationTraceContext | null | undefined;
@@ -925,6 +927,25 @@ export declare class LogBrewClient {
 /** Install explicit console capture while preserving the target console's normal output behavior. */
 export declare function installLogBrewConsoleCapture(config: ConsoleCaptureConfig): ConsoleCaptureHandle;
 
+/** Options for automatic browser breadcrumbs. Every source defaults to true. */
+export type BrowserBreadcrumbOptions = {
+  console?: boolean;
+  network?: boolean;
+  navigation?: boolean;
+  /** URLs whose requests are not recorded, such as the LogBrew ingest endpoint. */
+  ignoredUrls?: string[];
+};
+
+/**
+ * Record console calls, fetch and XHR requests, and route changes in a browser window as issue
+ * breadcrumbs on the client. The wrappers only observe calls. Returns an uninstall function.
+ */
+export declare function installBrowserBreadcrumbs(
+  browserWindow: unknown,
+  client: LogBrewClient,
+  options?: BrowserBreadcrumbOptions
+): () => void;
+
 /** Create safe action attributes for an app-owned product step without automatic UI capture. */
 export declare function createProductActionAttributes(
   action: ProductActionInput,

package/index.js

@@ -16,6 +16,7 @@ export const {
   createTracestate,
   createLogBrewPinoDestination,
   createLogBrewWinstonTransport,
+  installBrowserBreadcrumbs,
   installLogBrewConsoleCapture,
   LogBrewClient,
   logbrewTraceContextFromCurrentOpenTelemetrySpan,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logbrew/sdk",
-  "version": "0.1.30",
+  "version": "0.1.32",
   "description": "Public LogBrew JavaScript SDK for building, validating, and flushing event batches.",
   "type": "module",
   "main": "./index.cjs",
@@ -43,6 +43,7 @@
   },
   "files": [
     "index.cjs",
+    "browser-breadcrumbs.cjs",
     "core.cjs",
     "index.js",
     "index.d.ts",

package/react-native.d.ts

@@ -81,6 +81,7 @@ export {
   createTraceparent,
   createTraceparentHeaders,
   createTracestate,
+  installBrowserBreadcrumbs,
   installLogBrewConsoleCapture,
   LogBrewClient,
   logAttributesFromConsoleArgs,

package/react-native.js

@@ -3,6 +3,7 @@ import sdk from "./core.cjs";
 export const {
   PRODUCT_ANALYTICS_KINDS,
   PRODUCT_ANALYTICS_SCHEMA_VERSION,
+  installBrowserBreadcrumbs,
   createBaggage,
   createIssueAttributesFromError,
   createNetworkMilestoneAttributes,

package/winston.cjs

@@ -3,6 +3,10 @@ const { Writable } = require("node:stream");
 const { LogBrewClient, SdkError } = require("./core.cjs");
 const { buildLogContextHelpers } = require("./log-context.cjs");
 
+// Runtime packages with request scopes (such as @logbrew/node) register a recorder that keeps
+// breadcrumbs with the active request instead of the whole client.
+const BREADCRUMB_RECORDER = Symbol.for("@logbrew/sdk.breadcrumbRecorder");
+const MAX_BREADCRUMB_MESSAGE_LENGTH = 512;
 const WINSTON_RESERVED_FIELDS = new Set([
   "level",
   "message",
@@ -30,6 +34,7 @@ function createLogBrewWinstonTransport(config) {
   }
 
   const transport = config.transport;
+  const breadcrumbs = config.breadcrumbs !== false;
   const flushOnWrite = config.flushOnWrite === true;
   const includeErrorStack = config.includeErrorStack === true;
   const logger = config.logger ?? "winston";
@@ -49,6 +54,9 @@ function createLogBrewWinstonTransport(config) {
     objectMode: true,
     write(info, _encoding, callback) {
       try {
+        if (breadcrumbs) {
+          recordWinstonBreadcrumb(client, info);
+        }
         captureWinstonInfo({
           client,
           eventIdPrefix,
@@ -128,6 +136,49 @@ function captureWinstonInfo(config) {
   }
 }
 
+function recordWinstonBreadcrumb(client, info) {
+  if (!info || Array.isArray(info) || typeof info !== "object" || info.silent === true) {
+    return;
+  }
+  const breadcrumb = {
+    type: "debug",
+    category: "log.winston",
+    level: winstonBreadcrumbLevel(info.level),
+    message: Array.from(winstonMessage(info)).slice(0, MAX_BREADCRUMB_MESSAGE_LENGTH).join("")
+  };
+  const recorder = client.breadcrumbProvider ? globalThis[BREADCRUMB_RECORDER] : undefined;
+  try {
+    if (typeof recorder === "function") {
+      recorder(breadcrumb);
+    } else {
+      client.addBreadcrumb(breadcrumb);
+    }
+  } catch {
+    // Breadcrumbs are advisory; the log event below still goes out.
+  }
+}
+
+function winstonBreadcrumbLevel(level) {
+  switch (String(level).toLowerCase()) {
+    case "error":
+    case "crit":
+    case "critical":
+    case "fatal":
+    case "alert":
+    case "emerg":
+      return "error";
+    case "warn":
+    case "warning":
+      return "warning";
+    case "verbose":
+    case "debug":
+    case "silly":
+      return "debug";
+    default:
+      return "info";
+  }
+}
+
 function logAttributesFromWinstonInfo(info, options = {}) {
   if (!info || Array.isArray(info) || typeof info !== "object") {
     throw new SdkError("validation_error", "Winston info must be an object");