b2c-logging

name

b2c-logging

description

Implement server-side logging with dw.system.Logger, custom log categories, and named log files. Use this skill whenever the user needs to add debug or error logging to Commerce scripts, write to a dedicated log file, configure log categories and levels, or use nested diagnostic context for tracing. Also use when setting up logging in controllers, hooks, or job scripts -- even if they just say 'add logging to my script' or 'write to a custom log file'.

Logging Skill

This skill guides you through implementing logging in B2C Commerce using the Logger and Log classes.

Overview

B2C Commerce provides a logging framework with:

Feature	Description
Log Levels	debug, info, warn, error, fatal
Categories	Organize logs by functional area
Custom Files	Write to dedicated log files
NDC	Nested Diagnostic Context for tracing
BM Configuration	Enable/disable levels per category

Log Levels

Level	Method	Description	Default State
debug	debug()	Detailed debugging information	Disabled (never on production)
info	info()	General information	Disabled by default
warn	warn()	Warning conditions	Always enabled
error	error()	Error conditions	Always enabled
fatal	fatal()	Critical failures	Always enabled, can send email

Basic Logging

Using Logger (Static Methods)

The Logger class provides static methods for quick logging:

var Logger = require('dw/system/Logger');

// Simple messages
Logger.debug('Debug message');
Logger.info('Info message');
Logger.warn('Warning message');
Logger.error('Error message');

// Messages with parameters (Java MessageFormat syntax)
Logger.info('Processing order {0} for customer {1}', orderNo, customerEmail);
Logger.error('Failed to process {0}: {1}', productId, errorMessage);

Using Log (Instance Methods)

The Log class provides instance-based logging with categories:

var Logger = require('dw/system/Logger');

// Get logger for a category
var log = Logger.getLogger('checkout');

log.debug('Cart contents: {0}', JSON.stringify(cart));
log.info('Checkout started for basket {0}', basketId);
log.warn('Inventory low for product {0}', productId);
log.error('Payment failed: {0}', errorMessage);
log.fatal('Critical checkout failure: {0}', errorMessage);

Categories

Categories help organize and filter log messages:

var Logger = require('dw/system/Logger');

// Different categories for different areas
var checkoutLog = Logger.getLogger('checkout');
var paymentLog = Logger.getLogger('payment');
var inventoryLog = Logger.getLogger('inventory');
var integrationLog = Logger.getLogger('integration');

// Use appropriate logger
checkoutLog.info('Order {0} submitted', orderNo);
paymentLog.info('Payment authorized: {0}', transactionId);
inventoryLog.warn('Stock level below threshold for {0}', productId);
integrationLog.error('API call failed: {0}', serviceName);

Categories are configured in Business Manager under Administration > Operations > Custom Log Settings.

Custom Named Log Files

Write to dedicated log files instead of the standard custom log files:

var Logger = require('dw/system/Logger');

// Get logger with custom file prefix
var orderExportLog = Logger.getLogger('orderexport', 'export');
var feedLog = Logger.getLogger('productfeed', 'feed');

// Messages go to custom-orderexport-*.log
orderExportLog.info('Exporting order {0}', orderNo);

// Messages go to custom-productfeed-*.log
feedLog.info('Processing product {0}', productId);

File Name Rules

The fileNamePrefix parameter must follow these rules:

Rule	Requirement
Length	3-25 characters
Characters	a-z, A-Z, 0-9, -, _
Start/End	Must start and end with alphanumeric
Not allowed	Cannot start or end with - or _

File Naming Pattern

Custom log files follow this pattern:

custom-<prefix>-<hostname>-appserver-<date>.log

Example: custom-orderexport-blade0-1-appserver-20240115.log

Quota

Maximum 200 different log file names per day per appserver.

Checking Log Level Status

Check if a log level is enabled before expensive operations:

var Logger = require('dw/system/Logger');
var log = Logger.getLogger('myCategory');

// Check before expensive string building
if (log.isDebugEnabled()) {
    log.debug('Full cart contents: {0}', JSON.stringify(cart));
}

// Check before expensive calculations
if (log.isInfoEnabled()) {
    var stats = calculateDetailedStats(); // expensive
    log.info('Statistics: {0}', JSON.stringify(stats));
}

// Available checks
log.isDebugEnabled();  // true if debug logging enabled
log.isInfoEnabled();   // true if info logging enabled
log.isWarnEnabled();   // true if warn logging enabled
log.isErrorEnabled();  // true if error logging enabled

