@module-federation/observability-plugin 0.0.0-alpha.0

package/dist/esm/node.js

@@ -0,0 +1,156 @@
+import { ObservabilityPlugin as ObservabilityPlugin$1 } from "./index.js";
+
+//#region src/node.ts
+const DEFAULT_NODE_DIRECTORY = ".mf/observability";
+const DEFAULT_LATEST_FILE = "latest.json";
+const DEFAULT_EVENTS_FILE = "events.jsonl";
+let nodeOutputModulesPromise;
+function getNodeProcess() {
+	return globalThis.process;
+}
+function isNodeEnvironment() {
+	return Boolean(getNodeProcess()?.versions?.node);
+}
+function getNativeNodeRequire() {
+	if (typeof __non_webpack_require__ === "function") return __non_webpack_require__;
+	const globalRequire = globalThis.__non_webpack_require__;
+	if (typeof globalRequire === "function") return globalRequire;
+	try {
+		return Function("return typeof require === \"function\" ? require : undefined")();
+	} catch {
+		return;
+	}
+}
+function getRuntimeImport() {
+	try {
+		return Function("specifier", "return import(specifier)");
+	} catch {
+		return;
+	}
+}
+function unwrapDefaultExport(moduleValue) {
+	return moduleValue.default || moduleValue;
+}
+async function getNodeOutputModules() {
+	if (!isNodeEnvironment()) return;
+	if (nodeOutputModulesPromise) return nodeOutputModulesPromise;
+	nodeOutputModulesPromise = (async () => {
+		const nativeRequire = getNativeNodeRequire();
+		if (nativeRequire) try {
+			return {
+				fs: nativeRequire("node:fs"),
+				path: nativeRequire("node:path")
+			};
+		} catch {}
+		const runtimeImport = getRuntimeImport();
+		if (!runtimeImport) return;
+		try {
+			const [fsModule, pathModule] = await Promise.all([runtimeImport("node:fs"), runtimeImport("node:path")]);
+			return {
+				fs: unwrapDefaultExport(fsModule),
+				path: unwrapDefaultExport(pathModule)
+			};
+		} catch {
+			return;
+		}
+	})();
+	return nodeOutputModulesPromise;
+}
+function getNodeOutputConfig(options) {
+	return {
+		directory: options.directory || DEFAULT_NODE_DIRECTORY,
+		latestFile: options.latestFile || DEFAULT_LATEST_FILE,
+		eventsFile: options.eventsFile || DEFAULT_EVENTS_FILE
+	};
+}
+function shouldUseNodeOutput(options) {
+	return options.enabled !== false && options.fileOutput === true && isNodeEnvironment();
+}
+function shouldUseConsole(options) {
+	return options.console !== false;
+}
+function getNodeLatestPathForConsole(options) {
+	const config = getNodeOutputConfig(options);
+	return `${config.directory}/${config.latestFile}`;
+}
+function getNodeEventsPathForConsole(options) {
+	const config = getNodeOutputConfig(options);
+	return `${config.directory}/${config.eventsFile}`;
+}
+function isErrorEvent(event) {
+	return event.status === "error" || event.status === "complete" && Boolean(event.errorName || event.errorMessage);
+}
+function getRawStack(error) {
+	if (error instanceof Error) return error.stack || error.message;
+}
+async function writeNodeOutput(options, event, report) {
+	const modules = await getNodeOutputModules();
+	if (!modules) return;
+	const config = getNodeOutputConfig(options);
+	const cwd = getNodeProcess()?.cwd?.() || ".";
+	const directory = modules.path.isAbsolute(config.directory) ? config.directory : modules.path.resolve(cwd, config.directory);
+	const latestFile = modules.path.join(directory, config.latestFile);
+	const eventsFile = modules.path.join(directory, config.eventsFile);
+	modules.fs.mkdirSync(directory, { recursive: true });
+	modules.fs.writeFileSync(latestFile, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+	modules.fs.appendFileSync(eventsFile, `${JSON.stringify(event)}\n`, "utf8");
+}
+function emitNodeConsoleHint(options, event, report, context, reportedTraceIds, rawStack) {
+	if (!isErrorEvent(event) || !shouldUseConsole(options) || reportedTraceIds.has(report.traceId)) return;
+	reportedTraceIds.add(report.traceId);
+	const lines = [
+		"[Module Federation] Observability report generated",
+		`traceId: ${report.traceId}`,
+		`phase: ${report.failedPhase || event.phase}`
+	];
+	if (report.requestId) lines.push(`requestId: ${report.requestId}`);
+	if (report.errorCode) lines.push(`errorCode: ${report.errorCode}`);
+	if (report.shared?.name) lines.push(`shared: ${report.shared.name}`);
+	if (shouldUseNodeOutput(options)) {
+		lines.push(`latest: ${getNodeLatestPathForConsole(options)}`);
+		lines.push(`events: ${getNodeEventsPathForConsole(options)}`);
+	} else lines.push(`read: observability.getReport(${JSON.stringify(report.traceId)})`);
+	if (options.printRawStack === true && rawStack) lines.push("rawStack:", rawStack);
+	try {
+		console.error(lines.join("\n"));
+	} catch {}
+}
+function ObservabilityPlugin(options = {}) {
+	let nodeWriteQueue = Promise.resolve();
+	const consoleReportedTraceIds = /* @__PURE__ */ new Set();
+	const rawStackByTraceId = /* @__PURE__ */ new Map();
+	const observability = ObservabilityPlugin$1({
+		...options,
+		console: false,
+		browser: void 0,
+		onRawError(error, context) {
+			const rawStack = getRawStack(error);
+			if (rawStack) rawStackByTraceId.set(context.report.traceId, rawStack);
+			options.onRawError?.(error, context);
+		},
+		onEvent(event, report, context) {
+			if (shouldUseNodeOutput(options)) nodeWriteQueue = nodeWriteQueue.catch(() => void 0).then(() => writeNodeOutput(options, event, report)).catch(() => void 0);
+			emitNodeConsoleHint(options, event, report, context, consoleReportedTraceIds, rawStackByTraceId.get(report.traceId));
+			try {
+				options.onEvent?.(event, report, context);
+			} finally {
+				if (isErrorEvent(event)) rawStackByTraceId.delete(report.traceId);
+			}
+		},
+		onReport(report, context) {
+			options.onReport?.(report, context);
+		}
+	});
+	observability.plugin.name = "observability-node-plugin";
+	const clear = observability.clear;
+	observability.clear = () => {
+		clear();
+		nodeWriteQueue = Promise.resolve();
+		consoleReportedTraceIds.clear();
+		rawStackByTraceId.clear();
+	};
+	return observability;
+}
+
+//#endregion
+export { ObservabilityPlugin, getNativeNodeRequire };

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+import { ModuleFederationRuntimePlugin } from "@module-federation/runtime";
+
+//#region src/index.d.ts
+type ObservabilityLevel = 'error' | 'summary' | 'verbose';
+type ObservabilityEventStatus = 'start' | 'success' | 'error' | 'complete';
+type ObservabilityReportStatus = 'pending' | 'success' | 'error';
+type ObservabilityEventSource = 'runtime' | 'business';
+type ObservabilityBrowserMode = 'development' | 'production';
+type ObservabilityReportOutcome = 'pending' | 'runtime-loaded' | 'component-loaded' | 'failed' | 'recovered';
+type ObservabilityOwnerHint = 'host' | 'remote' | 'shared' | 'network' | 'runtime' | 'unknown';
+type ObservabilityMetadataValue = string | number | boolean;
+type ObservabilityMetadata = Record<string, ObservabilityMetadataValue>;
+interface ObservabilityModuleInfoEntry {
+  name: string;
+  publicPath?: string;
+  getPublicPath?: string;
+  remoteEntry?: string;
+  globalName?: string;
+}
+interface ObservabilityModuleInfoSummary {
+  reason: string;
+  clipped: true;
+  totalCount: number;
+  matchedCount: number;
+  entries: ObservabilityModuleInfoEntry[];
+  availableNames?: string[];
+}
+interface ObservabilityPhaseSummary {
+  status: ObservabilityEventStatus;
+  duration?: number;
+  cached?: boolean;
+  recovered?: boolean;
+  lifecycle?: string;
+}
+interface ObservabilitySharedSummary {
+  name: string;
+  provider?: string;
+  selectedVersion?: string;
+  shareScope?: string[];
+}
+interface ObservabilityReportFlags {
+  cached: boolean;
+  retried: boolean;
+  fallback: boolean;
+  recovered: boolean;
+}
+interface ObservabilityPhaseCollection {
+  phases: Record<string, ObservabilityPhaseSummary>;
+  shared?: ObservabilitySharedSummary;
+  flags: ObservabilityReportFlags;
+}
+interface ObservabilityErrorSummary {
+  errorCode?: string;
+  errorName?: string;
+  errorMessage?: string;
+  failedPhase?: string;
+  lifecycle?: string;
+  ownerHint?: ObservabilityOwnerHint;
+  retryable?: boolean;
+  context?: ObservabilityMetadata;
+}
+type ObservabilityActionId = 'check-manifest-url' | 'check-remote-entry' | 'check-remote-global' | 'check-host-remotes' | 'check-shared-provider' | 'check-shared-version' | 'check-eager-config' | 'check-network' | 'check-expose' | 'check-module-info' | 'inspect-runtime-events';
+interface ObservabilityAction {
+  id: ObservabilityActionId | string;
+  ownerHint?: ObservabilityOwnerHint;
+  title: string;
+  detail?: string;
+}
+interface ObservabilityFactReport {
+  title: string;
+  outcome: ObservabilityReportOutcome;
+  status: ObservabilityReportStatus;
+  ownerHint: ObservabilityOwnerHint;
+  failedPhase?: string;
+  errorCode?: string;
+  errorName?: string;
+  errorMessage?: string;
+  docLink?: string;
+  facts: ObservabilityMetadata;
+  completedPhases: string[];
+  pendingPhases: string[];
+  warnings?: string[];
+  actions: ObservabilityAction[];
+}
+interface ObservabilityRemoteInfo {
+  name: string;
+  alias?: string;
+  entry?: string;
+  entryGlobalName?: string;
+  type?: string;
+}
+interface ObservabilitySharedInfo {
+  name: string;
+  shareScope?: string[];
+  requiredVersion?: string | false;
+  selectedVersion?: string;
+  availableVersions?: string[];
+  provider?: string;
+  from?: string;
+  singleton?: boolean;
+  strictVersion?: boolean;
+  eager?: boolean;
+  strategy?: string;
+  loaded?: boolean;
+  loading?: boolean;
+  reason?: string;
+}
+interface ObservabilityEvent {
+  traceId: string;
+  timestamp: number;
+  phase: string;
+  status: ObservabilityEventStatus;
+  requestId?: string;
+  hostName?: string;
+  remote?: ObservabilityRemoteInfo;
+  shared?: ObservabilitySharedInfo;
+  expose?: string;
+  sanitizedUrl?: string;
+  message?: string;
+  errorCode?: string;
+  errorName?: string;
+  errorMessage?: string;
+  errorStack?: string;
+  ownerHint?: ObservabilityOwnerHint;
+  retryable?: boolean;
+  errorContext?: ObservabilityMetadata;
+  duration?: number;
+  lifecycle?: string;
+  eventName?: string;
+  source?: ObservabilityEventSource;
+  recovered?: boolean;
+  cached?: boolean;
+  componentName?: string;
+  metadata?: ObservabilityMetadata;
+}
+interface ObservabilityReport {
+  traceId: string;
+  status: ObservabilityReportStatus;
+  requestId?: string;
+  hostName?: string;
+  remote?: ObservabilityRemoteInfo;
+  shared?: ObservabilitySharedInfo;
+  expose?: string;
+  sanitizedUrl?: string;
+  startedAt: number;
+  updatedAt: number;
+  duration: number;
+  failedPhase?: string;
+  errorCode?: string;
+  errorName?: string;
+  errorMessage?: string;
+  errorStack?: string;
+  ownerHint?: ObservabilityOwnerHint;
+  retryable?: boolean;
+  errorContext?: ObservabilityMetadata;
+  moduleInfo?: ObservabilityModuleInfoSummary;
+  events: ObservabilityEvent[];
+  summary: {
+    eventCount: number;
+    recovered: boolean;
+    loadCompleted: boolean;
+    runtimeLoaded: boolean;
+    componentLoaded: boolean;
+    outcome: ObservabilityReportOutcome;
+    lastPhase?: string;
+    phases: Record<string, ObservabilityPhaseSummary>;
+    shared?: ObservabilitySharedSummary;
+    flags: ObservabilityReportFlags;
+    error?: ObservabilityErrorSummary;
+  };
+  diagnosis?: ObservabilityFactReport;
+}
+interface ObservabilityPluginOptions {
+  enabled?: boolean;
+  level?: ObservabilityLevel;
+  maxEvents?: number;
+  console?: boolean;
+  printRawStack?: boolean;
+  stackTrace?: {
+    enabled?: boolean;
+    maxLines?: number;
+    maxLength?: number;
+  };
+  browser?: {
+    enabled?: boolean;
+    scope?: string;
+    mode?: ObservabilityBrowserMode;
+  };
+  onEvent?: (event: ObservabilityEvent, report: ObservabilityReport, context?: ObservabilityEventContext) => void;
+  onReport?: (report: ObservabilityReport, context?: ObservabilityEventContext) => void;
+  onRawError?: (error: unknown, context: ObservabilityRawErrorContext) => void;
+}
+interface ObservabilityReportListOptions {
+  limit?: number;
+}
+interface ObservabilityReportQuery extends ObservabilityReportListOptions {
+  traceId?: string;
+  remote?: string;
+  expose?: string;
+  shared?: string;
+  status?: ObservabilityReportStatus;
+  outcome?: ObservabilityReportOutcome;
+}
+interface MarkComponentLoadedOptions {
+  traceId?: string;
+  requestId?: string;
+  componentName?: string;
+  metadata?: Record<string, unknown>;
+}
+interface ObservabilityController {
+  plugin: ObservabilityRuntimePlugin;
+  getEvents(): ObservabilityEvent[];
+  getTraceIds(): string[];
+  getReports(options?: ObservabilityReportListOptions): ObservabilityReport[];
+  findReports(query?: ObservabilityReportQuery): ObservabilityReport[];
+  getLatestReport(): ObservabilityReport | undefined;
+  getReport(traceId: string): ObservabilityReport | undefined;
+  exportReport(traceId?: string): ObservabilityReport | undefined;
+  clear(): void;
+  markComponentLoaded(options?: MarkComponentLoadedOptions): ObservabilityEvent | undefined;
+}
+interface ObservabilityRuntimeEventInput {
+  phase: string;
+  status: ObservabilityEventStatus;
+  requestId?: string;
+  hostName?: string;
+  remote?: ObservabilityRemoteInfo;
+  shared?: ObservabilitySharedInfo;
+  expose?: string;
+  url?: string;
+  message?: string;
+  error?: unknown;
+  errorContext?: Record<string, unknown>;
+  duration?: number;
+  lifecycle?: string;
+  eventName?: string;
+  source?: ObservabilityEventSource;
+  recovered?: boolean;
+  timestamp?: number;
+  traceId?: string;
+  cached?: boolean;
+  componentName?: string;
+  metadata?: Record<string, unknown>;
+}
+interface ObservabilityRuntimeOrigin {
+  options?: {
+    name?: string;
+  };
+}
+interface ObservabilityEventContext {
+  origin?: ObservabilityRuntimeOrigin;
+}
+interface ObservabilityRawErrorContext extends ObservabilityEventContext {
+  event: ObservabilityEvent;
+  report: ObservabilityReport;
+}
+type ObservabilityRuntimePlugin = ModuleFederationRuntimePlugin;
+interface ObservabilityBrowserReader {
+  getEvents(): ObservabilityEvent[];
+  getTraceIds(): string[];
+  getReports(options?: ObservabilityReportListOptions): ObservabilityReport[];
+  findReports(query?: ObservabilityReportQuery): ObservabilityReport[];
+  getLatestReport(): ObservabilityReport | undefined;
+  getReport(traceId: string): ObservabilityReport | undefined;
+  exportReport(traceId?: string): ObservabilityReport | undefined;
+}
+declare function ObservabilityPlugin(options?: ObservabilityPluginOptions): ObservabilityController;
+//#endregion
+export { MarkComponentLoadedOptions, ObservabilityAction, ObservabilityActionId, ObservabilityBrowserMode, ObservabilityBrowserReader, ObservabilityController, ObservabilityErrorSummary, ObservabilityEvent, ObservabilityEventContext, ObservabilityEventSource, ObservabilityEventStatus, ObservabilityFactReport, ObservabilityLevel, ObservabilityMetadata, ObservabilityMetadataValue, ObservabilityModuleInfoEntry, ObservabilityModuleInfoSummary, ObservabilityOwnerHint, ObservabilityPhaseCollection, ObservabilityPhaseSummary, ObservabilityPlugin, ObservabilityPluginOptions, ObservabilityRawErrorContext, ObservabilityRemoteInfo, ObservabilityReport, ObservabilityReportFlags, ObservabilityReportListOptions, ObservabilityReportOutcome, ObservabilityReportQuery, ObservabilityReportStatus, ObservabilityRuntimeEventInput, ObservabilityRuntimeOrigin, ObservabilityRuntimePlugin, ObservabilitySharedInfo, ObservabilitySharedSummary };