@superblocksteam/sdk 2.0.114 → 2.0.115-next.1

package/src/dev-utils/vite-dev-server-diagnostics.mts

@@ -0,0 +1,213 @@
+/**
+ * Helpers to classify Vite / esbuild stderr and emit logs that are easy to facet in Datadog
+ * (stable tokens: sdk_dev_server_vite_error, category=module_resolve, unresolved_specifier=...).
+ */
+
+/** Maximum characters of raw Vite/esbuild output stored on the error meta stack field. */
+export const VITE_ERROR_RAW_LOG_MAX_CHARS = 12_000;
+
+export type ViteBuildErrorDiagnostic =
+  | {
+      category: "module_resolve";
+      /** Package specifier esbuild could not resolve, when detected. */
+      unresolvedSpecifier: string;
+    }
+  | {
+      category: "optimize_deps" | "unknown";
+      unresolvedSpecifier?: undefined;
+    };
+
+type BuildViteBuildErrorLogDeps = {
+  diagnose: typeof diagnoseViteBuildLogMessage;
+  formatSummary: typeof formatViteBuildErrorLogSummary;
+  errorKind: typeof viteErrorKindForDiagnostic;
+  truncate: typeof truncateViteRawLog;
+};
+
+type BuildViteBuildErrorLogParams = {
+  rawMessage: string;
+  sdkVersion: string;
+  viteRootBasename: string;
+};
+
+function quoteFacetValue(value: string): string {
+  if (/^[A-Za-z0-9@._:/-]+$/.test(value)) {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Best-effort parse of Vite/esbuild multi-line error text (optimizeDeps, build, etc.).
+ */
+export function diagnoseViteBuildLogMessage(
+  msg: string,
+): ViteBuildErrorDiagnostic {
+  const resolveMatch = msg.match(/Could not resolve ['"]([^'"]+)['"]/);
+  if (resolveMatch?.[1]) {
+    return {
+      category: "module_resolve",
+      unresolvedSpecifier: resolveMatch[1],
+    };
+  }
+  if (/\boptimizeDeps\b|pre-bundl/i.test(msg)) {
+    return { category: "optimize_deps" };
+  }
+  return { category: "unknown" };
+}
+
+export function formatViteDevServerStartedLog(params: {
+  sdkVersion: string;
+  viteRootBasename: string;
+}): string {
+  return `sdk_dev_server_vite_ready sdk_version=${quoteFacetValue(params.sdkVersion)} vite_root=${quoteFacetValue(params.viteRootBasename)}`;
+}
+
+export function formatViteBuildErrorLogSummary(params: {
+  diagnostic: ViteBuildErrorDiagnostic;
+  sdkVersion: string;
+  viteRootBasename: string;
+}): string {
+  const { diagnostic, sdkVersion, viteRootBasename } = params;
+  const parts = [
+    "sdk_dev_server_vite_error",
+    `sdk_version=${quoteFacetValue(sdkVersion)}`,
+    `vite_root=${quoteFacetValue(viteRootBasename)}`,
+    `category=${diagnostic.category}`,
+  ];
+  if (diagnostic.unresolvedSpecifier) {
+    parts.push(
+      `unresolved_specifier=${quoteFacetValue(diagnostic.unresolvedSpecifier)}`,
+    );
+  }
+  return parts.join(" ");
+}
+
+export function viteErrorKindForDiagnostic(
+  diagnostic: ViteBuildErrorDiagnostic,
+): string {
+  switch (diagnostic.category) {
+    case "module_resolve":
+      return "ViteModuleResolveError";
+    case "optimize_deps":
+      return "ViteOptimizeDepsError";
+    case "unknown":
+      return "ViteBuildError";
+  }
+
+  throw new Error(
+    `Unhandled Vite build diagnostic category: ${String((diagnostic as { category?: unknown }).category)}`,
+  );
+}
+
+export function truncateViteRawLog(msg: string): string {
+  if (msg.length <= VITE_ERROR_RAW_LOG_MAX_CHARS) {
+    return msg;
+  }
+  return `${msg.slice(0, VITE_ERROR_RAW_LOG_MAX_CHARS)}\n...(truncated)`;
+}
+
+function defaultBuildSummary(params: BuildViteBuildErrorLogParams): string {
+  return formatViteBuildErrorLogSummary({
+    diagnostic: { category: "unknown" },
+    sdkVersion: params.sdkVersion,
+    viteRootBasename: params.viteRootBasename,
+  });
+}
+
+function diagnosticsFailureMeta(error: unknown, rawMessage: string) {
+  return {
+    error: {
+      kind: "ViteDiagnosticsError",
+      message: error instanceof Error ? error.message : "unknown",
+      stack: truncateViteRawLog(rawMessage),
+    },
+  };
+}
+
+export function buildViteBuildErrorLog(
+  params: BuildViteBuildErrorLogParams,
+  overrides?: Partial<BuildViteBuildErrorLogDeps>,
+): {
+  error: {
+    kind: string;
+    message: string;
+    stack: string;
+  };
+  message: string;
+} {
+  const deps: BuildViteBuildErrorLogDeps = {
+    diagnose: diagnoseViteBuildLogMessage,
+    errorKind: viteErrorKindForDiagnostic,
+    formatSummary: formatViteBuildErrorLogSummary,
+    truncate: truncateViteRawLog,
+    ...overrides,
+  };
+
+  try {
+    const diagnostic = deps.diagnose(params.rawMessage);
+    return {
+      error: {
+        kind: deps.errorKind(diagnostic),
+        message:
+          diagnostic.category === "module_resolve"
+            ? `Could not resolve: ${diagnostic.unresolvedSpecifier}`
+            : "Vite or esbuild reported an error",
+        stack: deps.truncate(params.rawMessage),
+      },
+      message: deps.formatSummary({
+        diagnostic,
+        sdkVersion: params.sdkVersion,
+        viteRootBasename: params.viteRootBasename,
+      }),
+    };
+  } catch {
+    // Keep the final fallback independent from injected helpers so a helper bug
+    // cannot prevent us from returning some structured error payload at all.
+    return {
+      error: {
+        kind: "ViteBuildError",
+        message: "Vite or esbuild reported an error",
+        stack: truncateViteRawLog(params.rawMessage),
+      },
+      message: defaultBuildSummary(params),
+    };
+  }
+}
+
+export function logViteBuildError(
+  logger: {
+    error: (
+      message: string,
+      meta?: {
+        error: {
+          kind: string;
+          message: string;
+          stack?: string;
+        };
+      },
+    ) => void;
+  },
+  params: BuildViteBuildErrorLogParams,
+  overrides?: {
+    build?: typeof buildViteBuildErrorLog;
+  },
+): void {
+  const build = overrides?.build ?? buildViteBuildErrorLog;
+
+  try {
+    const viteErrorLog = build(params);
+    logger.error(viteErrorLog.message, {
+      error: viteErrorLog.error,
+    });
+  } catch (error) {
+    try {
+      logger.error(
+        params.rawMessage,
+        diagnosticsFailureMeta(error, params.rawMessage),
+      );
+    } catch {
+      // Prevent exceptions from propagating into Vite's logger internals.
+    }
+  }
+}

package/src/telemetry/logging.test.ts

@@ -0,0 +1,142 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const {
+  emitMock,
+  winstonErrorMock,
+  winstonLoggerMock,
+  sanitizeLogMessageMock,
+  sanitizeLogErrorMock,
+} = vi.hoisted(() => {
+  const emitMock = vi.fn();
+  const winstonErrorMock = vi.fn();
+  const winstonLoggerMock = {
+    debug: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: winstonErrorMock,
+  };
+
+  const sanitizeLogMessageMock = vi.fn(
+    (message: string) => `sanitized-message:${message}`,
+  );
+  const sanitizeLogErrorMock = vi.fn(
+    (error: { kind: string; message: string; stack?: string }) => ({
+      ...error,
+      message: `sanitized-error:${error.message}`,
+      stack: error.stack ? `sanitized-error:${error.stack}` : undefined,
+    }),
+  );
+
+  return {
+    emitMock,
+    winstonErrorMock,
+    winstonLoggerMock,
+    sanitizeLogMessageMock,
+    sanitizeLogErrorMock,
+  };
+});
+
+vi.mock("@superblocksteam/telemetry", () => ({
+  sanitizeLogMessage: sanitizeLogMessageMock,
+  sanitizeLogError: sanitizeLogErrorMock,
+}));
+
+vi.mock("./index.js", () => ({
+  getLogger: vi.fn(() => ({
+    emit: emitMock,
+  })),
+}));
+
+vi.mock("winston", () => ({
+  createLogger: vi.fn(() => winstonLoggerMock),
+  format: {
+    combine: vi.fn(() => ({})),
+    timestamp: vi.fn(() => ({})),
+    json: vi.fn(() => ({})),
+    printf: vi.fn(() => ({})),
+    colorize: vi.fn(() => ({})),
+  },
+  transports: {
+    File: class {
+      constructor() {}
+    },
+    Console: class {
+      constructor() {}
+    },
+  },
+}));
+
+import { getLogger } from "./logging.js";
+
+describe("telemetry logger error sanitization", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it.each(["debug", "info", "warn"] as const)(
+    "sanitizes %s-level messages before emit and winston",
+    (level) => {
+      const logger = getLogger();
+      logger[level]("api_key=secret");
+      expect(sanitizeLogMessageMock).toHaveBeenCalledWith("api_key=secret");
+    },
+  );
+
+  it("sanitizes error meta for traced emit and winston output", () => {
+    const logger = getLogger();
+    const meta = {
+      error: {
+        kind: "RuntimeError",
+        message: "token=super-secret-token",
+        stack: "Error: token=super-secret-token",
+      },
+    };
+
+    logger.error("api_key=super-secret-key", meta);
+
+    expect(sanitizeLogMessageMock).toHaveBeenCalledWith(
+      "api_key=super-secret-key",
+    );
+    expect(sanitizeLogErrorMock).toHaveBeenCalledWith(meta.error);
+    expect(emitMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: "sanitized-message:api_key=super-secret-key",
+        attributes: {
+          error: {
+            kind: "RuntimeError",
+            message: "sanitized-error:token=super-secret-token",
+            stack: "sanitized-error:Error: token=super-secret-token",
+          },
+        },
+      }),
+    );
+    expect(winstonErrorMock).toHaveBeenCalledWith(
+      "sanitized-message:api_key=super-secret-key",
+      {
+        error: {
+          kind: "RuntimeError",
+          message: "sanitized-error:token=super-secret-token",
+          stack: "sanitized-error:Error: token=super-secret-token",
+        },
+      },
+    );
+  });
+
+  it("does not sanitize or emit error attributes when meta is missing", () => {
+    const logger = getLogger();
+
+    logger.error("plain failure");
+
+    expect(sanitizeLogMessageMock).toHaveBeenCalledWith("plain failure");
+    expect(sanitizeLogErrorMock).not.toHaveBeenCalled();
+    expect(emitMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        body: "sanitized-message:plain failure",
+        attributes: undefined,
+      }),
+    );
+    expect(winstonErrorMock).toHaveBeenCalledWith(
+      "sanitized-message:plain failure",
+    );
+  });
+});

