@travetto/log 3.3.1 → 3.3.3

package/README.md

@@ -29,7 +29,7 @@ export class CommonLoggerConfig {
 }
 ```
 
-In addition to these simple overrides, the [CommonLogger](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L11) can be extended by providing an implementation of either a [LogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L31) or [LogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L23), with the declared symbol of `LogCommonⲐ`.
+In addition to these simple overrides, the [CommonLogger](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L11) can be extended by providing an implementation of either a [LogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L38) or [LogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L30), with the declared symbol of `LogCommonⲐ`.
 
 **Code: Sample Common Formatter**
 ```typescript
@@ -45,10 +45,10 @@ export class SampleFormatter implements LogFormatter {
 }
 ```
 
-As you can see, implementing [LogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L31)/[LogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L23) with the appropriate symbol is all that is necessary to customize the general logging functionality.
+As you can see, implementing [LogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L38)/[LogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L30) with the appropriate symbol is all that is necessary to customize the general logging functionality.
 
 ## Creating a Logger
-The default pattern for logging is to create a [Logger](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L38) which simply consumes a logging event. The method is not asynchronous as ensuring the ordering of append calls will be the responsibility of the logger.  The default logger uses `console.log` and that is synchronous by default.
+The default pattern for logging is to create a [Logger](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L45) which simply consumes a logging event. The method is not asynchronous as ensuring the ordering of append calls will be the responsibility of the logger.  The default logger uses `console.log` and that is synchronous by default.
 
 **Code: Logger Shape**
 ```typescript
