@genesislcap/foundation-utils 15.46.5 → 15.46.6-alpha-606571609.0

package/dist/esm/error-monitoring/error-monitoring.js

@@ -0,0 +1,139 @@
+import { __awaiter } from "tslib";
+import { addGlobalLogReporter } from '@genesislcap/foundation-logger';
+import { fetchRuntimeConfig } from '../env/runtime-config';
+import { formatLogArgs } from './format-log-args';
+const REPORTED_LOG_TYPES = new Set(['error', 'fatal']);
+/** consola log types mapped to monitoring severities; anything unlisted is `info`. */
+const BREADCRUMB_LEVELS = {
+    warn: 'warning',
+    debug: 'debug',
+    trace: 'debug',
+    verbose: 'debug',
+};
+const isPlainObject = (value) => typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    !(value instanceof Error) &&
+    Object.getPrototypeOf(value) === Object.prototype;
+const nonEmptyString = (value) => typeof value === 'string' && value ? value : undefined;
+/**
+ * Creates a global log reporter that sends foundation logger output to a monitoring client.
+ *
+ * @remarks
+ * `error` and `fatal` logs become events: an exception when an `Error` was logged, otherwise a
+ * message built with {@link formatLogArgs}. Each is tagged with the logger name, and plain-object
+ * arguments (such as an error boundary's reference ID and component stack) are merged into its
+ * extra data alongside the raw arguments. Other logs become breadcrumbs unless `breadcrumbs` is
+ * `false`. A failing client never breaks logging.
+ *
+ * {@link setupErrorMonitoring} registers this for you; use it directly to wire a client by hand.
+ *
+ * @param client - The monitoring client.
+ * @param options - Set `breadcrumbs: false` to skip breadcrumbs.
+ * @public
+ */
+export const createErrorMonitoringReporter = (client, { breadcrumbs = true } = {}) => ({
+    log: ({ type, tag, args }) => {
+        var _a, _b;
+        try {
+            if (!REPORTED_LOG_TYPES.has(type)) {
+                if (breadcrumbs) {
+                    (_a = client.addBreadcrumb) === null || _a === void 0 ? void 0 : _a.call(client, {
+                        category: tag || 'logger',
+                        level: (_b = BREADCRUMB_LEVELS[type]) !== null && _b !== void 0 ? _b : 'info',
+                        message: formatLogArgs(args),
+                    });
+                }
+                return;
+            }
+            const context = {
+                level: type === 'fatal' ? 'fatal' : 'error',
+                tags: { logger: tag || 'unknown' },
+                extra: Object.assign(Object.assign({}, Object.assign({}, ...args.filter(isPlainObject))), { args }),
+            };
+            const error = args.find((arg) => arg instanceof Error);
+            if (error) {
+                client.captureException(error, context);
+                return;
+            }
+            const message = formatLogArgs(args);
+            client.captureMessage(tag ? `${tag}: ${message}` : message, context);
+        }
+        catch (_c) {
+            // Monitoring must never break the app's logging.
+        }
+    },
+});
+/**
+ * True for a console breadcrumb written by a foundation logger.
+ *
+ * @remarks
+ * consola's browser output starts with a `%c` badge, and SDKs that record console calls join the
+ * arguments with `String()`, so these breadcrumbs arrive as CSS and `[object Object]`. The
+ * reporter from {@link createErrorMonitoringReporter} records the same logs readably.
+ * @public
+ */
+export const isFoundationLoggerConsoleBreadcrumb = (breadcrumb) => {
+    var _a, _b;
+    const first = (_b = (_a = breadcrumb.data) === null || _a === void 0 ? void 0 : _a.arguments) === null || _b === void 0 ? void 0 : _b[0];
+    return breadcrumb.category === 'console' && typeof first === 'string' && first.startsWith('%c');
+};
+let removeActiveReporter;
+/**
+ * Sets up error monitoring for a Genesis app in one call.
+ *
+ * @remarks
+ * Reads the DSN and environment from per-deployment config (`/env.json` by default) with
+ * {@link fetchRuntimeConfig}, so one image can be promoted across environments. Without a DSN it
+ * does nothing and resolves `false`, as in local development. Otherwise it:
+ *
+ * - initialises the client (`client.init`, or `options.init`) with the DSN, environment,
+ *   `normalizeDepth: 10`, a `beforeBreadcrumb` that drops unreadable foundation logger console
+ *   breadcrumbs, and any `initOptions`;
+ * - registers a global log reporter ({@link createErrorMonitoringReporter}), so errors logged by
+ *   every foundation logger, including those Genesis packages create at import time, are reported
+ *   with their structured arguments, and other logs become readable breadcrumbs.
+ *
+ * Errors caught by the foundation-react-utils `AppErrorBoundary` and `TileErrorBoundary` are logged
+ * with their reference ID and component stack, so they are reported too without an `onError`.
+ * Pair them with `onCaughtError` on the React root.
+ *
+ * Calling it again replaces the previous reporter, or removes it if the new call finds no DSN.
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from '@sentry/react';
+ * import { setupErrorMonitoring } from '@genesislcap/foundation-utils';
+ *
+ * setupErrorMonitoring(Sentry);
+ * ```
+ *
+ * @param client - The monitoring SDK (for example the Sentry namespace) or an adapter for one.
+ * @param options - Config location and keys, and extra init options.
+ * @returns Whether monitoring was enabled.
+ * @public
+ */
+export function setupErrorMonitoring(client_1) {
+    return __awaiter(this, arguments, void 0, function* (client, options = {}) {
+        var _a, _b;
+        const { configUrl, dsnKey = 'sentryDsn', environmentKey = 'environmentType', defaultEnvironment = 'local', initOptions = {}, init, breadcrumbs = true, } = options;
+        const config = yield fetchRuntimeConfig(configUrl);
+        removeActiveReporter === null || removeActiveReporter === void 0 ? void 0 : removeActiveReporter();
+        removeActiveReporter = undefined;
+        const dsn = nonEmptyString(config[dsnKey]);
+        if (!dsn) {
+            return false;
+        }
+        const appBeforeBreadcrumb = initOptions.beforeBreadcrumb;
+        const beforeBreadcrumb = (breadcrumb) => {
+            if (breadcrumbs && isFoundationLoggerConsoleBreadcrumb(breadcrumb)) {
+                return null;
+            }
+            return appBeforeBreadcrumb ? appBeforeBreadcrumb(breadcrumb) : breadcrumb;
+        };
+        const resolvedInitOptions = Object.assign(Object.assign({ normalizeDepth: 10 }, initOptions), { dsn, environment: (_a = nonEmptyString(config[environmentKey])) !== null && _a !== void 0 ? _a : defaultEnvironment, beforeBreadcrumb });
+        yield (init ? init(resolvedInitOptions) : (_b = client.init) === null || _b === void 0 ? void 0 : _b.call(client, resolvedInitOptions));
+        removeActiveReporter = addGlobalLogReporter(createErrorMonitoringReporter(client, { breadcrumbs }));
+        return true;
+    });
+}

