feat(logger): support JSON log output

tsushanth · tsushanth · commit 376c7b4f0cb0 · 2026-06-10T10:00:39.000-07:00
Adds an opt-in `jsonOutput` mode that emits a single-line JSON object per log call instead of ANSI-coloured text. Each entry carries the `level` ("debug" | "info" | "warn" | "error") and `message`; when `shouldIncludeTimestamp` is also set, an ISO `timestamp` field is included alongside. This addresses the case in #1991 where a Datadog ingestion pipeline (or any other log consumer) sees every line as unstructured text and defaults `error` records to `info`. The third constructor parameter is now `boolean | LoggerOptions`. The boolean form preserves the existing call sites verbatim (`new Logger(stdout, INFO, true)`); the options form unlocks the new `jsonOutput` flag and remains forward-compatible. A `setJsonOutput` runtime toggle is also exposed alongside the existing `setShouldIncludeTime`. Tests cover both modes — log-level gating, timestamp inclusion / omission, ANSI-stripping in JSON mode, and a JSON→text toggle.
diff --git a/packages/base/src/helpers/__tests__/logger.test.ts b/packages/base/src/helpers/__tests__/logger.test.ts
@@ -0,0 +1,126 @@
+import {Logger, LogLevel} from '../logger'
+
+describe('Logger', () => {
+  const collect = () => {
+    const lines: string[] = []
+    const write = (s: string) => {
+      lines.push(s)
+    }
+
+    return {lines, write}
+  }
+
+  describe('text mode (default)', () => {
+    it('writes each level with a trailing newline', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.DEBUG)
+
+      logger.debug('d')
+      logger.info('i')
+      logger.warn('w')
+      logger.error('e')
+
+      expect(lines).toHaveLength(4)
+      expect(lines.every((line) => line.endsWith('\n'))).toBe(true)
+    })
+
+    it('respects the configured log level', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.WARN)
+
+      logger.debug('d')
+      logger.info('i')
+      logger.warn('w')
+      logger.error('e')
+
+      expect(lines).toHaveLength(2)
+    })
+
+    it('prefixes lines with an ISO timestamp when enabled (legacy boolean)', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.INFO, true)
+
+      logger.info('hello')
+
+      expect(lines[0]).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.+: hello\n$/)
+    })
+
+    it('accepts the options-bag form for the timestamp flag', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.INFO, {shouldIncludeTimestamp: true})
+
+      logger.info('hello')
+
+      expect(lines[0]).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.+: hello\n$/)
+    })
+  })
+
+  describe('JSON mode', () => {
+    it('emits a single-line JSON object per call with the correct level', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.DEBUG, {jsonOutput: true})
+
+      logger.debug('d')
+      logger.info('i')
+      logger.warn('w')
+      logger.error('e')
+
+      expect(lines).toHaveLength(4)
+
+      const parsed = lines.map((line) => {
+        expect(line.endsWith('\n')).toBe(true)
+
+        return JSON.parse(line.trim()) as Record<string, string>
+      })
+
+      expect(parsed.map((entry) => entry.level)).toEqual(['debug', 'info', 'warn', 'error'])
+      expect(parsed.map((entry) => entry.message)).toEqual(['d', 'i', 'w', 'e'])
+    })
+
+    it('does not apply ANSI colour codes to JSON output', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.ERROR, {jsonOutput: true})
+
+      logger.error('boom')
+
+      const entry = JSON.parse(lines[0].trim()) as Record<string, string>
+      expect(entry.message).toBe('boom')
+      // eslint-disable-next-line no-control-regex
+      expect(lines[0]).not.toMatch(/\[/)
+    })
+
+    it('includes an ISO timestamp field when timestamps are enabled', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.INFO, {jsonOutput: true, shouldIncludeTimestamp: true})
+
+      logger.info('hello')
+
+      const entry = JSON.parse(lines[0].trim()) as Record<string, string>
+      expect(entry.message).toBe('hello')
+      expect(entry.level).toBe('info')
+      expect(entry.timestamp).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)
+    })
+
+    it('omits the timestamp field when timestamps are disabled', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.INFO, {jsonOutput: true})
+
+      logger.info('hello')
+
+      const entry = JSON.parse(lines[0].trim()) as Record<string, string>
+      expect(entry.timestamp).toBeUndefined()
+    })
+
+    it('toggles back to text via setJsonOutput(false)', () => {
+      const {lines, write} = collect()
+      const logger = new Logger(write, LogLevel.INFO, {jsonOutput: true})
+
+      logger.info('json')
+      logger.setJsonOutput(false)
+      logger.info('plain')
+
+      expect(() => JSON.parse(lines[0].trim())).not.toThrow()
+      expect(() => JSON.parse(lines[1].trim())).toThrow()
+    })
+  })
+})
diff --git a/packages/base/src/helpers/logger.ts b/packages/base/src/helpers/logger.ts
@@ -7,18 +7,43 @@ export enum LogLevel {
   ERROR,
 }
 
