logging patterns

Author: clavery

docs/cli/index.md

@@ -30,6 +30,10 @@ These flags are available on all commands that interact with B2C instances:
 - [Sandbox Commands](./sandbox) - Create and manage sandboxes
 - [MRT Commands](./mrt) - Manage Managed Runtime environments
 
+## Configuration
+
+- [Logging](./logging) - Log levels, output formats, and environment variables
+
 ## Getting Help
 
 Get help for any command:

docs/cli/logging.md

@@ -0,0 +1,123 @@
+# Logging
+
+The CLI uses [pino](https://github.com/pinojs/pino) for structured logging with pretty-printed output by default.
+
+## Output Modes
+
+### Pretty Print (Default)
+
+Human-readable output with colors, suitable for interactive terminal use:
+
+```
+[18:31:58] INFO: Deploying cartridges...
+[18:31:59] INFO: Upload complete
+```
+
+### JSON Lines (`--json`)
+
+Machine-readable output for scripting, CI/CD pipelines, and log aggregation:
+
+```bash
+b2c code deploy --json
+```
+
+```json
+{"level":"info","time":1764113529411,"command":"code deploy","msg":"Deploying cartridges..."}
+{"level":"info","time":1764113529412,"command":"code deploy","msg":"Upload complete"}
+```
+
+## Log Levels
+
+Control verbosity with `--log-level` or `-D` for debug:
+
+| Level | Description |
+|-------|-------------|
+| `trace` | Maximum verbosity |
+| `debug` | Detailed operational info |
+| `info` | Normal messages (default) |
+| `warn` | Warnings |
+| `error` | Errors only |
+| `silent` | No output |
+
+```bash
+b2c code deploy --log-level debug
+b2c code deploy -D  # shorthand for --log-level debug
+```
+
+In debug/trace mode, context objects are displayed:
+
+```
+[18:31:58] INFO: Upload complete
+    command: "code deploy"
+    file: "cartridge.zip"
+    bytes: 45678
+    duration: 1234
+```
+
+## Flags
+
+| Flag | Environment Variable | Description |
+|------|---------------------|-------------|
+| `--log-level` | `SFCC_LOG_LEVEL` | Set log verbosity |
+| `-D, --debug` | `SFCC_DEBUG` | Enable debug logging |
+| `--json` | | Output JSON lines |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SFCC_LOG_LEVEL` | Log level (trace, debug, info, warn, error, silent) |
+| `SFCC_DEBUG` | Enable debug logging |
+| `SFCC_LOG_TO_STDOUT` | Send logs to stdout instead of stderr |
+| `SFCC_LOG_COLORIZE` | Force colors on/off |
+| `SFCC_REDACT_SECRETS` | Set to `false` to disable secret redaction |
+| `NO_COLOR` | Industry standard to disable colors |
+
+## Output Streams
+
+By default, logs go to **stderr** so that command output (data, IDs, etc.) can be piped cleanly:
+
+```bash
+# Logs go to stderr, JSON output goes to stdout
+b2c sites list --json 2>/dev/null | jq '.sites[0].id'
+```
+
+To send logs to stdout instead:
+
+```bash
+SFCC_LOG_TO_STDOUT=1 b2c code deploy
+```
+
+## Secret Redaction
+
+Sensitive fields are automatically redacted from log output:
+
+- `password`, `secret`, `token`
+- `client_secret`, `access_token`, `refresh_token`
+- `api_key`, `authorization`
+
+```
+[18:31:58] INFO: Authenticating
+    client_id: "my-client"
+    client_secret: "[REDACTED]"
+```
+
+To disable redaction (for debugging):
+
+```bash
+SFCC_REDACT_SECRETS=false b2c code deploy --debug
+```
+
+## CI/CD Usage
+
+For CI/CD pipelines, use JSON output and disable colors:
+
+```bash
+NO_COLOR=1 b2c code deploy --json 2>&1 | tee deploy.log
+```
+
+Or explicitly set the log level:
+
+```bash
+SFCC_LOG_LEVEL=info b2c code deploy --json
+```

packages/b2c-cli/src/commands/_test/index.ts

@@ -0,0 +1,45 @@
+import {BaseCommand} from '@salesforce/b2c-tooling/cli';
+
+export default class Test extends BaseCommand<typeof Test> {
+  static description = 'Test logging output';
+  static hidden = true;
+
+  async run(): Promise<void> {
+    // Test this.log() which now uses pino
+    this.log('Using this.log() - goes through pino');
+    this.warn('Using this.warn() - goes through pino');
+
+    // Test logger directly at different levels
+    this.logger.trace('Trace level message');
+    this.logger.debug('Debug level message');
+    this.logger.info('Info level message');
+    this.logger.error('Error level message');
+
+    // Context (visible in debug mode)
+    this.logger.info({operation: 'test', duration: 123}, 'Message with context');
+
+    this.logger.debug(
+      {
+        file: 'cartridge.zip',
+        bytes: 45_678,
+        instance: 'dev01.sandbox.us01.dx.commercecloud.salesforce.com',
+      },
+      'Debug with multiple context fields',
+    );
+
+    // Test redaction
+    this.logger.info(
+      {
+        username: 'testuser',
+        password: 'secret123',
+        client_secret: 'abc123xyz', // eslint-disable-line camelcase
+        token: 'Bearer eyJhbGciOiJIUzI1NiJ9.test',
+      },
+      'This should have redacted fields',
+    );
+
+    // Child logger
+    const childLogger = this.logger.child({operation: 'upload'});
+    childLogger.info('Message from child logger');
+  }
+}

packages/b2c-cli/src/commands/hello/index.ts

@@ -148,6 +148,7 @@
   },
   "dependencies": {
     "i18next": "^25.6.3",
-    "pino": "^10.1.0"
+    "pino": "^10.1.0",
+    "pino-pretty": "^13.1.2"
   }
 }

packages/b2c-cli/src/commands/hello/world.ts

@@ -10,6 +10,12 @@ const LOG_LEVELS = ['trace', 'debug', 'info', 'warn', 'error', 'silent'] as cons
 
 /**
  * Base command class for B2C CLI tools.
+ *
+ * Environment variables for logging:
+ * - SFCC_LOG_TO_STDOUT: Send logs to stdout instead of stderr
+ * - SFCC_LOG_COLORIZE: Force colors on/off (default: auto-detect TTY)
+ * - SFCC_REDACT_SECRETS: Set to 'false' to disable secret redaction
+ * - NO_COLOR: Industry standard to disable colors
  */
 export abstract class BaseCommand<T extends typeof Command> extends Command {
   static baseFlags = {
@@ -26,6 +32,11 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
       default: false,
       helpGroup: 'LOGGING',
     }),
+    json: Flags.boolean({
+      description: 'Output logs as JSON lines',
+      default: false,
+      helpGroup: 'LOGGING',
+    }),
     lang: Flags.string({
       char: 'L',
       description: 'Language for messages (e.g., en, de). Also respects LANGUAGE env var.',
@@ -70,6 +81,26 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
     this.resolvedConfig = this.loadConfiguration();
   }
 
+  /**
+   * Determine colorize setting based on env vars and TTY.
+   * Priority: NO_COLOR > SFCC_LOG_COLORIZE > TTY detection
+   */
+  private shouldColorize(): boolean {
+    // NO_COLOR is the industry standard
+    if (process.env.NO_COLOR !== undefined) {
+      return false;
+    }
+
+    // Explicit override
+    const colorizeEnv = process.env.SFCC_LOG_COLORIZE;
+    if (colorizeEnv !== undefined) {
+      return colorizeEnv !== 'false' && colorizeEnv !== '0';
+    }
+
+    // Default: colorize if stderr is a TTY
+    return process.stderr.isTTY ?? false;
+  }
+
   protected configureLogging(): void {
     let level: LogLevel = 'info';
 
@@ -79,15 +110,42 @@ export abstract class BaseCommand<T extends typeof Command> extends Command {
       level = 'debug';
     }
 
+    // Default to stderr (fd 2), allow override to stdout (fd 1)
+    const fd = process.env.SFCC_LOG_TO_STDOUT ? 1 : 2;
+
+    // Redaction: default true, can be disabled
+    const redact = process.env.SFCC_REDACT_SECRETS !== 'false';
+
     configureLogger({
       level,
-      destination: process.stderr,
+      fd,
       baseContext: {command: this.id},
+      json: this.flags.json,
+      colorize: this.shouldColorize(),
+      redact,
     });
 
     this.logger = getLogger();
   }
 
+  /**
+   * Override oclif's log() to use pino.
+   */
+  log(message?: string, ...args: unknown[]): void {
+    if (message !== undefined) {
+      this.logger.info(args.length > 0 ? `${message} ${args.join(' ')}` : message);
+    }
+  }
+
+  /**
+   * Override oclif's warn() to use pino.
+   */
+  warn(input: string | Error): string | Error {
+    const message = input instanceof Error ? input.message : input;
+    this.logger.warn(message);
+    return input;
+  }
+
   protected loadConfiguration(): ResolvedConfig {
     const options: LoadConfigOptions = {
       instance: this.flags.instance,