package/dist/esm/error-monitoring/format-log-args.js

@@ -0,0 +1,52 @@
+const MAX_MESSAGE_LENGTH = 2000;
+/** `JSON.stringify` replacer that names functions and marks repeated objects instead of throwing. */
+const readableReplacer = () => {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value === 'function') {
+            return `[Function ${value.name || 'anonymous'}]`;
+        }
+        if (typeof value === 'bigint') {
+            return `${value}n`;
+        }
+        if (typeof value === 'object' && value !== null) {
+            if (seen.has(value)) {
+                return '[Circular]';
+            }
+            seen.add(value);
+        }
+        return value;
+    };
+};
+const stringifyArg = (arg) => {
+    var _a;
+    if (typeof arg === 'string') {
+        return arg;
+    }
+    if (arg instanceof Error) {
+        return arg.message;
+    }
+    try {
+        return (_a = JSON.stringify(arg, readableReplacer())) !== null && _a !== void 0 ? _a : String(arg);
+    }
+    catch (_b) {
+        return String(arg);
+    }
+};
+/**
+ * Builds a readable one-line message from a log call's arguments.
+ *
+ * @remarks
+ * Objects, such as a Genesis NACK, are JSON-encoded rather than becoming `[object Object]`.
+ * Circular references are marked, functions and classes are named, errors contribute their message,
+ * and the result is capped at 2000 characters.
+ *
+ * @param args - The arguments passed to the logger.
+ * @public
+ */
+export const formatLogArgs = (args) => args
+    .map(stringifyArg)
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .join(' ')
+    .slice(0, MAX_MESSAGE_LENGTH);

package/dist/esm/error-monitoring/index.js

@@ -0,0 +1,2 @@
+export * from './error-monitoring';
+export * from './format-log-args';

package/dist/esm/index.js

@@ -6,6 +6,7 @@ export * from './directives';
 export * from './encoding';
 export * from './env';
 export * from './error';
+export * from './error-monitoring';
 export * from './feature-flags';
 export * from './formatters';
 export * from './logger';