@@ -113,6 +113,38 @@ export class CustomLogger implements Logger {
 }
 ```
 
+## Creating a Decorator
+In addition to being able to control the entire logging experience, there are also scenarios in which the caller may want to only add information to the log event, without affecting control of the formatting or appending. The [Logger](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L22) is an interface that provides a contract that allows transforming the [LogEvent](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L8) data. A common scenario for this would be to add additional metadata data (e.g. server name, ip, code revision, CPU usage, memory usage, etc) into the log messages.
+
+**Code: Log Decorator Shape**
+```typescript
+export interface LogDecorator {
+  decorate(ev: LogEvent): LogEvent;
+}
+```
+
+**Code: Custom Logger**
+```typescript
+import os from 'os';
+
+import { Injectable } from '@travetto/di';
+import { LogDecorator, LogEvent } from '@travetto/log';
+
+@Injectable()
+export class CustomDecorator implements LogDecorator {
+  decorate(ev: LogEvent): LogEvent {
+
+    // Add memory usage, and hostname
+    Object.assign(ev.context ??= {}, {
+      memory: process.memoryUsage,
+      hostname: os.hostname()
+    });
+
+    return ev;
+  }
+}
+```
+
 ## Logging to External Systems
 By default the logging functionality logs messages directly to the console, relying on the `util.inspect` method, as is the standard behavior.  When building distributed systems, with multiple separate logs, it is useful to rely on structured logging for common consumption.  The framework supports logging as [JSON](https://www.json.org), which is easily consumable by services like [elasticsearch](https://elastic.co) or [AWS Cloudwatch](https://aws.amazon.com/cloudwatch/) if running as a lambda or in a docker container. 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/log",
-  "version": "3.3.1",
+  "version": "3.3.3",
   "description": "Logging framework that integrates at the console.log level.",
   "keywords": [
     "typescript",
@@ -23,9 +23,9 @@
     "directory": "module/log"
   },
   "dependencies": {
-    "@travetto/config": "^3.3.1",
-    "@travetto/di": "^3.3.1",
-    "@travetto/terminal": "^3.3.0"
+    "@travetto/config": "^3.3.3",
+    "@travetto/di": "^3.3.3",
+    "@travetto/terminal": "^3.3.1"
   },
   "travetto": {
     "displayName": "Logging"

package/src/internal/types.ts

@@ -1,3 +1,4 @@
 export class LogAppenderTarget { }
 export class LogFormatterTarget { }
-export class LoggerTarget { }
+export class LogDecoratorTarget { }
+export class LoggerTarget { }

package/src/service.ts

@@ -2,8 +2,8 @@ import { ObjectUtil, ConsoleListener, ConsoleManager, ConsoleEvent } from '@trav
 import { AutoCreate, DependencyRegistry, Injectable } from '@travetto/di';
 import { GlobalTerminal } from '@travetto/terminal';
 
-import { LogEvent, Logger } from './types';
-import { LoggerTarget } from './internal/types';
+import { LogDecorator, LogEvent, Logger } from './types';
+import { LogDecoratorTarget, LoggerTarget } from './internal/types';
 import { CommonLogger } from './common';
 
 /**
@@ -13,24 +13,25 @@ import { CommonLogger } from './common';
 export class LogService implements ConsoleListener, AutoCreate {
 
   /**
-   * List of all listeners
+   * Log listeners
    */
   #listeners: Logger[] = [];
 
+  /**
+   * Log decorators
+   */
+  #decorators: LogDecorator[] = [];
+
   async postConstruct(): Promise<void> {
     await GlobalTerminal.init();
 
-    const loggers = DependencyRegistry.getCandidateTypes(LoggerTarget).filter(c => c.class !== CommonLogger);
-
-    // If the user specified logger(s) directly, load them all
-    if (loggers.length) {
-      const instances = await Promise.all(loggers.map(l => DependencyRegistry.getInstance<Logger>(l.class, l.qualifier)));
-      for (const inst of instances) {
-        this.#listeners.push(inst);
-      }
-    } else { // Otherwise fall back to the common logger
-      this.#listeners.push(await DependencyRegistry.getInstance(CommonLogger));
+    this.#listeners = await DependencyRegistry.getCandidateInstances<Logger>(LoggerTarget, c => c.class !== CommonLogger);
+    if (!this.#listeners.length) {
+      this.#listeners = [await DependencyRegistry.getInstance(CommonLogger)];
     }
+
+    this.#decorators = await DependencyRegistry.getCandidateInstances<LogDecorator>(LogDecoratorTarget);
+
     // Take over
     ConsoleManager.set(this, true);
   }
@@ -40,27 +41,29 @@ export class LogService implements ConsoleListener, AutoCreate {
    */
   onLog(ev: ConsoleEvent): void {
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions, prefer-const
-    let [message, context, ...args] = ev.args as [string, Record<string, unknown>, ...unknown[]];
+    let [message, context, ...args] = ev.args as [string | undefined, Record<string, unknown>, ...unknown[]];
     if (!ObjectUtil.isPlainObject(context)) {
-      args.unshift(context);
+      if (context !== undefined) {
+        args.unshift(context);
+      }
       context = {};
     }
 
-    if (typeof message !== 'string') {
+    if (typeof message !== 'string' && message !== undefined) {
       args.unshift(message);
-      message = '';
+      message = undefined;
     }
 
     // Allow for controlled order of event properties
-    const finalEvent: LogEvent = {
-      ...ev,
-      message: message !== '' ? message : undefined,
-      context,
-      args: args.filter(x => x !== undefined)
-    };
+    let outEvent: LogEvent = { ...ev, message, context, args };
+
+    // Decorate event as needed
+    for (const d of this.#decorators) {
+      outEvent = d.decorate(outEvent);
+    }
 
     for (const l of this.#listeners) {
-      l.onLog(finalEvent);
+      l.onLog(outEvent);
     }
   }
 }

package/src/types.ts

@@ -16,6 +16,13 @@ export interface LogEvent extends ConsoleEvent {
   context?: Record<string, unknown>;
 }
 
+/**
+ * @concrete ./internal/types:LogDecoratorTarget
+ */
+export interface LogDecorator {
+  decorate(ev: LogEvent): LogEvent;
+}
+
 /**
  * Output appender for the logger
  * @concrete ./internal/types:LogAppenderTarget