AG-36533 Added new LogLevel.Trace logging level

Merge in ADGUARD-FILTERS/tsurlfilter from feature/AG-36533 to master Squashed commit of the following: commit 44aaa2d Author: Kurbanali Ruslan <[email protected]> Date: Tue Oct 8 11:03:10 2024 +0500 added jsdoc commit 2cc7525 Author: Kurbanali Ruslan <[email protected]> Date: Tue Oct 8 10:58:33 2024 +0500 updated readme commit 398c980 Author: Kurbanali Ruslan <[email protected]> Date: Tue Oct 8 10:57:14 2024 +0500 updated changelog date commit 2c1d6e4 Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 13:43:22 2024 +0500 bump version, updated changelog and readme commit 1520919 Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 13:36:16 2024 +0500 proper checking writer.trace method commit 021bd7a Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 11:41:08 2024 +0500 updated comments commit 8cb7a3e Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 11:40:02 2024 +0500 updated tests commit a31fbe7 Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 11:39:49 2024 +0500 updated changelog commit de5a6dc Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 11:36:12 2024 +0500 updated readme commit 1ad9d8e Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 11:36:05 2024 +0500 updated changelog commit 937faca Author: Kurbanali Ruslan <[email protected]> Date: Mon Oct 7 11:33:03 2024 +0500 added trace logging level
AdguardTeam · Oct 8, 2024 · 5249fc0 · 5249fc0
1 parent 65a40fc
commit 5249fc0
Show file tree

Hide file tree

Showing 5 changed files with 124 additions and 6 deletions.
diff --git a/packages/logger/CHANGELOG.md b/packages/logger/CHANGELOG.md
@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2024-10-08
+
+### Added
+
+- New logging level `LogLevel.Trace` which works as debug but prints with call stack trace.
+
 ## [1.0.2] - 2024-09-23
 
 ### Fixed

