feat: customizable logger

[mdonnalley]

Customizable Logger

In the current major version, we exclusively use debug for debug logs. This PR exports a Logger interface that will allow people to provide a custom logger for @oclif/core to use. This will be useful if you want all the @oclif/core debug logs to go through your own logger.

The default logger will continue to use debug under the hood. So if you choose to use the default, you can continue to use the DEBUG environment variable to access the debug logs in the console. The only breaking change will be that the namespace for all the logs with be prefixed with a root namespace, oclif.

So if you're used to using DEBUG=config:* my-cli do stuff, you'll need to start doing this instead: DEBUG=oclif:config:* my-cli do stuff

Interface

export type Logger = {
  debug: (formatter: unknown, ...args: unknown[]) => void
  error: (formatter: unknown, ...args: unknown[]) => void
  info: (formatter: unknown, ...args: unknown[]) => void
  trace: (formatter: unknown, ...args: unknown[]) => void
  warn: (formatter: unknown, ...args: unknown[]) => void
  child: (namespace: string) => Logger
  namespace: string
}

Usage

// oclif-logger.ts
import { format } from 'node:util';
import { Interfaces } from '@oclif/core';
import { Logger } from './my-cli-logger';

export const customLogger = (namespace: string): Interfaces.Logger => {
  const myLogger = new Logger(namespace);
  return {
    child: (ns: string, delimiter?: string) => customLogger(`${namespace}${delimiter ?? ':'}${ns}`),
    debug: (formatter: unknown, ...args: unknown[]) => myLogger.debug(format(formatter, ...args)),
    error: (formatter: unknown, ...args: unknown[]) => myLogger.error(format(formatter, ...args)),
    info: (formatter: unknown, ...args: unknown[]) => myLogger.info(format(formatter, ...args)),
    trace: (formatter: unknown, ...args: unknown[]) => myLogger.trace(format(formatter, ...args)),
    warn: (formatter: unknown, ...args: unknown[]) => myLogger.warn(format(formatter, ...args)),
    namespace,
  };
};

export const logger = customLogger('my-cli');

// bin/run.js
#!/usr/bin/env node

async function main() {
  const {execute} = await import('@oclif/core');
  const { logger } = await import('../dist/oclif-logger.js');
  await oclif.execute({
    dir: import.meta.url,
    loadOptions: {
      root: import.meta.dirname,
      logger,
    },
  });
}

await main();

You can also provide the logger to Config, in the event that you instantiate Config before calling run or execute

import {Config, run} from '@oclif/core'
const config = await config.load({
  logger,
});

await run(process.argv.slice(2), config)

@W-15470578@

[shetzel]

I've wanted to do this exact thing for sfdx-core too. Nice!

[shetzel]

Tested with the mdonnalley/core-v4 branch of @salesforce/cli, running bin/run.js config list --dev-debug

✅ Output looks like:

[10:57:08.758] TRACE (sf:find-root:root-plugin): Created 'sf:find-root:root-plugin' child logger instance
[10:57:08.758] DEBUG (sf:find-root:root-plugin): Finding root plugin using /Users/shetzel/dev/salesforcecli/cli/dist
[10:57:08.758] DEBUG (sf:find-root:root-plugin): Finding root starting at /Users/shetzel/dev/salesforcecli/cli/dist