feat: allow creating scoped loggers (#3214)

Adds `newScope` function to loggers that creates a logger under the current context.

This is ultimately to allow unambiguous cascading log prefixes of:

`libp2p` -> `transport` -> `connection` -> `muxer` -> `stream`

E.g. `libp2p:tcp:connection:outbound:1:yamux:stream:inbound:1`

Author: achingbrain

packages/interface/src/index.ts

@@ -127,10 +127,46 @@ export interface IdentifyResult {
  * Logger component for libp2p
  */
 export interface Logger {
+  /**
+   * Log a message
+   */
   (formatter: any, ...args: any[]): void
+
+  /**
+   * Log an error message
+   */
   error(formatter: any, ...args: any[]): void
+
+  /**
+   * Log a trace message
+   */
   trace(formatter: any, ...args: any[]): void
+
+  /**
+   * `true` if this logger is enabled
+   */
   enabled: boolean
+
+  /**
+   * Create a logger scoped below this one
+   *
+   * @example
+   *
+   * ```ts
+   * import { defaultLogger } from '@libp2p/logger'
+   *
+   * const log = defaultLogger().forComponent('foo')
+   *
+   * log('hello')
+   * // foo hello
+   *
+   * const subLog = log.newScope('bar')
+   *
+   * subLog('hello')
+   * // foo:bar hello
+   * ```
+   */
+  newScope(name: string): Logger
 }
 
 /**

packages/logger/src/index.ts

@@ -37,7 +37,7 @@ import { base58btc } from 'multiformats/bases/base58'
 import { base64 } from 'multiformats/bases/base64'
 import debug from 'weald'
 import { truncatePeerId } from './utils.js'
-import type { PeerId } from '@libp2p/interface'
+import type { PeerId, Logger, ComponentLogger } from '@libp2p/interface'
 import type { Multiaddr } from '@multiformats/multiaddr'
 import type { Key } from 'interface-datastore'
 import type { CID } from 'multiformats/cid'
@@ -82,16 +82,7 @@ debug.formatters.e = (v?: Error): string => {
   return v == null ? 'undefined' : notEmpty(v.stack) ?? notEmpty(v.message) ?? v.toString()
 }
 
-export interface Logger {
-  (formatter: any, ...args: any[]): void
-  error(formatter: any, ...args: any[]): void
-  trace(formatter: any, ...args: any[]): void
-  enabled: boolean
-}
-
-export interface ComponentLogger {
-  forComponent(name: string): Logger
-}
+export type { Logger, ComponentLogger }
 
 function createDisabledLogger (namespace: string): debug.Debugger {
   const logger = (): void => {}
@@ -205,7 +196,8 @@ export function logger (name: string): Logger {
 
   return Object.assign(debug(name), {
     error: debug(`${name}:error`),
-    trace
+    trace,
+    newScope: (scope: string) => logger(`${name}:${scope}`)
   })
 }
 

packages/logger/test/index.spec.ts

@@ -79,6 +79,20 @@ describe('logger', () => {
     expect(log).to.have.nested.property('trace.enabled').that.is.true()
   })
 
+  it('creates a sub logger', () => {
+    debug.enable('enabled-with-trace-logger*,*:trace')
+
+    const log = logger('enabled-with-trace-logger')
+    const subLog = log.newScope('sub-component')
+
+    expect(subLog).to.be.a('function')
+    expect(subLog).to.have.property('enabled').that.is.true()
+    expect(subLog).to.have.property('error').that.is.a('function')
+    expect(subLog).to.have.nested.property('error.enabled').that.is.true()
+    expect(subLog).to.have.property('trace').that.is.a('function')
+    expect(subLog).to.have.nested.property('trace.enabled').that.is.true()
+  })
+
   it('has all formatters', () => {
     debug.enable('enabled-with-formatters')