diff --git a/packages/logger/README.md b/packages/logger/README.md
@@ -56,6 +56,19 @@ const writer = {
 const logger = new Logger(writer);
 ```
 
+#### `Trace` logging level
+
+This logging level made solely for development purposes, to provided clickable call stack trace in console.
+
+This level works as `Debug` level, only difference is that for every method of logger it prints with call stack trace.
+Except `error()` which already provides call stack trace. In order to make it work these conditions should meet:
+- Logging level must be `LogLevel.Trace` or higher.
+- It should not be `error()` method.
+- `Writer` must have `trace()` method.
+
+If logging level is `LogLevel.Trace` or higher and `trace()` method is not provided with `writer` it will
+work as regular `LogLevel.Debug` level.
+
 ## Development
 
 To contribute to the development of AdGuard Logger, follow these steps:

diff --git a/packages/logger/package.json b/packages/logger/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@adguard/logger",
-    "version": "1.0.2",
+    "version": "1.1.0",
     "scripts": {
         "prebuild": "rimraf dist",
         "build": "pnpm prebuild && rollup -c rollup.config.ts --configPlugin typescript && pnpm build:types && pnpm build:txt",

diff --git a/packages/logger/src/Logger.ts b/packages/logger/src/Logger.ts
@@ -9,6 +9,7 @@ export const enum LogLevelNumeric {
     Warn,
     Info,
     Debug,
+    Trace,
 }
 
 /**
@@ -19,6 +20,7 @@ export enum LogLevel {
     Warn = 'warn',
     Info = 'info',
     Debug = 'debug',
+    Trace = 'trace',
 }
 
 /**
@@ -29,6 +31,7 @@ const levelMapNumToString = {
     [LogLevelNumeric.Warn]: LogLevel.Warn,
     [LogLevelNumeric.Info]: LogLevel.Info,
     [LogLevelNumeric.Debug]: LogLevel.Debug,
+    [LogLevelNumeric.Trace]: LogLevel.Trace,
 };
 
 /**
@@ -54,6 +57,13 @@ export const enum LogMethod {
     Error = 'error',
 }
 
+/**
+ * Writer method.
+ *
+ * @param {...any} args Arguments list to log.
+ */
+export type WriterMethod = (...args: any[]) => void;
+
 /**
  * Writer interface.
  */
@@ -62,19 +72,28 @@ export interface Writer {
      * Log method.
      * @param args
      */
-    log: (...args: any[]) => void;
+    log: WriterMethod;
+
     /**
      * Info method.
      * @param args
      */
-    info: (...args: any[]) => void;
+    info: WriterMethod;
+
     /**
      * Error method.
      * @param args
      */
-    error: (...args: any[]) => void;
+    error: WriterMethod;
+
+    /**
+     * Trace method.
+     * @param args
+     */
+    trace?: WriterMethod;
+
     // We do not use 'warn' channel, since in the extensions warn is counted as error.
-    // warn: (...args: any[]) => void;
+    // warn: WriterMethod;
 }
 
 /**
@@ -211,6 +230,21 @@ export class Logger {
 
         const formattedTime = `${formatTime(new Date())}:`;
 
-        this.writer[method](formattedTime, ...formattedArgs);
+        /**
+         * Conditions in which trace can happen:
+         * 1. Method is not error (because console.error provides call stack trace)
+         * 2. Log level is equal or higher that `LogLevel.Trace`.
+         * 3. Writer has `trace` method.
+         */
+        if (
+            method !== LogMethod.Error
+            && this.currentLevelValue >= levelMapStringToNum[LogLevel.Trace]
+            && 'trace' in this.writer
+            && typeof this.writer.trace === 'function'
+        ) {
+            this.writer.trace(formattedTime, ...formattedArgs);
+        } else {
+            this.writer[method](formattedTime, ...formattedArgs);
+        }
     }
 }
diff --git a/packages/logger/tests/logger.test.ts b/packages/logger/tests/logger.test.ts
@@ -62,15 +62,19 @@ describe('works', () => {
             const logger = new Logger(writer);
             expect(logger.currentLevel).toBe(LogLevel.Info);
         });
+
         it('switches log levels', () => {
             const logger = new Logger(writer);
+            logger.currentLevel = LogLevel.Trace;
+            expect(logger.currentLevel).toBe(LogLevel.Trace);
             logger.currentLevel = LogLevel.Debug;
             expect(logger.currentLevel).toBe(LogLevel.Debug);
             logger.currentLevel = LogLevel.Info;
             expect(logger.currentLevel).toBe(LogLevel.Info);
             logger.currentLevel = LogLevel.Error;
             expect(logger.currentLevel).toBe(LogLevel.Error);
         });
+
         it('does not print message if debug is printed and info is selected', () => {
             const logger = new Logger(writer);
             const message = 'some message';
@@ -80,6 +84,7 @@ describe('works', () => {
             expect(writer.log).not.toHaveBeenCalled();
             expect(writer.error).not.toHaveBeenCalled();
         });
+
         it('prints message if debug method is called and debug level is selected', () => {
             const logger = new Logger(writer);
             const message = 'some message';
@@ -89,5 +94,65 @@ describe('works', () => {
             expect(writer.log).toHaveBeenCalled();
             expect(writer.error).not.toHaveBeenCalled();
         });
+
+        describe('log level -- trace', () => {
+            const writerWithTrace: Writer = {
+                log: jest.fn(),
+                info: jest.fn(),
+                error: jest.fn(),
+                trace: jest.fn(),
+            };
+
+            it('does not print with trace method if error is called', () => {
+                const logger = new Logger(writerWithTrace);
+                const message = 'some message';
+                logger.currentLevel = LogLevel.Trace;
+                logger.error(message);
+                expect(writerWithTrace.error).toHaveBeenCalled();
+                expect(writerWithTrace.trace).not.toHaveBeenCalled();
+            });
+
+            it('does not print with trace method if level is not enough', () => {
+                const logger = new Logger(writerWithTrace);
+                const message = 'some message';
+                logger.currentLevel = LogLevel.Debug;
+
+                logger.debug(message);
+                expect(writerWithTrace.log).toHaveBeenCalled();
+
+                logger.info(message);
+                logger.warn(message);
+                expect(writerWithTrace.info).toHaveBeenCalledTimes(2);
+
+                expect(writerWithTrace.trace).not.toHaveBeenCalled();
+            });
+
+            it('print with regular methods if trace method is not provided and level is enough', () => {
+                const logger = new Logger(writer);
+                const message = 'some message';
+                logger.currentLevel = LogLevel.Trace;
+
+                logger.debug(message);
+                expect(writer.log).toHaveBeenCalled();
+
+                logger.info(message);
+                logger.warn(message);
+                expect(writer.info).toHaveBeenCalledTimes(2);
+            });
+
+            it('print with trace method', () => {
+                const logger = new Logger(writerWithTrace);
+                const message = 'some message';
+                logger.currentLevel = LogLevel.Trace;
+
+                logger.debug(message);
+                logger.info(message);
+                logger.warn(message);
+                logger.error(message);
+
+                expect(writerWithTrace.trace).toHaveBeenCalledTimes(3);
+                expect(writerWithTrace.error).toHaveBeenCalled();
+            });
+        });
     });
 });