@travetto/log 3.1.2 → 3.1.4

package/README.md

@@ -15,8 +15,40 @@ yarn add @travetto/log
 
 This module provides logging functionality, building upon [ConsoleManager](https://github.com/travetto/travetto/tree/main/module/base/src/console.ts) in the [Base](https://github.com/travetto/travetto/tree/main/module/base#readme "Environment config and common utilities for travetto applications.") module.  This is all ultimately built upon [console](https://nodejs.org/api/console.html) operations. The logging infrastructure is built upon the [Dependency Injection](https://github.com/travetto/travetto/tree/main/module/di#readme "Dependency registration/management and injection support.") system, and so new loggers can be created that rely upon dependency injected services and sources.
 
+## Extending the Common Logger
+By default, the system ships with the [CommonLogger](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L11), and by default will leverage the [LineLogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/formatter/line.ts#L36) and the [ConsoleLogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/appender/console.ts#L7). The configuration [CommonLoggerConfig](https://github.com/travetto/travetto/tree/main/module/log/src/common.ts#L11) provides two configuration variables that allows for switching out [LineLogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/formatter/line.ts#L36) for the [JsonLogFormatter](https://github.com/travetto/travetto/tree/main/module/log/src/formatter/json.ts#L16), depending on the value of `CommonLoggerConfig.format`.  Additionally the [ConsoleLogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/appender/console.ts#L7) can be swapped out for the [FileLogAppender](https://github.com/travetto/travetto/tree/main/module/log/src/appender/file.ts#L10) depending on the value of `CommonLoggerConfig.output`.
+
+**Code: Standard Logging Config**
+```typescript
+export class CommonLoggerConfig {
+  @EnvVar('TRV_LOG_FORMAT')
+  format: 'line' | 'json' = 'line';
+
+  @EnvVar('TRV_LOG_OUTPUT')
+  output: 'console' | 'file' | string = 'console';
+}
+```
+
+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Ⲑ`.
+
+**Code: Sample Common Formatter**
+```typescript
+import { Injectable } from '@travetto/di';
+import { LogFormatter, LogCommonⲐ, LogEvent } from '@travetto/log';
+
+@Injectable(LogCommonⲐ)
+export class SampleFormatter implements LogFormatter {
+
+  format(e: LogEvent): string {
+    return `${e.timestamp} [${e.level}]#[${e.scope ?? 'unknown'}] ${e.message ?? 'NO MESSAGE'} ${(e.args ?? []).join(' ')}`;
+  }
+}
+```
+
+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.
+
 ## 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#L33) 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#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.
 
 **Code: Logger Shape**
 ```typescript
@@ -61,7 +93,7 @@ export type ConsoleEvent = {
 };
 ```
 
-The [LogEvent](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L5) is an extension of the [ConsoleEvent](https://github.com/travetto/travetto/tree/main/module/base/src/types.ts#L12) with the addition of two fields:
+The [LogEvent](https://github.com/travetto/travetto/tree/main/module/log/src/types.ts#L8) is an extension of the [ConsoleEvent](https://github.com/travetto/travetto/tree/main/module/base/src/types.ts#L12) with the addition of two fields:
    *  `message` - This is the primary argument passed to the console statement, if it happens to be a string, otherwise the field is left empty
    *  `context` - This is the final argument passed to the console statement, if it happens to be a simple object.  This is useful for external loggers that allow for searching/querying by complex data
 
@@ -93,39 +125,16 @@ The main caveat that comes with this, is that not all objects can be converted t
 **Code: Standard Logging Config**
 ```typescript
 export class CommonLoggerConfig {
-  @EnvVar('TRV_LOG_COMMON')
-  commonActive?: boolean;
-
-  /** Should we enrich the console by default */
   @EnvVar('TRV_LOG_FORMAT')
   format: 'line' | 'json' = 'line';
 
-  /** Log file, if needed */
-  @EnvVar('TRV_LOG_FILE')
-  file?: string;
-
-  @EnvVar('TRV_LOG_PLAIN')
-  plain?: boolean;
-
-  @EnvVar('TRV_LOG_TIME')
-  time: 's' | 'ms' | string = 'ms';
-
-  @Ignore()
-  get timestamp(): 's' | 'ms' | false {
-    return (this.time ?? 'ms') === 'ms' ? 'ms' : (this.time === 's' ? 's' : false);
-  }
-
-  postConstruct(): void {
-    if (GlobalEnv.test) {
-      this.time = '';
-    }
-    this.plain ??= GlobalTerminal.colorLevel === 0;
-  }
+  @EnvVar('TRV_LOG_OUTPUT')
+  output: 'console' | 'file' | string = 'console';
 }
 ```
 
 The following environment variables have control over the default logging config:
    *  `TRV_LOG_FORMAT` - This determines whether or not the output is standard text lines, or is it output as a single line of [JSON](https://www.json.org)
-   *  `TRV_LOG_FILE` - This determines whether or not the logging goes to the console or if it is written to a file
+   *  `TRV_LOG_OUTPUT` - This determines whether or not the logging goes to the console or if it is written to a file
    *  `TRV_LOG_PLAIN` - Allows for an override of whether or not to log colored output, this defaults to values provided by the [Terminal](https://github.com/travetto/travetto/tree/main/module/terminal#readme "General terminal support") in response to `FORCE_COLOR` and `NO_COLOR`
    *  `TRV_LOG_TIME` - This represents what level of time logging is desired, the default is `ms` which is millisecond output.  A value of `s` allows for second level logging, and `false` will disable the output. When ingesting the content into another logging, its generally desirable to suppress the initial time output as most other loggers will append as needed.

package/__index__.ts

@@ -1,6 +1,7 @@
 export * from './src/service';
 export * from './src/formatter/json';
 export * from './src/formatter/line';
+export * from './src/formatter/google';
 export * from './src/appender/console';
 export * from './src/appender/file';
 export * from './src/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/log",
-  "version": "3.1.2",
+  "version": "3.1.4",
   "description": "Logging framework that integrates at the console.log level.",
   "keywords": [
     "typescript",

package/src/appender/console.ts

@@ -1,10 +1,26 @@
-import { Appender, LogEvent } from '../types';
+import { Injectable } from '@travetto/di';
+import { Config } from '@travetto/config';
+
+import { LogAppender, LogEvent } from '../types';
+
+@Config('log')
+export class ConsoleLogAppenderConfig {
+  logToLevel = true;
+}
 
 /**
- * Console.output
+ * Console Logging Appender
  */
-export class ConsoleAppender implements Appender {
+@Injectable()
+export class ConsoleLogAppender implements LogAppender {
+
+  config: ConsoleLogAppenderConfig;
+
+  constructor(config: ConsoleLogAppenderConfig) {
+    this.config = config;
+  }
+
   append(ev: LogEvent, formatted: string): void {
-    console![ev.level](formatted);
+    console![this.config.logToLevel ? ev.level : 'log'](formatted);
   }
 }

package/src/appender/file.ts

@@ -1,24 +1,33 @@
-import { createWriteStream, WriteStream } from 'fs';
-import { Appender, LogEvent } from '../types';
+import { createWriteStream, WriteStream, mkdirSync } from 'fs';
 
-/**
- * File appender options
- */
-export interface FileAppenderOpts {
-  file: string;
+import { Injectable } from '@travetto/di';
+import { Config, EnvVar } from '@travetto/config';
+import { path, RootIndex } from '@travetto/manifest';
+
+import { LogAppender, LogEvent } from '../types';
+
+@Config('log')
+export class FileLogAppenderConfig {
+  @EnvVar('TRV_LOG_OUTPUT')
+  output?: 'file' | string;
+
+  postConstruct(): void {
+    if (!this.output || this.output === 'file' || this.output === 'console') {
+      this.output = path.resolve(RootIndex.manifest.toolFolder, 'logs', `${RootIndex.manifest.mainModule}.log`);
+    }
+  }
 }
 
 /**
- * File appender logger
+ * File Logging Appender
  */
-export class FileAppender implements Appender {
+@Injectable()
+export class FileLogAppender implements LogAppender {
   stream: WriteStream;
 
-  constructor(opts: FileAppenderOpts) {
-    this.stream = createWriteStream(opts.file, {
-      autoClose: true,
-      flags: 'a'
-    });
+  constructor(opts: FileLogAppenderConfig) {
+    mkdirSync(path.dirname(opts.output!), { recursive: true });
+    this.stream = createWriteStream(opts.output!, { autoClose: true, flags: 'a' });
   }
 
   append(ev: LogEvent, formatted: string): void {

package/src/common.ts

@@ -1,69 +1,39 @@
-import { GlobalEnv } from '@travetto/base';
 import { Config, EnvVar } from '@travetto/config';
-import { Inject, Injectable } from '@travetto/di';
-import { Ignore } from '@travetto/schema';
-import { GlobalTerminal } from '@travetto/terminal';
+import { DependencyRegistry, Inject, Injectable } from '@travetto/di';
 
-import { ConsoleAppender } from './appender/console';
-import { FileAppender } from './appender/file';
-import { JsonFormatter } from './formatter/json';
-import { LineFormatter } from './formatter/line';
-import { Appender, Formatter, LogEvent } from './types';
+import { ConsoleLogAppender } from './appender/console';
+import { FileLogAppender } from './appender/file';
+import { JsonLogFormatter } from './formatter/json';
+import { LineLogFormatter } from './formatter/line';
+import { LogAppender, LogFormatter, LogEvent, LogCommonⲐ, Logger } from './types';
 
 @Config('log')
 export class CommonLoggerConfig {
-  @EnvVar('TRV_LOG_COMMON')
-  commonActive?: boolean;
-
-  /** Should we enrich the console by default */
   @EnvVar('TRV_LOG_FORMAT')
   format: 'line' | 'json' = 'line';
 
-  /** Log file, if needed */
-  @EnvVar('TRV_LOG_FILE')
-  file?: string;
-
-  @EnvVar('TRV_LOG_PLAIN')
-  plain?: boolean;
-
-  @EnvVar('TRV_LOG_TIME')
-  time: 's' | 'ms' | string = 'ms';
-
-  @Ignore()
-  get timestamp(): 's' | 'ms' | false {
-    return (this.time ?? 'ms') === 'ms' ? 'ms' : (this.time === 's' ? 's' : false);
-  }
-
-  postConstruct(): void {
-    if (GlobalEnv.test) {
-      this.time = '';
-    }
-    this.plain ??= GlobalTerminal.colorLevel === 0;
-  }
+  @EnvVar('TRV_LOG_OUTPUT')
+  output: 'console' | 'file' | string = 'console';
 }
 
 @Injectable()
-export class CommonLogger {
-  #appender: Appender;
-  #formatter: Formatter;
+export class CommonLogger implements Logger {
 
   @Inject()
   config: CommonLoggerConfig;
 
-  get active(): boolean {
-    return this.config.commonActive !== false;
-  }
+  @Inject(LogCommonⲐ, { optional: true })
+  formatter: LogFormatter;
+
+  @Inject(LogCommonⲐ, { optional: true })
+  appender: LogAppender;
 
-  postConstruct(): void {
-    this.#formatter = this.config.format === 'line' ?
-      new LineFormatter(this.config) :
-      new JsonFormatter();
-    this.#appender = this.config.file ?
-      new FileAppender({ file: this.config.file }) :
-      new ConsoleAppender();
+  async postConstruct(): Promise<void> {
+    this.formatter ??= await DependencyRegistry.getInstance(this.config.format === 'line' ? LineLogFormatter : JsonLogFormatter);
+    this.appender ??= await DependencyRegistry.getInstance(this.config.output !== 'console' ? FileLogAppender : ConsoleLogAppender);
   }
 
   onLog(ev: LogEvent): void {
-    this.#appender.append(ev, this.#formatter.format(ev));
+    this.appender.append(ev, this.formatter.format(ev));
   }
 }

package/src/formatter/google.ts

@@ -0,0 +1,34 @@
+import util from 'util';
+
+import { Injectable } from '@travetto/di';
+
+import { LogFormatter, LogEvent } from '../types';
+
+/**
+ * Google Logging Formatter
+ *
+ * Provides a standard google logging provider that adapts the content for google's logging structure
+ */
+@Injectable()
+export class GoogleLogFormatter implements LogFormatter {
+  format({
+    source: file, line, scope, level, message, timestamp, module, args,
+    context: { method, path, statusCode, ...context } = {},
+  }: LogEvent): string {
+    return JSON.stringify({
+      context,
+      'logging.googleapis.com/sourceLocation': { file, line },
+      'logging.googleapis.com/labels': { module, scope },
+      severity: level,
+      message: util.format(message, ...args, ...Object.entries(context).map(([k, v]) => util.format('%s=%s', k, v))),
+      timestamp,
+      ...(method ? {
+        httpRequest: {
+          requestMethod: method,
+          requestUrl: path,
+          status: statusCode
+        }
+      } : {})
+    });
+  }
+}

package/src/formatter/json.ts

@@ -1,23 +1,26 @@
-import { LogEvent, Formatter } from '../types';
+import { Injectable } from '@travetto/di';
+import { Config, EnvVar } from '@travetto/config';
 
-/**
- * JSON Options
- */
-export interface JSONFormatterOpts {
-  depth?: number;
+import { LogEvent, LogFormatter } from '../types';
+
+@Config('log')
+export class JSONLogFormatterConfig {
+  @EnvVar('TRV_LOG_JSON_INDENT')
+  jsonIndent?: number;
 }
 
 /**
- * JSON Formatter
+ * JSON Logging Formatter
  */
-export class JsonFormatter implements Formatter {
-  #opts: JSONFormatterOpts;
+@Injectable()
+export class JsonLogFormatter implements LogFormatter {
+  opts: JSONLogFormatterConfig;
 
-  constructor(opts: JSONFormatterOpts = {}) {
-    this.#opts = opts;
+  constructor(opts: JSONLogFormatterConfig) {
+    this.opts = opts;
   }
 
   format(ev: LogEvent): string {
-    return JSON.stringify(ev, null, this.#opts.depth);
+    return JSON.stringify(ev, null, this.opts.jsonIndent);
   }
 }

package/src/formatter/line.ts

@@ -1,8 +1,12 @@
 import util from 'util';
 
 import { GlobalTerminal } from '@travetto/terminal';
+import { Injectable } from '@travetto/di';
+import { Config, EnvVar } from '@travetto/config';
+import { GlobalEnv } from '@travetto/base';
+import { Ignore } from '@travetto/schema';
 
-import { LogEvent, Formatter } from '../types';
+import { LogEvent, LogFormatter } from '../types';
 
 /**
  * Level coloring
@@ -28,27 +32,56 @@ export interface LineFormatterOpts {
   location?: boolean;
 }
 
+@Config('log')
+export class LineLogFormatterConfig {
+  @EnvVar('TRV_LOG_PLAIN')
+  plain?: boolean;
+
+  @EnvVar('TRV_LOG_TIME')
+  time?: 's' | 'ms' | string;
+
+  colorize?: boolean;
+  align?: boolean;
+  level?: boolean;
+  location?: boolean;
+
+  @Ignore()
+  timestamp?: 's' | 'ms';
+
+  postConstruct(): void {
+    if (GlobalEnv.test) {
+      this.plain = true;
+      this.time = undefined;
+    }
+    this.time ??= (!this.plain ? 'ms' : undefined);
+    this.plain ??= GlobalTerminal.colorLevel === 0;
+    this.colorize ??= !this.plain;
+    this.location ??= !this.plain;
+    this.level ??= !this.plain;
+    this.align ??= !this.plain;
+    if (this.time !== undefined && this.time === 'ms' || this.time === 's') {
+      this.timestamp = this.time;
+    }
+  }
+}
+
 /**
- * Line formatter
+ * Line Logging Formatter
  */
-export class LineFormatter implements Formatter {
-  #opts: LineFormatterOpts;
-
-  constructor(opts: LineFormatterOpts = {}) {
-    const notPlain = opts.plain !== true;
-    this.#opts = {
-      colorize: notPlain,
-      timestamp: notPlain ? opts.timestamp : undefined,
-      align: true, level: notPlain, location: notPlain,
-      ...opts
-    };
+@Injectable()
+export class LineLogFormatter implements LogFormatter {
+
+  opts: LineLogFormatterConfig;
+
+  constructor(opts: LineLogFormatterConfig) {
+    this.opts = opts;
   }
 
   pretty(ev: LogEvent, o: unknown): string {
     return util.inspect(o, {
       showHidden: ev.level === 'debug',
       depth: 4,
-      colors: this.#opts.colorize !== false,
+      colors: this.opts.colorize !== false,
       breakLength: 100
     });
   }
@@ -57,35 +90,34 @@ export class LineFormatter implements Formatter {
    * Format an event into a single line
    */
   format(ev: LogEvent): string {
-    const opts = this.#opts;
     const out = [];
 
-    if (opts.timestamp) {
+    if (this.opts.timestamp) {
       let timestamp = ev.timestamp.toISOString();
-      if (opts.timestamp === 's') {
+      if (this.opts.timestamp === 's') {
         timestamp = timestamp.replace(/[.]\d{3}/, '');
       }
-      if (opts.colorize) {
+      if (this.opts.colorize) {
         timestamp = STYLES.timestamp(timestamp);
       }
       out.push(timestamp);
     }
 
-    if (opts.level) {
+    if (this.opts.level) {
       let level: string = ev.level;
-      if (opts.align) {
+      if (this.opts.align) {
         level = level.padEnd(5, ' ');
       }
-      if (opts.colorize) {
+      if (this.opts.colorize) {
         level = STYLES[ev.level](level);
       }
       out.push(level);
     }
 
-    if (ev.source && opts.location) {
+    if (ev.source && this.opts.location) {
       const ns = `${ev.module}:${ev.modulePath}`;
       let loc = ev.line ? `${ns}:${ev.line}` : ns;
-      if (opts.colorize) {
+      if (this.opts.colorize) {
         loc = STYLES.location(loc);
       }
       out.push(`[${loc}]`);

package/src/internal/types.ts

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

package/src/service.ts

@@ -20,17 +20,17 @@ export class LogService implements ConsoleListener, AutoCreate {
   async postConstruct(): Promise<void> {
     await GlobalTerminal.init();
 
-    const def = await DependencyRegistry.getInstance(CommonLogger);
-    if (def.active) {
-      this.#listeners.push(def);
-    }
+    const loggers = DependencyRegistry.getCandidateTypes(LoggerTarget).filter(c => c.class !== CommonLogger);
 
-    const loggers = DependencyRegistry.getCandidateTypes(LoggerTarget);
-    const instances = await Promise.all(loggers.map(l => DependencyRegistry.getInstance<Logger>(l.class, l.qualifier)));
-    for (const inst of instances) {
-      this.#listeners.push(inst);
+    // 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));
     }
-
     // Take over
     ConsoleManager.set(this, true);
   }

package/src/types.ts

@@ -1,4 +1,7 @@
 import { ConsoleEvent } from '@travetto/base';
+
+export const LogCommonⲐ = Symbol.for('@travetto/log:common');
+
 /**
  * Logging event
  */
@@ -15,15 +18,17 @@ export interface LogEvent extends ConsoleEvent {
 
 /**
  * Output appender for the logger
+ * @concrete ./internal/types:LogAppenderTarget
  */
-export interface Appender {
+export interface LogAppender {
   append(ev: LogEvent, formatted: string): void;
 }
 
 /**
  * Output formatter
+ * @concrete ./internal/types:LogFormatterTarget
  */
-export interface Formatter {
+export interface LogFormatter {
   format(e: LogEvent): string;
 }