feat(logger): introduce loglevel trace #1589 (#2902)

Author: timo92

Diff for: docs/core/logger.md

@@ -454,6 +454,7 @@ We support the following log levels:
 
 | Level      | Numeric value |
 | ---------- | ------------- |
+| `TRACE`    | 6             |
 | `DEBUG`    | 8             |
 | `INFO`     | 12            |
 | `WARN`     | 16            |

Diff for: packages/logger/src/Logger.ts

@@ -158,6 +158,7 @@ class Logger extends Utility implements LoggerInterface {
    * The levels are in ascending order from the most verbose to the least verbose (no logs).
    */
   private readonly logLevelThresholds: LogLevelThresholds = {
+    TRACE: 6,
     DEBUG: 8,
     INFO: 12,
     WARN: 16,
@@ -200,7 +201,7 @@ class Logger extends Utility implements LoggerInterface {
    *
    * We keep this value to be able to reset the log level to the initial value when the sample rate is refreshed.
    */
-  #initialLogLevel = 12;
+  #initialLogLevel = this.logLevelThresholds.INFO;
   /**
    * Replacer function used to serialize the log items.
    */
@@ -337,7 +338,7 @@ class Logger extends Utility implements LoggerInterface {
     input: LogItemMessage,
     ...extraInput: LogItemExtraInput
   ): void {
-    this.processLogItem(24, input, extraInput);
+    this.processLogItem(this.logLevelThresholds.CRITICAL, input, extraInput);
   }
 
   /**
@@ -348,7 +349,7 @@ class Logger extends Utility implements LoggerInterface {
    * @returns {void}
    */
   public debug(input: LogItemMessage, ...extraInput: LogItemExtraInput): void {
-    this.processLogItem(8, input, extraInput);
+    this.processLogItem(this.logLevelThresholds.DEBUG, input, extraInput);
   }
 
   /**
@@ -359,7 +360,7 @@ class Logger extends Utility implements LoggerInterface {
    * @returns {void}
    */
   public error(input: LogItemMessage, ...extraInput: LogItemExtraInput): void {
-    this.processLogItem(20, input, extraInput);
+    this.processLogItem(this.logLevelThresholds.ERROR, input, extraInput);
   }
 
   /**
@@ -403,7 +404,7 @@ class Logger extends Utility implements LoggerInterface {
    * @returns {void}
    */
   public info(input: LogItemMessage, ...extraInput: LogItemExtraInput): void {
-    this.processLogItem(12, input, extraInput);
+    this.processLogItem(this.logLevelThresholds.INFO, input, extraInput);
   }
 
   /**
@@ -636,6 +637,17 @@ class Logger extends Utility implements LoggerInterface {
     return this.getLogEvent();
   }
 
+  /**
+   * It prints a log item with level TRACE.
+   *
+   * @param {LogItemMessage} input
+   * @param {Error | LogAttributes | string} extraInput
+   * @returns {void}
+   */
+  public trace(input: LogItemMessage, ...extraInput: LogItemExtraInput): void {
+    this.processLogItem(this.logLevelThresholds.TRACE, input, extraInput);
+  }
+
   /**
    * It prints a log item with level WARN.
    *
@@ -644,7 +656,7 @@ class Logger extends Utility implements LoggerInterface {
    * @returns {void}
    */
   public warn(input: LogItemMessage, ...extraInput: LogItemExtraInput): void {
-    this.processLogItem(16, input, extraInput);
+    this.processLogItem(this.logLevelThresholds.WARN, input, extraInput);
   }
 
   /**
@@ -913,7 +925,7 @@ class Logger extends Utility implements LoggerInterface {
     log.prepareForPrint();
 
     const consoleMethod =
-      logLevel === 24
+      logLevel === this.logLevelThresholds.CRITICAL
         ? 'error'
         : (this.getLogLevelNameFromNumber(logLevel).toLowerCase() as keyof Omit<
             LogFunction,
@@ -970,6 +982,13 @@ class Logger extends Utility implements LoggerInterface {
     } else {
       this.console = console;
     }
+
+    /**
+     * Patch `console.trace` to avoid printing a stack trace and aligning with AWS Lambda behavior - see #2902
+     */
+    this.console.trace = (message: string, ...optionalParams: unknown[]) => {
+      this.console.log(message, ...optionalParams);
+    };
   }
 
   /**
@@ -1050,7 +1069,12 @@ class Logger extends Utility implements LoggerInterface {
       if (this.isValidSampleRate(value)) {
         this.powertoolsLogData.sampleRateValue = value;
 
-        if (value && randomInt(0, 100) / 100 <= value) {
+        if (
+          this.logLevel > this.logLevelThresholds.DEBUG &&
+          value &&
+          randomInt(0, 100) / 100 <= value
+        ) {
+          // only change logLevel if higher than debug, i.e. don't change from e.g. tracing to debug
           this.setLogLevel('DEBUG');
           this.debug('Setting log level to DEBUG due to sampling rate');
         } else {

Diff for: packages/logger/src/constants.ts

@@ -15,6 +15,7 @@ const LogJsonIndent = {
 } as const;
 
 const LogLevel = {
+  TRACE: 'TRACE',
   DEBUG: 'DEBUG',
   INFO: 'INFO',
   WARN: 'WARN',

Diff for: packages/logger/src/types/Logger.ts

@@ -148,6 +148,7 @@ type LoggerInterface = {
   setLogLevel(logLevel: LogLevel): void;
   setPersistentLogAttributes(attributes?: LogAttributes): void;
   shouldLogEvent(overwriteValue?: boolean): boolean;
+  trace(input: LogItemMessage, ...extraInput: LogItemExtraInput): void;
   warn(input: LogItemMessage, ...extraInput: LogItemExtraInput): void;
 };