Static Level Checks

var Logger = require('dw/system/Logger');

if (Logger.isDebugEnabled()) {
    Logger.debug('Debug message');
}

Message Formatting

Messages support Java MessageFormat syntax:

var Logger = require('dw/system/Logger');
var log = Logger.getLogger('order');

// Positional parameters
log.info('Order {0} has {1} items totaling {2}', orderNo, itemCount, total);

// Same parameter multiple times
log.info('Product {0}: {0} is out of stock', productId);

// Complex objects (use JSON.stringify for objects)
log.debug('Request: {0}', JSON.stringify(requestData));

Nested Diagnostic Context (NDC)

NDC helps trace related log messages across a request:

var Logger = require('dw/system/Logger');
var Log = require('dw/system/Log');

var log = Logger.getLogger('checkout');
var ndc = Log.getNDC();

function processOrder(orderId) {
    // Push context onto the stack
    ndc.push('Order:' + orderId);

    try {
        log.info('Starting order processing');
        processPayment();
        processShipping();
        log.info('Order processing complete');
    } finally {
        // Always pop context when leaving scope
        ndc.pop();
    }
}

function processPayment() {
    ndc.push('Payment');
    try {
        log.info('Processing payment'); // NDC shows: Order:123 Payment
    } finally {
        ndc.pop();
    }
}

NDC Methods

Method	Description
push(message)	Add context to the stack
pop()	Remove and return top context
peek()	View top context without removing
remove()	Clear entire context

Best Practices

1. Use Categories

// Good: Organized by functional area
var log = Logger.getLogger('payment.processor');
var log = Logger.getLogger('inventory.sync');
var log = Logger.getLogger('order.export');

// Avoid: No category
Logger.info('Something happened');

2. Check Level Before Expensive Operations

// Good: Check before building expensive string
if (log.isDebugEnabled()) {
    log.debug('Full response: {0}', JSON.stringify(largeObject));
}

// Avoid: Always building expensive strings
log.debug('Full response: {0}', JSON.stringify(largeObject));

3. Include Context in Messages

// Good: Includes relevant context
log.error('Payment failed for order {0}, customer {1}: {2}',
    orderNo, customerId, errorMessage);

// Avoid: Missing context
log.error('Payment failed');

4. Use Appropriate Levels

// debug: Detailed technical information
log.debug('SQL query: {0}', query);
log.debug('API request body: {0}', JSON.stringify(body));

// info: Notable events
log.info('Order {0} placed successfully', orderNo);
log.info('Customer {0} logged in', customerId);

// warn: Potential issues
log.warn('Inventory low for product {0}: {1} remaining', productId, qty);
log.warn('Slow API response: {0}ms', responseTime);

// error: Failures that need attention
log.error('Payment declined for order {0}: {1}', orderNo, reason);
log.error('Failed to connect to service {0}: {1}', serviceName, error);

// fatal: Critical system failures
log.fatal('Database connection lost');
log.fatal('Critical configuration missing: {0}', configKey);

5. Use Custom Log Files for Integration

// Dedicated files for each integration
var erpLog = Logger.getLogger('erp-sync', 'erp');
var omsLog = Logger.getLogger('oms-export', 'oms');
var crmLog = Logger.getLogger('crm-sync', 'crm');

6. Don't Log Sensitive Data

// Good: Mask sensitive data
log.info('Payment processed for card ending in {0}', cardNumber.slice(-4));

// Avoid: Logging sensitive data
log.info('Payment processed for card {0}', cardNumber);

Business Manager Configuration

Configure custom logging in Administration > Operations > Custom Log Settings:

Setting	Description
Log to File	Enable file logging for each level
Receive Email	Email addresses for fatal notifications
Root Category	Default settings for all categories
Custom Categories	Override settings per category

Configuring Categories

1. Go to Custom Log Settings
2. Click Add Category
3. Enter category name (e.g., checkout, payment)
4. Set log levels to enable

Log Output Format

Log entries follow this format:

[timestamp] [level] [category] message

Example:

[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] Order ORD123 placed successfully

Detailed Reference

• Log Files - Log file types, locations, and retention

Script API Classes

Class	Description
dw.system.Logger	Static logging methods and logger factory
dw.system.Log	Logger instance with category support
dw.system.LogNDC	Nested Diagnostic Context for tracing