Refactor to default to structured logging.

- Added `flattenMessage` and `FlattenedLogMessage` to default to
  structured logging.
- Rework the logic formatting messages for the ConsoleLogger.
- Add a more comprehensive README.

src/api-log-appender.ts

@@ -1,20 +1,13 @@
-import { LogMessage, LogLevel } from './log-message';
-import LogAppender from './log-appender';
+import { LogMessage, LogLevel, flattenMessage, FlattenedLogMessage } from './log-message';
+import { LogAppender } from './log-appender';
 
-interface ApiMessage {
-  level: string;
-  message: string;
-  scope: string;
-  stacktrace: string;
-  timestamp: string;
-}
 export class ApiLogAppender implements LogAppender {
   public batchSize = 10;
   public minimumTimePassedInSec = 60;
   public maximumTimePassedInSec = 120;
   public threshold = LogLevel.ALL;
 
-  private msgBuffer: ApiMessage[] = [];
+  private msgBuffer: FlattenedLogMessage[] = [];
   private lastSent = 0;
 
   constructor(
@@ -33,16 +26,7 @@ export class ApiLogAppender implements LogAppender {
       return;
     }
 
-    this.msgBuffer.push({
-      level: LogLevel[msg.level],
-      message:
-        typeof msg.message === 'string'
-          ? msg.message
-          : JSON.stringify(msg.message),
-      scope: msg.scope,
-      stacktrace: msg.stacktrace,
-      timestamp: msg.timestamp.toISOString()
-    });
+    this.msgBuffer.push(flattenMessage(msg));
   }
 
   private doPost() {

src/console-log-appender.ts

@@ -1,14 +1,22 @@
-/*tslint:disable:no-console*/
-import { LogMessage, LogLevel } from './log-message';
-import LogAppender from './log-appender';
+import {
+  LogLevel,
+  LogMessage,
+  LogMessageFormatter,
+  structuredLogMessageFormatter
+} from './log-message';
+import { LogAppender } from './log-appender';
 
 export class ConsoleLogAppender implements LogAppender {
   public threshold = LogLevel.ALL;
+  public formatter = structuredLogMessageFormatter;
 
-  constructor(threshold?: LogLevel) {
+  constructor(threshold?: LogLevel, formatter?: LogMessageFormatter) {
     if (threshold) {
       this.threshold = threshold;
     }
+    if (formatter) {
+      this.formatter = formatter;
+    }
   }
 
   public appendMessage(msg: LogMessage): void {
@@ -42,12 +50,12 @@ export class ConsoleLogAppender implements LogAppender {
         break;
     }
 
-    if (msg.error) {
-      logMethod(`[${msg.scope}]:`, msg.message, msg.error);
-    } else if (msg.stacktrace) {
-      logMethod(`[${msg.scope}]:`, msg.message, msg.stacktrace);
+    const strMsg = this.formatter(msg);
+
+    if (msg.error || msg.stacktrace) {
+      logMethod(strMsg, msg.error ?? msg.stacktrace);
     } else {
-      logMethod(`[${msg.scope}]:`, msg.message);
+      logMethod(strMsg);
     }
   }
 }

src/log-appender.ts

@@ -1,5 +1,8 @@
 import { LogLevel, LogMessage } from './log-message';
-export default interface LogAppender {
+
+export interface LogAppender {
   threshold: LogLevel;
   appendMessage(message: LogMessage): void;
 }
+
+export default LogAppender;

src/log-message.ts

@@ -1,3 +1,5 @@
+import { omit } from './util'
+
 export enum LogLevel {
   ALL = 0,
   TRACE,
@@ -6,12 +8,15 @@ export enum LogLevel {
   INFO,
   WARN,
   ERROR,
-  FATAL
+  FATAL,
 }
 
-export function parseLogLevel(str: string, defaultLevel = LogLevel.INFO): LogLevel {
-  if (Object.prototype.hasOwnProperty.call(LogLevel, str)) {
-    return LogLevel[<any>str] as unknown as LogLevel;
+export function parseLogLevel(
+  str: string,
+  defaultLevel = LogLevel.INFO,
+): LogLevel {
+  if (str in LogLevel) {
+    return LogLevel[str as keyof typeof LogLevel] as LogLevel;
   } else {
     return defaultLevel;
   }
@@ -20,10 +25,59 @@ export function parseLogLevel(str: string, defaultLevel = LogLevel.INFO): LogLev
 export interface LogMessage {
   scope: string;
   level: LogLevel;
-  message: string | object;
-  stacktrace: string;
+  message: string | Record<string, unknown>;
+  stacktrace?: string;
   error?: Error;
   timestamp: Date;
 }
 
+export type FlattenedLogMessage = Record<string, unknown>;
+
+/**
+ * Flatten a log message to a plain object. The *message* field can be either a
+ * string or an object. In the case of an object message, the LogMessage should
+ * be flattened before being emitted by an appender, promoting the object's
+ * fields to the top level of the message. Fields defined on the *LogMessage*
+ * interface are reserved and should not be used as keys in the message object
+ * (and will be ignored if they are).
+ *
+ * So, for example:
+ *
+ * ```typescript
+ * const logger = logService.getLogger('example');
+ * logger.info({ foo: 'bar', baz: 'qux', timestamp: 'today', level: LogLevel.WARN });
+ * ```
+ *
+ * Should result after flattening in a structured log message like:
+ * ```json
+ * {"scope":"example","level":4,"foo":"bar","baz":"qux","timestamp":"2020-01-01T00:00:00.000Z"}
+ * ```
+ */
+export function flattenMessage(msg: LogMessage): FlattenedLogMessage {
+  if (typeof msg.message === 'string') {
+    return { ...msg };
+  } else {
+    const { message, ...rest } = msg;
+    return {
+      ...omit(message, [
+        'scope',
+        'level',
+        'stacktrace',
+        'error',
+        'timestamp',
+      ]),
+      ...rest,
+    };
+  }
+}
+export type LogMessageFormatter = (msg: LogMessage) => string;
+
+export function structuredLogMessageFormatter(msg: LogMessage): string {
+  return JSON.stringify(flattenMessage(msg));
+}
+
+export function simpleTextLogMessageFormatter(msg: LogMessage): string {
+  return `[${msg.scope}] - ${msg.level}: ${msg.message}`;
+}
+
 export default LogMessage;

src/log-service.ts

@@ -1,10 +1,16 @@
 import { LogLevel } from './log-message';
-import Logger from './logger';
+import { Logger } from './logger';
 
 const ROOT_LOGGER_NAME = 'ROOT';
 
+/**
+ * Service for managing loggers. A LogService instance defines
+ * the service context for a set of loggers. Typically there is only one
+ * LogService instance per application, the one exported as default from this
+ * module.
+ */
 export class LogService {
-  private loggers: { [key: string]: Logger };
+  private loggers: Record<string, Logger>;
 
   public get ROOT_LOGGER() {
     return this.loggers[ROOT_LOGGER_NAME];
@@ -15,10 +21,38 @@ export class LogService {
     this.loggers[ROOT_LOGGER_NAME] = new Logger(
       ROOT_LOGGER_NAME,
       undefined,
-      LogLevel.ALL
+      LogLevel.ALL,
     );
   }
 
+  /**
+   * Get a logger by name. If the logger does not exist, it will be created.
+   * Loggers are hierarchical, with the heirarchy defined by the logger name.
+   * When creating a new logger, the parent logger is determined by the longest
+   * existing logger name that is a prefix of the new logger name. For example,
+   * if a logger with the name "foo" already exists, any subsequent loggers
+   * with the names "foo.bar", "foo/bar", "foolish.choice", etc. will be
+   * created as children of the "foo" logger.
+   *
+   * As another example, given the following invocations:
+   *
+   * ```typescript
+   * logService.getLogger('foo');
+   * logService.getLogger('foo.bar');
+   * logService.getLogger('foo.bar.baz');
+   * logService.getLogger('foo.qux');
+   * ```
+   *
+   * will result in the following logging hierarchy:
+   *
+   *     foo
+   *     ├─foo.bar
+   *     │ └─foo.bar.baz
+   *     └─foo.qux
+   *
+   * See the Logger class for details on how loggers are used and the
+   * implications of the logger hierarchy.
+   */
   public getLogger(name: string, threshold?: LogLevel): Logger {
     if (this.loggers[name]) {
       return this.loggers[name];
@@ -30,7 +64,7 @@ export class LogService {
       .filter((n: string) => name.startsWith(n))
       .reduce(
         (acc: string, cur: string) => (acc.length > cur.length ? acc : cur),
-        ''
+        '',
       );
 
     if (parentLoggerName) {

src/logger.ts

@@ -1,16 +1,52 @@
-import { LogMessage, LogLevel } from './log-message';
-import LogAppender from './log-appender';
+import { LogLevel, LogMessage } from './log-message';
+import { LogAppender } from './log-appender';
 
-export type DeferredMsg = () => string | object;
-export type MessageType = string | DeferredMsg | object;
+export type DeferredMsg = () => string | Record<string, unknown>;
+export type MessageType = string | DeferredMsg | Record<string, unknown>;
 
+export function isDeferredMsg(msg: MessageType): msg is DeferredMsg {
+  return typeof msg === 'function';
+}
+
+/**
+ * Logger class for logging messages.
+ *
+ * Loggers are used to log messages at different levels. The levels are, in
+ * order of increasing severity: TRACE, DEBUG, LOG, INFO, WARN, ERROR, FATAL.
+ * Log messages can be logged at a specific level by calling the corresponding
+ * method on the logger instance. For example, to log a message at the INFO
+ * level, call the *info* method on the logger.
+ *
+ * Loggers have a threshold level, which is the minimum level of log message
+ * that will be logged by the logger. Log messages with a level below the
+ * threshold will be ignored. The threshold level can be set when creating a
+ * logger, or by calling the *setThreshold* method on an existing logger. If a
+ * threshold is not set, the logger will use the threshold of its parent
+ * logger.
+ *
+ * Loggers are hierarchical, with the hierarchy defined by the logger name.
+ * The heirarchy is tracked by the children: child loggers have a link to their
+ * parents, while parent loggers do not have a list of their children.
+ *
+ * When a log message is logged by a logger, it is sent to all of the appenders
+ * attached to the logger and to the parent logger. Appenders can be attached
+ * to any Logger instance, but, because of this upwards propogation, appenders
+ * are usually attached to the root logger, which is an ancestor of all loggers
+ * created by the same LogService instance.
+ *
+ * Loggers are typically created and managed by a LogService instance.  The
+ * *LogService#getLogger* method is used to get a logger by name, creating it
+ * if necessary. When creating a new logger, the parent logger is determined by
+ * the longest existing logger name that is a prefix of the new logger name.
+ * For more details, see *LogService#getLogger*.
+ */
 export class Logger {
   public appenders: LogAppender[] = [];
 
   public constructor(
     public readonly name: string,
     private parentLogger?: Logger,
-    public threshold?: LogLevel
+    public threshold?: LogLevel,
   ) {}
 
   public createChildLogger(name: string, threshold?: LogLevel): Logger {
@@ -20,7 +56,7 @@ export class Logger {
   public doLog(
     level: LogLevel,
     message: Error | MessageType,
-    stacktrace?: string
+    stacktrace?: string,
   ): void {
     if (level < this.getEffectiveThreshold()) {
       return;
@@ -31,20 +67,20 @@ export class Logger {
       level,
       message: '',
       stacktrace: '',
-      timestamp: new Date()
+      timestamp: new Date(),
     };
 
     if (message === undefined || message === null) {
       logMsg.message = message;
-      logMsg.stacktrace = stacktrace == null ? '' : stacktrace;
-    } else if ((message as DeferredMsg).call !== undefined) {
-      logMsg.message = (message as DeferredMsg)();
-      logMsg.stacktrace = stacktrace == null ? '' : stacktrace;
+      logMsg.stacktrace = stacktrace ?? '';
     } else if (message instanceof Error) {
       const error = message as Error;
       logMsg.error = error;
       logMsg.message = `${error.name}: ${error.message}`;
-      logMsg.stacktrace = error.stack == null ? '' : error.stack;
+      logMsg.stacktrace = stacktrace ?? error.stack ?? '';
+    } else if (isDeferredMsg(message)) {
+      logMsg.message = message();
+      logMsg.stacktrace = stacktrace == null ? '' : stacktrace;
     } else {
       // string | object
       logMsg.message = message;
@@ -83,7 +119,7 @@ export class Logger {
   }
 
   protected sendToAppenders(logMsg: LogMessage) {
-    this.appenders.forEach(app => {
+    this.appenders.forEach((app) => {
       app.appendMessage(logMsg);
     });
 

src/util.ts

@@ -0,0 +1,12 @@
+export function omit(
+  obj: Record<string, unknown>,
+  keys: string[],
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const key in obj) {
+    if (!keys.includes(key)) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}