Add Logging

Add logging to your plugin with the Logger class from @salesforce/core.

Add Logging to a Command

Let’s show how to add logging to the initial hello world command that sf dev generate plugin generated.

Open src/commands/hello/world.ts and update the import from @salesforce/core to include the Logger class:
1import { Messages, Logger } from "@salesforce/core";

Now create child logger instance. The Logger class creates a root logger with some defaults. Other code, like a command or library, then creates a child logger using the Logger.child() method. To try it out, replace the run method with this code:

1public async run(): Promise<HelloWorldResult> {
2    const log = await Logger.child(this.ctor.name);
3
4    const { flags } = await this.parse(World);
5    const time = new Date().toDateString();
6    const message = `Hello ${flags.name} at ${time}`;
7
8    log.debug(`Time: ${time} | Name: ${flags.name}`);
9
10    this.log(message);
11    return {
12      name: flags.name,
13      time,
14    };
15  }

The example shows how you pass the name of the child logger as the first argument of Logger.child(). In the example, it’s set it to this.ctor.name which points to the name of the command class (World in our case). But it can be anything you want.

Now make the logger print records to the terminal. First set the DEBUG environment variable, either to * to see all log records or sf:_LoggerName_ to filter records by logger.

For now, let’s print logs for only the hello world command:

For bash/zsh:
1export DEBUG='sf:World'
For PowerShell:
1$Env:DEBUG = 'sf:World'

Run the hello world command using bin/dev as usual:

1./bin/dev hello world --name Astro

You see log and command output similar to this:

1sf:World DEBUG Time: Wed Sep 7 2022 | Name: Astro +0ms
2Hello Astro at Wed Sep 7 2022

Remember to unset the DEBUG environment variable after you’re done:

For bash/zsh:
1unset DEBUG
For PowerShell:
1$Env:DEBUG = ''

Logging Levels

The Logger class wraps pino, which already sets log levels. See logger.levels for more information.

Log Storage

Salesforce CLI saves logs to a file in the global .sf folder; you can turn off this behavior by setting the SFDX_DISABLE_LOG_FILE environment variable to true. The CLI starts a new log file every day, formatted like sf-YYYY-MM-DD.log. The CLI cleans them up if they’re more than 7 days old.

Salesforce CLI saves log records to a log file only if the log level method used is the same level or higher than the level set in the logger instance.

Let’s see how this works. By default, the root logger sets the log level to warn. This example shows calls to debug, warn, and error methods, but only the warn and error records are saved to the log file:

1log.debug("test1"); // log level: 20, below 40 so don't save it.
2log.warn("test2"); // log level: 40, same level as the logger instance so record goes to file.
3log.error("test3"); // log level: 50, above `warn` so it's saved to a file too.

The user can set the log level with environment variables (SF_LOG_LEVEL=debug or SF_LOG_LEVEL=trace) so it’s best not to rely on code to manage your child Logger. Rather,let the user control the log level.