@terreno/api 0.20.1 → 0.21.0

package/dist/logger.js

@@ -43,6 +43,17 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __values = (this && this.__values) || function(o) {
+    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
+    if (m) return m.call(o);
+    if (o && typeof o.length === "number") return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
+};
 var __read = (this && this.__read) || function (o, n) {
     var m = typeof Symbol === "function" && o[Symbol.iterator];
     if (!m) return o;
@@ -68,23 +79,39 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     }
     return to.concat(ar || Array.prototype.slice.call(from));
 };
-var __values = (this && this.__values) || function(o) {
-    var s = typeof Symbol === "function" && Symbol.iterator, m = s && o[s], i = 0;
-    if (m) return m.call(o);
-    if (o && typeof o.length === "number") return {
-        next: function () {
-            if (o && i >= o.length) o = void 0;
-            return { value: o && o[i++], done: !o };
-        }
-    };
-    throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
-};
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setupLogging = exports.logger = exports.winstonLogger = void 0;
+exports.setupLogging = exports.createFeatureFlaggedLogger = exports.createScopedLogger = exports.logger = exports.winstonLogger = exports.formatLogContextSuffix = void 0;
+/**
+ * Backend logging for `@terreno/api`.
+ *
+ * Three building blocks cooperate so a single request or background job can be followed across
+ * many log lines, both in plain-text consoles and in structured transports (Google Cloud Logging,
+ * Sentry):
+ *
+ * - **{@link logger}** – the global logger (`debug` / `info` / `warn` / `error` / `catch`). Use it
+ *   for one-off messages.
+ * - **{@link createScopedLogger}** – returns a logger that prepends a stable `prefix` and/or
+ *   attaches `labels` (workflow dimensions such as `invoiceId`) to every line. Use it when a
+ *   handler, job, or service runs multiple steps that should share identifiers.
+ * - **{@link createFeatureFlaggedLogger}** – wraps any {@link ScopedLogger} behind an
+ *   `isEnabled()` predicate so verbose diagnostics can be toggled with a feature flag or env var
+ *   without a redeploy.
+ *
+ * **Correlation** is automatic: while a request/job AsyncLocalStorage scope is active (see
+ * `requestContext.ts` – HTTP middleware or `runWithRequestContext`), every log line is enriched
+ * with `requestId`, `userId`, `traceId`, etc. and a nested `terrenoRequestLog` object, regardless
+ * of which logger above emitted it.
+ *
+ * @see {@link createScopedLogger}
+ * @see {@link createFeatureFlaggedLogger}
+ * @see {@link formatLogContextSuffix}
+ * @module logger
+ */
 var node_fs_1 = __importDefault(require("node:fs"));
+var node_path_1 = require("node:path");
 var node_util_1 = require("node:util");
 var Sentry = __importStar(require("@sentry/bun"));
 var winston_1 = __importDefault(require("winston"));
@@ -97,23 +124,95 @@ var formatWithInspect = function (val) {
     var shouldFormat = typeof val !== "string";
     return prefix + (shouldFormat ? (0, node_util_1.inspect)(val, { colors: true, depth: null }) : val);
 };
+var buildTerrenoRequestLog = function (active) {
+    var _a;
+    return {
+        requestId: active.requestId,
+        userId: (_a = active.userId) !== null && _a !== void 0 ? _a : null,
+    };
+};
+var mergeActiveRequestIntoInfo = function (info, active) {
+    var next = __assign(__assign({}, info), { requestId: active.requestId, terrenoRequestLog: buildTerrenoRequestLog(active) });
+    if (active.jobId) {
+        next.jobId = active.jobId;
+    }
+    if (active.sessionId) {
+        next.sessionId = active.sessionId;
+    }
+    if (active.userId) {
+        next.userId = active.userId;
+    }
+    if (active.spanId) {
+        next.spanId = active.spanId;
+    }
+    if (active.traceId) {
+        next.traceId = active.traceId;
+    }
+    if (active.traceSampled !== undefined) {
+        next.traceSampled = active.traceSampled;
+    }
+    return next;
+};
 var addRequestContextFormat = winston_1.default.format(function (info) {
-    var context = (0, requestContext_1.getCurrentLogContext)();
-    return __assign(__assign({}, context), info);
+    var active = (0, requestContext_1.getCurrentRequestContext)();
+    if (!active) {
+        return __assign({}, info);
+    }
+    return mergeActiveRequestIntoInfo(info, active);
 });
