feat: add system logger

package.json

@@ -9,6 +9,10 @@
     "dist/**/*.d.ts",
     "types/**/*.d.ts"
   ],
+  "exports": {
+    ".": "./dist/main.js",
+    "./internal": "./dist/internal.js"
+  },
   "scripts": {
     "build": "tsc",
     "prepare": "husky install node_modules/@netlify/eslint-config-node/.husky/",

src/internal.ts

@@ -0,0 +1,5 @@
+// this file is exported as @netlify/functions/internal,
+// and only meant for consumption by Netlify Teams.
+// While we try to adhere to semver, this file is not considered part of the public API.
+
+export { systemLogger, LogLevel } from './lib/system_logger.js'

src/lib/system_logger.ts

@@ -0,0 +1,115 @@
+const systemLogTag = '__nfSystemLog'
+
+const serializeError = (error: Error): Record<string, unknown> => {
+  const cause = error?.cause instanceof Error ? serializeError(error.cause) : error.cause
+
+  return {
+    error: error.message,
+    error_cause: cause,
+    error_stack: error.stack,
+  }
+}
+
+// eslint pretends there's a different enum at the same place - it's wrong!
+// eslint-disable-next-line no-shadow
+export enum LogLevel {
+  Debug = 1,
+  Info,
+  Warn,
+  Error,
+}
+
+class SystemLogger {
+  // eslint-disable-next-line no-useless-constructor
+  constructor(
+    private readonly fields: Record<string, unknown> = {},
+    private readonly logLevel = LogLevel.Info,
+    private readonly samplingRate = 1,
+  ) {}
+
+  private doLog(logger: typeof console.log, message: string) {
+    if (this.samplingRate < 1 && Math.random() > this.samplingRate) {
+      return
+    }
+
+    logger(systemLogTag, JSON.stringify({ msg: message, fields: this.fields }))
+  }
+
+  /**
+   * Alias for .info
+   */
+  log(message: string) {
+    this.info(message)
+  }
+
+  info(message: string) {
+    if (this.logLevel > LogLevel.Info) {
+      return
+    }
+
+    this.doLog(console.info, message)
+  }
+
+  debug(message: string) {
+    if (this.logLevel > LogLevel.Debug) {
+      return
+    }
+
+    this.doLog(console.debug, message)
+  }
+
+  warn(message: string) {
+    if (this.logLevel > LogLevel.Warn) {
+      return
+    }
+
+    this.doLog(console.warn, message)
+  }
+
+  error(message: string) {
+    if (this.logLevel > LogLevel.Error) {
+      return
+    }
+
+    this.doLog(console.error, message)
+  }
+
+  withLogLevel(level: LogLevel) {
+    return new SystemLogger(this.fields, level, this.samplingRate)
+  }
+
+  withSamplingRate(rate: number) {
+    return new SystemLogger(this.fields, this.logLevel, rate)
+  }
+
+  withFields(fields: Record<string, unknown>) {
+    return new SystemLogger(
+      {
+        ...this.fields,
+        ...fields,
+      },
+      this.logLevel,
+      this.samplingRate,
+    )
+  }
+
+  withError(error: unknown) {
+    const fields = error instanceof Error ? serializeError(error) : { error }
+
+    return this.withFields(fields)
+  }
+
+  withRequest(req: Request) {
+    // proxy automatically adds the request ID to the logs,
+    // so we don't need to care about it here
+
+    const debug = req.headers.has('x-nf-debug-logging')
+    if (debug) {
+      return this.withLogLevel(LogLevel.Debug)
+    }
+
+    return this
+  }
+}
+
+export const systemLogger = new SystemLogger()

test/unit/system_logger.js

@@ -0,0 +1,75 @@
+const test = require('ava')
+
+const { systemLogger, LogLevel } = require('../../dist/internal')
+
+test('Log Level', (t) => {
+  const originalLog = console.info
+  const originalDebug = console.debug
+
+  const infoLogs = []
+  const debugLogs = []
+  console.info = (...message) => infoLogs.push(message)
+  console.debug = (...message) => debugLogs.push(message)
+
+  systemLogger.debug('hello!')
+  t.is(debugLogs.length, 0)
+
+  systemLogger.withLogLevel(LogLevel.Debug).debug('hello!')
+  t.is(debugLogs.length, 1)
+
+  systemLogger
+    .withRequest(new Request('https://example.com'))
+    .debug('hello!')
+  t.is(debugLogs.length, 1)
+
+  systemLogger
+    .withRequest(new Request('https://example.com', { headers: { 'x-nf-debug-logging': '1' } }))
+    .debug('hello!')
+  t.is(debugLogs.length, 2)
+
+  systemLogger
+    .withLogLevel(LogLevel.Info)
+    .debug('hello!')
+  t.is(debugLogs.length, 2)
+
+  console.info = originalLog
+  console.debug = originalDebug
+})
+
+test('Fields', (t) => {
+  const originalLog = console.info
+  const logs = []
+  console.info = (...message) => logs.push(message)
+  systemLogger.withError(new Error('boom')).withFields({ foo: 'bar' }).log('hello!')
+  t.is(logs.length, 1)
+  t.is(logs[0][0], '__nfSystemLog')
+  const log = JSON.parse(logs[0][1])
+  t.is(log.msg, 'hello!')
+  t.is(log.fields.foo, 'bar')
+  t.is(log.fields.error, 'boom')
+  t.is(log.fields.error_stack.split('\n').length > 2, true)
+
+  console.info = originalLog
+})
+
+test('Sampling', (t) => {
+  const originalLog = console.info
+  const logs = []
+  console.info = (...message) => logs.push(message)
+  let randomValue = 0.5
+  const originalRandom = Math.random
+  Math.random = () => randomValue
+
+  systemLogger.withSamplingRate(0.6).log('hello!')
+  t.is(logs.length, 1)
+
+  systemLogger.withSamplingRate(0.3).log('hello!')
+  t.is(logs.length, 1)
+
+  randomValue = 0.2
+  systemLogger.withSamplingRate(0.3).log('hello!')
+  t.is(logs.length, 2)
+
+  Math.random = originalRandom
+  console.info = originalLog
+})

tsconfig.json

@@ -11,7 +11,7 @@
     // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
 
     /* Language and Environment */
-    "target": "ES2020" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
+    "target": "ES2022" /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */,
     // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
     // "jsx": "preserve",                                /* Specify what JSX code is generated. */
     // "experimentalDecorators": true,                   /* Enable experimental support for TC39 stage 2 draft decorators. */