chore: add more verbose logger bootstrap error message (#7314)

Author: bartoszherba

.changeset/red-days-exercise.md

@@ -0,0 +1,11 @@
+---
+"@vue-storefront/middleware": patch
+---
+
+** [CHANGED] **
+
+- added more verbose message with a troubleshooting guide in case that the `getLogger` method was not able to retrieve the logger instance.
+
+** [FIXED] **
+
+- changed `level` property to `verbosity` in the `LoggerConfig` interface.

packages/middleware/src/logger/fallbackLogger.ts

@@ -0,0 +1,20 @@
+import { LoggerFactory, LoggerType } from "@vue-storefront/logger";
+
+import { injectMetadata, lockLogger } from "./injectMetadata";
+
+/**
+ * This logger is used as a fallback logger in case of any error during the
+ * initialization of the logger. It is used to log the error and provide a
+ * default logger for the application. It should not be used as a primary
+ * logger.
+ */
+const fallbackLogger = injectMetadata(
+  lockLogger(LoggerFactory.create(LoggerType.ConsolaGcp)),
+  () => ({
+    alokai: {
+      context: "middleware",
+    },
+  })
+);
+
+export { fallbackLogger };

packages/middleware/src/logger/getLogger.ts

@@ -1,5 +1,6 @@
 import type { LoggerInterface } from "@vue-storefront/logger";
 import type { AlokaiContainer, ResponseWithAlokaiLocals } from "../types";
+import { fallbackLogger } from "./fallbackLogger";
 
 type ContextSubset = { res: ResponseWithAlokaiLocals };
 type LoggerSource = AlokaiContainer | ResponseWithAlokaiLocals | ContextSubset;
@@ -19,8 +20,23 @@ function findLogger(source: LoggerSource): LoggerInterface {
 
 export function getLogger(source: LoggerSource): LoggerInterface {
   const logger = findLogger(source);
+
   if (!logger) {
-    throw new Error("Logger instance could not be determined");
+    fallbackLogger.alert("Logger instance could not be resolved", {
+      troubleshooting: {
+        message:
+          "This issue is likely caused by a version mismatch in the middleware stack. Note: Logger functionality was introduced in version 5.1.0 of the middleware package. For more details, refer to https://docs.alokai.com/middleware/guides/logging.",
+        steps: [
+          "Update all middleware packages to the latest compatible version to ensure logger compatibility.",
+          "Ensure API client packages are also updated, as they rely on compatible middleware versions.",
+          "Update unified API packages to the latest version to maintain compatibility with the updated middleware packages.",
+        ],
+      },
+    });
+
+    throw new Error(
+      "Logger instance could not be determined. In most cases, this is due to a versions missmatch in the middleware stack."
+    );
   }
   return logger;
 }

packages/middleware/src/types/config.ts

@@ -23,9 +23,9 @@ export type LogVerbosity =
  */
 export interface LoggerOptions {
   /**
-   * The log level aligned with RFC5424.
+   * The log verbosity level aligned with RFC5424.
    */
-  level?: LogVerbosity;
+  verbosity?: LogVerbosity;
 
   /**
    * Whether to include the stack trace in the log message.