Add named loggers

Author: terehov

README.md

@@ -61,15 +61,17 @@ In order to run a native ES module in Node.js, you have to do two things:
 2) For now, start with `--experimental-specifier-resolution=node`
 
 Example `package.json`
-```json
+```json5
 {
   "name": "NAME",
   "version": "1.0.0",
   "main": "index.js",
-  "type": "module", // <-- here 
+  // here:
+  "type": "module",
   "scripts": {
     "build": "tsc -p .",
-    "start": "node --enable-source-maps --experimental-specifier-resolution=node index.js" // <-- and here
+    // and here:
+    "start": "node --enable-source-maps --experimental-specifier-resolution=node index.js"
   },
   "dependencies": {
     "tslog": "^4"
@@ -144,7 +146,7 @@ This feature enables `tslog` to reference a correct line number in your TypeScri
 ```typescript
 import { Logger } from "tslog";
 
-const logger = new Logger();
+const logger = new Logger({ name: "myLogger" });
 logger.silly("I am a silly log.");
 logger.trace("I am a trace log.");
 logger.debug("I am a debug log.");
@@ -169,6 +171,8 @@ logger.fatal(new Error("I am a pretty Error with a stacktrace."));
 - **Pretty Error:** Errors and stack traces printed in a structured way and fully accessible through _JSON_ (e.g. external Log services)
 - **ES Modules:** import syntax with ([tree-shaking](https://webpack.js.org/guides/tree-shaking/))
 - **Object/JSON highlighting:** Nicely prints out objects
+- **Instance Name**: _(Server-side only)_ Logs capture instance name (default host name) making it easy to distinguish logs coming from different instances
+- **Named Logger:** Logger can be named (e.g. useful for packages/modules and monorepos)
 - **Sub Logger with inheritance:** Powerful sub-loggers with settings inheritance, also at runtime
 - **Secrets masking:** Prevent passwords and secrets from sneaking into log files by masking them
 - **Short paths:** Paths are relative to the root of the application folder
@@ -268,6 +272,36 @@ const jsonLogger = new Logger({type: "json"});
 const hiddenLogger = new Logger({type: "hidden"});
 ```
 
+
+#### Name
+
+Each logger has an optional name. You can find the name of the logger responsible for a log inside the `Meta`-object or printed in `pretty` mode. 
+Names get also inherited to sub loggers and can be found inside the `Meta`-object `parentNames` as well as printed out with a separator (e.g. `:`). 
+
+Simple name example:
+```typescript
+new Logger({ name: "myLogger" });
+```
+
+Sub-loggers with an inherited name: 
+```typescript
+const mainLogger = new Logger({ type: "pretty", name: "MainLogger" });
+mainLogger.silly("foo bar");
+
+const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" });
+firstSubLogger.silly("foo bar 1");
+
+const secondSubLogger = firstSubLogger.getSubLogger({ name: "SecondSubLogger" });
+secondSubLogger.silly("foo bar 2");
+```
+
+Output: 
+```shell
+2022-11-17 10:45:47.705 SILLY   [/examples/nodejs/index2.ts:51 MainLogger]       foo bar
+2022-11-17 10:45:47.706 SILLY   [/examples/nodejs/index2.ts:54 MainLogger:FirstSubLogger]        foo bar 1
+2022-11-17 10:45:47.706 SILLY   [/examples/nodejs/index2.ts:57 MainLogger:FirstSubLogger:SecondSubLogger]        foo bar 2
+```
+
 #### minLevel
 
 You can ignore every log message from being processed until a certain severity.
@@ -276,7 +310,7 @@ Default severities are:
 
 ```typescript
 
-const suppressSilly = new Logger({minLevel: 1 });
+const suppressSilly = new Logger({ minLevel: 1 });
 suppressSilly.silly("Will be hidden");
 suppressSilly.trace("Will be visible");
 ```
@@ -319,6 +353,7 @@ Following settings are available for styling:
     - `{{ms}}`: milliseconds
     - `{{dateIsoStr}}`: Shortcut for `{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}`
     - `{{logLevelName}}`: name of the log level
+    - `{{name}}`: optional name of the current logger and his parents (e.g. "ParentLogger:ThisLogger")
     - `{{fullFilePath}}`: a full path starting from `/` root
     - `{{filePathWithLine}}`: a full path below the project path with line number
   - `prettyErrorTemplate`: template string for error message. Possible placeholders:
@@ -329,6 +364,7 @@ Following settings are available for styling:
     - `{{fileName}}`: name of the file
     - `{{filePathWithLine}}`: a full path below the project path with a line number
     - `{{method}}`: _optional_ name of the invoking method
+  - `prettyErrorParentNamesSeparator`: separator to be used when joining names ot the parent logger, and the current one (default: `:`)
   - `prettyInspectOptions`: <a href="https://nodejs.org/api/util.html#utilinspectobject-options" target="_blank">Available options</a>
 
 - **Styling:**
@@ -348,9 +384,10 @@ You can define the property containing this meta information with `metaProperty`
 ```typescript
 
 const logger = new Logger({
-  prettyLogTemplate: "{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}\t{{logLevelName}}\t[{{filePathWithLine}}]\t",
+  prettyLogTemplate: "{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}\t{{logLevelName}}\t[{{filePathWithLine}}{{name}}]\t",
   prettyErrorTemplate: "\n{{errorName}} {{errorMessage}}\nerror stack:\n{{errorStack}}",
   prettyErrorStackTemplate: "  • {{fileName}}\t{{method}}\n\t{{filePathWithLine}}",
+  prettyErrorParentNamesSeparator: ":",
   stylePrettyLogs: true,
   prettyLogStyles: {
     logLevelName: {
@@ -365,6 +402,7 @@ const logger = new Logger({
     },
     dateIsoStr: "white",
     filePathWithLine: "white",
+    name: "white",
     errorName: ["bold", "bgRedBright", "whiteBright"],
     fileName: ["yellow"],
   },

examples/nodejs/index2.ts

@@ -47,6 +47,11 @@ jsonLoggerArgumentsArray.silly("test1", "test2");
 
 ////////////////////////////
 
-const log = new Logger({ type: "json" }, { name: "DefaultLogger" });
+const mainLogger = new Logger({ type: "pretty", name: "MainLogger" });
+mainLogger.silly("foo bar");
 
-log.silly("foo bar");
+const firstSubLogger = mainLogger.getSubLogger({ name: "FirstSubLogger" });
+firstSubLogger.silly("foo bar 1");
+
+const secondSubLogger = firstSubLogger.getSubLogger({ name: "SecondSubLogger" });
+secondSubLogger.silly("foo bar 2");

src/BaseLogger.ts

@@ -19,11 +19,15 @@ export class BaseLogger<LogObj> {
 
     this.settings = {
       type: settings?.type ?? "pretty",
+      name: settings?.name,
+      parentNames: settings?.parentNames,
       minLevel: settings?.minLevel ?? 0,
       argumentsArrayName: settings?.argumentsArrayName,
-      prettyLogTemplate: settings?.prettyLogTemplate ?? "{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}\t{{logLevelName}}\t[{{filePathWithLine}}]\t",
+      prettyLogTemplate:
+        settings?.prettyLogTemplate ?? "{{yyyy}}.{{mm}}.{{dd}} {{hh}}:{{MM}}:{{ss}}:{{ms}}\t{{logLevelName}}\t[{{filePathWithLine}}{{name}}]\t",
       prettyErrorTemplate: settings?.prettyErrorTemplate ?? "\n{{errorName}} {{errorMessage}}\nerror stack:\n{{errorStack}}",
       prettyErrorStackTemplate: settings?.prettyErrorTemplate ?? "  • {{fileName}}\t{{method}}\n\t{{filePathWithLine}}",
+      prettyErrorParentNamesSeparator: settings?.prettyErrorParentNamesSeparator ?? ":",
       stylePrettyLogs: settings?.stylePrettyLogs ?? true,
       prettyLogStyles: settings?.prettyLogStyles ?? {
         logLevelName: {
@@ -38,6 +42,7 @@ export class BaseLogger<LogObj> {
         },
         dateIsoStr: "white",
         filePathWithLine: "white",
+        name: "white",
         errorName: ["bold", "bgRedBright", "whiteBright"],
         fileName: ["yellow"],
       },
@@ -150,6 +155,13 @@ export class BaseLogger<LogObj> {
     const subLoggerSettings: ISettings<LogObj> = {
       ...this.settings,
       ...settings,
+      // collect parent names in Array
+      parentNames:
+        this.settings?.parentNames != null && this.settings?.name != null
+          ? [...this.settings.parentNames, this.settings.name]
+          : this.settings?.name != null
+          ? [this.settings.name]
+          : undefined,
       // merge all prefixes instead of overwriting them
       prefix: [...this.settings.prefix, ...(settings?.prefix ?? [])],
     };
@@ -244,7 +256,7 @@ export class BaseLogger<LogObj> {
   private _addMetaToLogObj(logObj: LogObj, logLevelId: number, logLevelName: string): LogObj & ILogObjMeta & ILogObj {
     return {
       ...logObj,
-      [this.settings.metaProperty]: getMeta(logLevelId, logLevelName, this.stackDepthLevel),
+      [this.settings.metaProperty]: getMeta(logLevelId, logLevelName, this.stackDepthLevel, this.settings.name, this.settings.parentNames),
     };
   }
 
@@ -273,6 +285,10 @@ export class BaseLogger<LogObj> {
     placeholderValues["logLevelName"] = logObjMeta?.logLevelName;
     placeholderValues["filePathWithLine"] = logObjMeta?.path?.filePathWithLine;
     placeholderValues["fullFilePath"] = logObjMeta?.path?.fullFilePath;
+    // name
+    let parentNamesString = this.settings.parentNames?.join(this.settings.prettyErrorParentNamesSeparator);
+    parentNamesString = parentNamesString != null && logObjMeta?.name != null ? parentNamesString + this.settings.prettyErrorParentNamesSeparator : undefined;
+    placeholderValues["name"] = logObjMeta?.name != null || parentNamesString != null ? " " + (parentNamesString ?? "") + logObjMeta?.name ?? "" : "";
 
     return formatTemplate(this.settings, template, placeholderValues);
   }

src/interfaces.ts

@@ -10,11 +10,14 @@ export type TStyle =
 
 export interface ISettingsParam<LogObj> {
   type?: "json" | "pretty" | "hidden";
+  name?: string;
+  parentNames?: string[];
   minLevel?: number;
   argumentsArrayName?: string;
   prettyLogTemplate?: string;
   prettyErrorTemplate?: string;
   prettyErrorStackTemplate?: string;
+  prettyErrorParentNamesSeparator?: string;
   stylePrettyLogs?: boolean;
   prettyLogStyles?: {
     yyyy?: TStyle;
@@ -53,11 +56,14 @@ export interface ISettingsParam<LogObj> {
 
 export interface ISettings<LogObj> extends ISettingsParam<LogObj> {
   type: "json" | "pretty" | "hidden";
+  name?: string;
+  parentNames?: string[];
   minLevel: number;
   argumentsArrayName?: string;
   prettyLogTemplate: string;
   prettyErrorTemplate: string;
   prettyErrorStackTemplate: string;
+  prettyErrorParentNamesSeparator: string;
   stylePrettyLogs: boolean;
   prettyLogStyles: {
     yyyy?: TStyle;
@@ -73,6 +79,7 @@ export interface ISettings<LogObj> extends ISettingsParam<LogObj> {
     filePath?: TStyle;
     fileLine?: TStyle;
     filePathWithLine?: TStyle;
+    name?: TStyle;
     errorName?: TStyle;
     errorMessage?: TStyle;
   };

src/runtime/browser/index.ts

@@ -3,6 +3,8 @@ import { formatTemplate } from "../../formatTemplate";
 import { inspect } from "./util.inspect.polyfil";
 
 export interface IMetaStatic {
+  name?: string;
+  parentNames?: string[];
   runtime: string;
   browser: string;
 }
@@ -19,9 +21,10 @@ const meta: IMetaStatic = {
   browser: window?.["navigator"].userAgent,
 };
 
-export function getMeta(logLevelId: number, logLevelName: string, stackDepthLevel: number): IMeta {
+export function getMeta(logLevelId: number, logLevelName: string, stackDepthLevel: number, name?: string): IMeta {
   return {
     ...meta,
+    name,
     date: new Date(),
     logLevelId,
     logLevelName,

src/runtime/nodejs/index.ts

@@ -6,6 +6,8 @@ import { formatTemplate } from "../../formatTemplate";
 export { InspectOptions };
 
 export interface IMetaStatic {
+  name?: string;
+  parentNames?: string[];
   runtime: string;
   hostname: string;
 }
@@ -22,9 +24,11 @@ const meta: IMetaStatic = {
   hostname: hostname(),
 };
 
-export function getMeta(logLevelId: number, logLevelName: string, stackDepthLevel: number): IMeta {
+export function getMeta(logLevelId: number, logLevelName: string, stackDepthLevel: number, name?: string, parentNames?: string[]): IMeta {
   return {
     ...meta,
+    name,
+    parentNames,
     date: new Date(),
     logLevelId,
     logLevelName,