package/src/telemetry/logging.ts

@@ -3,20 +3,32 @@ import type { AnyValueMap } from "@opentelemetry/api-logs";
 import { createLogger, format, transports } from "winston";
 import type winston from "winston";
 
+import {
+  sanitizeLogError,
+  sanitizeLogMessage,
+} from "@superblocksteam/telemetry";
+
 import { getLogger as getTracedLogger } from "./index.js";
 import { safeStringify } from "./safe-stringify.js";
 
 const activeTransports: winston.transport[] = [];
 
 if (process.env.SUPERBLOCKS_IS_CSB === "true") {
-  // TODO(alex): Revisit this for cloud-prem if we want logger to write to stdout
+  // info to stdout for cluster log shippers / kubectl logs;
+  // debug stays in /tmp/dev-server.log for on-pod triage
   activeTransports.push(
     new transports.File({
-      format: format.json(),
+      format: format.combine(format.timestamp(), format.json()),
       filename: `/tmp/dev-server.log`,
       level: "debug",
     }),
   );
+  activeTransports.push(
+    new transports.Console({
+      format: format.combine(format.timestamp(), format.json()),
+      level: process.env.SUPERBLOCKS_SDK_LOG_LEVEL ?? "info",
+    }),
+  );
 } else {
   // having no transport increases memory usage
   activeTransports.push(
@@ -43,6 +55,7 @@ const winstonLogger = createLogger({
   level: "debug",
   exitOnError: false,
   format: format.json(),
+  defaultMeta: { process: "child" },
   transports: activeTransports,
 });
 
@@ -67,7 +80,7 @@ function formatMessages(messages: unknown[]): string {
 
 const logger: Logger = Object.freeze({
   debug: (...messages: unknown[]) => {
-    const body = formatMessages(messages);
+    const body = sanitizeLogMessage(formatMessages(messages));
     getTracedLogger().emit({
       severityNumber: SeverityNumber.DEBUG,
       severityText: "DEBUG",
@@ -76,7 +89,7 @@ const logger: Logger = Object.freeze({
     winstonLogger.debug(body);
   },
   info: (...messages: unknown[]) => {
-    const body = formatMessages(messages);
+    const body = sanitizeLogMessage(formatMessages(messages));
     getTracedLogger().emit({
       severityNumber: SeverityNumber.INFO,
       severityText: "INFO",
@@ -85,7 +98,7 @@ const logger: Logger = Object.freeze({
     winstonLogger.info(body);
   },
   warn: (...messages: unknown[]) => {
-    const body = formatMessages(messages);
+    const body = sanitizeLogMessage(formatMessages(messages));
     getTracedLogger().emit({
       severityNumber: SeverityNumber.WARN,
       severityText: "WARN",
@@ -94,16 +107,23 @@ const logger: Logger = Object.freeze({
     winstonLogger.warn(body);
   },
   error: (message: string, meta?: ErrorMeta) => {
+    const safeMessage = sanitizeLogMessage(message);
+    const safeError = meta?.error
+      ? (({ kind, message, stack }) => ({ kind, message, stack }))(
+          sanitizeLogError(meta.error) as ErrorMeta["error"],
+        )
+      : undefined;
+    const safeMeta = safeError ? { error: safeError } : undefined;
     getTracedLogger().emit({
       severityNumber: SeverityNumber.ERROR,
       severityText: "ERROR",
-      body: message,
-      attributes: meta as unknown as AnyValueMap | undefined,
+      body: safeMessage,
+      attributes: safeMeta as unknown as AnyValueMap | undefined,
     });
-    if (meta) {
-      winstonLogger.error(message, { error: meta.error });
+    if (safeError) {
+      winstonLogger.error(safeMessage, { error: safeError });
     } else {
-      winstonLogger.error(message);
+      winstonLogger.error(safeMessage);
     }
   },
 });