+const LEVEL_NAMES: Record<LogLevel, string> = {
+  [LogLevel.DEBUG]: 'debug',
+  [LogLevel.INFO]: 'info',
+  [LogLevel.WARN]: 'warn',
+  [LogLevel.ERROR]: 'error',
+}
+
+export interface LoggerOptions {
+  shouldIncludeTimestamp?: boolean
+  /**
+   * When `true`, every log call emits a single-line JSON object instead of
+   * ANSI-coloured text. Useful when Datadog itself (or any other log
+   * pipeline) ingests CLI output: each line parses cleanly and `level` is
+   * preserved instead of every `error` showing up as `info`.
+   */
+  jsonOutput?: boolean
+}
+
 export class Logger {
   private loglevel: LogLevel
-  private writeMessage: (s: string) => void
+  private rawWriteMessage: (s: string) => void
   private shouldIncludeTimestamp: boolean
+  private jsonOutput: boolean
 
-  constructor(writeMessage: (s: string) => void, loglevel: LogLevel, shouldIncludeTimestamp?: boolean) {
-    this.shouldIncludeTimestamp = shouldIncludeTimestamp ?? false
-    this.writeMessage = (s: string) => {
-      const message = this.shouldIncludeTimestamp ? `${new Date().toISOString()}: ${s}` : s
+  constructor(
+    writeMessage: (s: string) => void,
+    loglevel: LogLevel,
+    shouldIncludeTimestampOrOptions?: boolean | LoggerOptions
+  ) {
+    const options: LoggerOptions =
+      typeof shouldIncludeTimestampOrOptions === 'boolean'
+        ? {shouldIncludeTimestamp: shouldIncludeTimestampOrOptions}
+        : (shouldIncludeTimestampOrOptions ?? {})
 
-      return writeMessage(message)
-    }
+    this.rawWriteMessage = writeMessage
+    this.shouldIncludeTimestamp = options.shouldIncludeTimestamp ?? false
+    this.jsonOutput = options.jsonOutput ?? false
     this.loglevel = loglevel
   }
 
@@ -30,27 +55,50 @@ export class Logger {
     this.shouldIncludeTimestamp = newShouldIncludeTimestamp
   }
 
+  public setJsonOutput(newJsonOutput: boolean) {
+    this.jsonOutput = newJsonOutput
+  }
+
   public error(s: string) {
     if (this.loglevel <= LogLevel.ERROR) {
-      this.writeMessage(chalk.red(s) + '\n')
+      this.emit(LogLevel.ERROR, s, chalk.red)
     }
   }
 
   public warn(s: string) {
     if (this.loglevel <= LogLevel.WARN) {
-      this.writeMessage(chalk.yellow(s) + '\n')
+      this.emit(LogLevel.WARN, s, chalk.yellow)
     }
   }
 
   public info(s: string) {
     if (this.loglevel <= LogLevel.INFO) {
-      this.writeMessage(s + '\n')
+      this.emit(LogLevel.INFO, s)
     }
   }
 
   public debug(s: string) {
     if (this.loglevel <= LogLevel.DEBUG) {
-      this.writeMessage(s + '\n')
+      this.emit(LogLevel.DEBUG, s)
+    }
+  }
+
+  private emit(level: LogLevel, message: string, colorize?: (s: string) => string) {
+    if (this.jsonOutput) {
+      const payload: Record<string, string> = {
+        level: LEVEL_NAMES[level],
+        message,
+      }
+      if (this.shouldIncludeTimestamp) {
+        payload.timestamp = new Date().toISOString()
+      }
+      this.rawWriteMessage(JSON.stringify(payload) + '\n')
+
+      return
     }
+
+    const prefix = this.shouldIncludeTimestamp ? `${new Date().toISOString()}: ` : ''
+    const body = colorize ? colorize(message) : message
+    this.rawWriteMessage(prefix + body + '\n')
   }
 }