-var formatContext = function (info) {
+/**
+ * Builds the ` key=value ...` suffix appended to console/file log lines after the message.
+ * Request-scoped fields come from AsyncLocalStorage via Winston metadata; `terrenoLabels` and
+ * `terrenoLogPrefix` come from {@link createScopedLogger}. Nested `terrenoRequestLog`
+ * (`requestId` + `userId` including `null` when anonymous) is attached on the Winston info
+ * object for structured transports only, not repeated in this suffix.
+ */
+var formatLogContextSuffix = function (fields) {
+    var e_1, _a;
     var contextParts = [
-        info.requestId ? "requestId=".concat(info.requestId) : undefined,
-        info.jobId ? "jobId=".concat(info.jobId) : undefined,
-        info.sessionId ? "sessionId=".concat(info.sessionId) : undefined,
-        info.userId ? "userId=".concat(info.userId) : undefined,
-        info.traceId ? "traceId=".concat(info.traceId) : undefined,
+        fields.requestId ? "requestId=".concat(fields.requestId) : undefined,
+        fields.jobId ? "jobId=".concat(fields.jobId) : undefined,
+        fields.sessionId ? "sessionId=".concat(fields.sessionId) : undefined,
+        fields.userId ? "userId=".concat(fields.userId) : undefined,
+        fields.traceId ? "traceId=".concat(fields.traceId) : undefined,
+        fields.terrenoLogPrefix ? "logPrefix=".concat(fields.terrenoLogPrefix) : undefined,
     ].filter(Boolean);
+    if (fields.terrenoLabels && typeof fields.terrenoLabels === "object") {
+        var sortedKeys = Object.keys(fields.terrenoLabels).sort();
+        try {
+            for (var sortedKeys_1 = __values(sortedKeys), sortedKeys_1_1 = sortedKeys_1.next(); !sortedKeys_1_1.done; sortedKeys_1_1 = sortedKeys_1.next()) {
+                var key = sortedKeys_1_1.value;
+                var value = fields.terrenoLabels[key];
+                if (value !== undefined && value !== "") {
+                    contextParts.push("".concat(key, "=").concat(value));
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (sortedKeys_1_1 && !sortedKeys_1_1.done && (_a = sortedKeys_1.return)) _a.call(sortedKeys_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    }
     if (contextParts.length === 0) {
         return "";
     }
     return " ".concat(contextParts.join(" "));
 };
+exports.formatLogContextSuffix = formatLogContextSuffix;
+var formatContext = function (info) {
+    return (0, exports.formatLogContextSuffix)({
+        jobId: info.jobId,
+        requestId: info.requestId,
+        sessionId: info.sessionId,
+        terrenoLabels: info.terrenoLabels,
+        terrenoLogPrefix: info.terrenoLogPrefix,
+        traceId: info.traceId,
+        userId: info.userId,
+    });
+};
 // Winston doesn't operate like console.log by default, e.g. `logger.error('error',
 // error)` only prints the message and no args. Add handling for all the args,
 // while also supporting splat logging.
@@ -131,6 +230,43 @@ var printf = function (timestamp) {
         return "".concat(info.level, ": ").concat(msg).concat(context, " ").concat(rest);
     };
 };
+var terrenoDevJsonlAttached = false;
+var shouldAttachTerrenoDevJsonl = function () {
+    if (process.env.TERRENO_LOG_FILE === "false" || process.env.TERRENO_LOG_FILE === "0") {
+        return false;
+    }
+    if (process.env.TERRENO_LOG_FILE === "true" || process.env.TERRENO_LOG_FILE === "1") {
+        return true;
+    }
+    return process.env.NODE_ENV !== "production";
+};
+var attachTerrenoDevJsonlTransportIfEnabled = function (logger, options) {
+    if (options === null || options === void 0 ? void 0 : options.disable) {
+        return;
+    }
+    if (!shouldAttachTerrenoDevJsonl()) {
+        return;
+    }
+    if (terrenoDevJsonlAttached) {
+        return;
+    }
+    var logDir = (0, node_path_1.join)(process.cwd(), ".terreno", "logs");
+    if (!node_fs_1.default.existsSync(logDir)) {
+        node_fs_1.default.mkdirSync(logDir, { recursive: true });
+    }
+    var maxBytes = 5 * 1024 * 1024;
+    logger.add(new winston_1.default.transports.File({
+        filename: (0, node_path_1.join)(logDir, "app.log"),
+        format: winston_1.default.format.combine(addRequestContextFormat(), winston_1.default.format.timestamp(), winston_1.default.format.json()),
+        handleExceptions: true,
+        handleRejections: true,
+        level: "debug",
+        maxFiles: 3,
+        maxsize: maxBytes,
+        options: { flags: "a", mode: 384 },
+    }));
+    terrenoDevJsonlAttached = true;
+};
 // Setup a global, default rejection handler.
 winston_1.default.add(new winston_1.default.transports.Console({
     debugStdout: true,
@@ -153,13 +289,42 @@ exports.winstonLogger = winston_1.default.createLogger({
         }),
     ],
 });
+var mergeSentryLogAttributes = function (extra) {
+    var active = (0, requestContext_1.getCurrentRequestContext)();
+    var out = __assign(__assign({}, (0, requestContext_1.getCurrentLogContext)()), (extra !== null && extra !== void 0 ? extra : {}));
+    if (active) {
+        out.terrenoRequestLog = buildTerrenoRequestLog(active);
+    }
+    return out;
+};
+attachTerrenoDevJsonlTransportIfEnabled(exports.winstonLogger);
 // Helper function to send logs to Sentry if enabled
-var sendToSentry = function (message, level) {
+var sendToSentry = function (message, level, extraAttributes) {
     if (process.env.USE_SENTRY_LOGGING === "true" && Sentry.logger) {
         var logWithContext = Sentry.logger[level];
-        logWithContext(message, (0, requestContext_1.getCurrentLogContext)());
+        logWithContext(message, mergeSentryLogAttributes(extraAttributes));
     }
 };
+/**
+ * Global application logger. Each method writes through Winston (console/file transports) and, when
+ * `USE_SENTRY_LOGGING=true`, mirrors the line to Sentry with the active request context attached.
+ *
+ * Prefer {@link createScopedLogger} when a workflow spans multiple log lines that should share a
+ * prefix or labels.
+ *
+ * @example
+ * ```typescript
+ * import {logger} from "@terreno/api";
+ *
+ * logger.info("Server started", {port: 4000});
+ * logger.warn("Slow query", {ms: 500});
+ * logger.error("Failed to process", {error});
+ * logger.debug("Request details", {body: req.body});
+ *
+ * // Convenient `.catch` handler for promises – logs and captures the exception.
+ * await chargeCard(id).catch(logger.catch);
+ * ```
+ */
 exports.logger = {
     // simple way to log a caught exception. e.g. promise().catch(logger.catch)
     catch: function (e) {
@@ -170,7 +335,7 @@ exports.logger = {
                 Sentry.captureException(e);
             }
             else if (Sentry.logger) {
-                Sentry.logger.error(errorMsg);
+                Sentry.logger.error(errorMsg, mergeSentryLogAttributes());
             }
         }
     },
@@ -207,10 +372,261 @@ exports.logger = {
         sendToSentry(msg, "warn");
     },
 };
+var normalizeLogLabels = function (labels) {
+    var e_2, _a;
+    if (!labels) {
+        return undefined;
+    }
+    var out = {};
+    try {
+        for (var _b = __values(Object.entries(labels)), _c = _b.next(); !_c.done; _c = _b.next()) {
+            var _d = __read(_c.value, 2), key = _d[0], value = _d[1];
+            if (value === undefined || value === null) {
+                continue;
+            }
+            out[key] = String(value);
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+};
+var applyMessagePrefix = function (prefix, msg) {
+    var trimmed = prefix === null || prefix === void 0 ? void 0 : prefix.trim();
+    if (!trimmed) {
+        return msg;
+    }
+    return "".concat(trimmed, " ").concat(msg);
+};
+var buildScopedLoggerSentryExtras = function (labels, logPrefix) {
+    var e_3, _a;
+    var out = {};
+    if (logPrefix) {
+        out.terrenoLogPrefix = logPrefix;
+    }
+    if (labels) {
+        try {
+            for (var _b = __values(Object.entries(labels)), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = __read(_c.value, 2), key = _d[0], value = _d[1];
+                out[key] = value;
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+};
+/**
+ * Creates a {@link ScopedLogger} that prefixes every message and/or attaches stable `labels` to
+ * every line, so multi-step workflows are easy to group and search.
+ *
+ * - `prefix` is prepended to the human-readable message (easy grep / Log Explorer text search) and
+ *   also stored as the Winston metadata field `terrenoLogPrefix`.
+ * - `labels` are normalized to strings and stored as the Winston metadata field `terrenoLabels`.
+ *   They appear in the plain-text ` key=value` suffix (see {@link formatLogContextSuffix}) and as
+ *   discrete fields on structured transports such as `@google-cloud/logging-winston`.
+ *
+ * Both ride on a Winston **child logger**, so they merge with — and never overwrite — the
+ * request/job correlation fields that AsyncLocalStorage injects (`requestId`, `userId`,
+ * `terrenoRequestLog`, etc.). Avoid label keys that collide with those framework fields:
+ * `requestId`, `jobId`, `sessionId`, `userId`, `traceId`, `spanId`, `terrenoLogPrefix`,
+ * `terrenoRequestLog`, `terrenoLabels`.
+ *
+ * If both `prefix` and `labels` are empty, the global {@link logger} is returned unchanged.
+ *
+ * @param options - Optional `prefix` token and/or `labels` dimensions for this scope.
+ * @returns A scoped logger sharing the same methods as the global {@link logger}.
+ * @see {@link createFeatureFlaggedLogger} to gate a scoped logger behind a feature flag.
+ *
+ * @example Reuse one instance for a whole workflow so every line shares identifiers
+ * ```typescript
+ * import {createScopedLogger} from "@terreno/api";
+ *
+ * const log = createScopedLogger({
+ *   prefix: "[InvoicePay]",
+ *   labels: {invoiceId: invoice._id.toString(), attempt: String(attemptNumber)},
+ * });
+ *
+ * log.info("Starting capture");        // -> "[InvoicePay] Starting capture invoiceId=... attempt=1 requestId=..."
+ * log.warn("Stripe rate limited, backing off");
+ * await capture(invoice).catch(log.catch);
+ * ```
+ */
+var createScopedLogger = function (options) {
+    var _a;
+    if (options === void 0) { options = {}; }
+    var trimmedPrefix = ((_a = options.prefix) === null || _a === void 0 ? void 0 : _a.trim()) ? options.prefix.trim() : undefined;
+    var terrenoLabels = normalizeLogLabels(options.labels);
+    if (!trimmedPrefix && !terrenoLabels) {
+        return exports.logger;
+    }
+    var childDefaults = {};
+    if (terrenoLabels) {
+        childDefaults.terrenoLabels = terrenoLabels;
+    }
+    if (trimmedPrefix) {
+        childDefaults.terrenoLogPrefix = trimmedPrefix;
+    }
+    var base = exports.winstonLogger.child(childDefaults);
+    var sentryExtras = function () {
+        return buildScopedLoggerSentryExtras(terrenoLabels, trimmedPrefix);
+    };
+    return {
+        catch: function (e) {
+            var errorMsg = applyMessagePrefix(trimmedPrefix, "Caught: ".concat(e === null || e === void 0 ? void 0 : e.message, " ").concat(e === null || e === void 0 ? void 0 : e.stack));
+            base.error(errorMsg);
+            if (process.env.USE_SENTRY_LOGGING === "true") {
+                if (e instanceof Error) {
+                    Sentry.captureException(e);
+                }
+                else if (Sentry.logger) {
+                    Sentry.logger.error(errorMsg, mergeSentryLogAttributes(sentryExtras()));
+                }
+            }
+        },
+        debug: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            var line = applyMessagePrefix(trimmedPrefix, msg);
+            base.debug.apply(base, __spreadArray([line], __read(args), false));
+            sendToSentry(line, "debug", sentryExtras());
+        },
+        error: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            var line = applyMessagePrefix(trimmedPrefix, msg);
+            base.error.apply(base, __spreadArray([line], __read(args), false));
+            sendToSentry(line, "error", sentryExtras());
+        },
+        info: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            var line = applyMessagePrefix(trimmedPrefix, msg);
+            base.info.apply(base, __spreadArray([line], __read(args), false));
+            sendToSentry(line, "info", sentryExtras());
+        },
+        warn: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            var line = applyMessagePrefix(trimmedPrefix, msg);
+            base.warn.apply(base, __spreadArray([line], __read(args), false));
+            sendToSentry(line, "warn", sentryExtras());
+        },
+    };
+};
+exports.createScopedLogger = createScopedLogger;
+/**
+ * Wraps a {@link ScopedLogger} so all `debug` / `info` / `warn` / `error` traffic is dropped while
+ * `isEnabled()` returns false. Use it to keep verbose diagnostics in the code but silent until a
+ * flag turns them on — no redeploy required.
+ *
+ * `isEnabled` is evaluated on **every** call, so it can read any feature-flag source: an
+ * environment variable, a cached/remote flag map, or a call into `@terreno/feature-flags` from your
+ * app. (`@terreno/api` deliberately does not import `@terreno/feature-flags` to avoid a package
+ * cycle — you supply the predicate.)
+ *
+ * @param options - The `isEnabled` predicate plus an optional `target` logger and `gateCatch`.
+ * @returns A scoped logger that forwards to `target` only while the flag is enabled.
+ * @see {@link createScopedLogger} for the usual `target`.
+ *
+ * @example Gate a scoped logger behind an env var (flips live, no restart)
+ * ```typescript
+ * import {createFeatureFlaggedLogger, createScopedLogger} from "@terreno/api";
+ *
+ * const jobLog = createFeatureFlaggedLogger({
+ *   isEnabled: () => process.env.JOB_TRACE_LOGS === "true",
+ *   target: createScopedLogger({prefix: "[Job]", labels: {jobName: "nightly-sync"}}),
+ * });
+ *
+ * jobLog.info("step 1"); // silent unless JOB_TRACE_LOGS=true
+ * ```
+ *
+ * @example Drive it from `@terreno/feature-flags` in app code
+ * ```typescript
+ * const debugLog = createFeatureFlaggedLogger({
+ *   isEnabled: () => flags.isEnabled("debug.billing"),
+ *   target: createScopedLogger({prefix: "[Billing]"}),
+ *   gateCatch: true, // also silence `catch` while the flag is off (default: false)
+ * });
+ * ```
+ */
+var createFeatureFlaggedLogger = function (options) {
+    var _a, _b;
+    var target = (_a = options.target) !== null && _a !== void 0 ? _a : exports.logger;
+    var gateCatch = (_b = options.gateCatch) !== null && _b !== void 0 ? _b : false;
+    return {
+        catch: function (e) {
+            if (gateCatch && !options.isEnabled()) {
+                return;
+            }
+            target.catch(e);
+        },
+        debug: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            if (!options.isEnabled()) {
+                return;
+            }
+            target.debug.apply(target, __spreadArray([msg], __read(args), false));
+        },
+        error: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            if (!options.isEnabled()) {
+                return;
+            }
+            target.error.apply(target, __spreadArray([msg], __read(args), false));
+        },
+        info: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            if (!options.isEnabled()) {
+                return;
+            }
+            target.info.apply(target, __spreadArray([msg], __read(args), false));
+        },
+        warn: function (msg) {
+            var args = [];
+            for (var _i = 1; _i < arguments.length; _i++) {
+                args[_i - 1] = arguments[_i];
+            }
+            if (!options.isEnabled()) {
+                return;
+            }
+            target.warn.apply(target, __spreadArray([msg], __read(args), false));
+        },
+    };
+};
+exports.createFeatureFlaggedLogger = createFeatureFlaggedLogger;
 var setupLogging = function (options) {
-    var _a, e_1, _b;
+    var _a, e_4, _b;
     var _c, _d;
     exports.winstonLogger.clear();
+    terrenoDevJsonlAttached = false;
     if (!(options === null || options === void 0 ? void 0 : options.disableConsoleLogging)) {
         var formats = [addRequestContextFormat(), winston_1.default.format.simple()];
         if (!(options === null || options === void 0 ? void 0 : options.disableConsoleColors)) {
@@ -259,13 +675,16 @@ var setupLogging = function (options) {
                 exports.winstonLogger.add(transport);
             }
         }
-        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        catch (e_4_1) { e_4 = { error: e_4_1 }; }
         finally {
             try {
                 if (_f && !_f.done && (_b = _e.return)) _b.call(_e);
             }
-            finally { if (e_1) throw e_1.error; }
+            finally { if (e_4) throw e_4.error; }
         }
     }
+    attachTerrenoDevJsonlTransportIfEnabled(exports.winstonLogger, {
+        disable: (options === null || options === void 0 ? void 0 : options.disableTerrenoDevJsonlLog) === true,
+    });
 };
 exports.setupLogging = setupLogging;