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---appserver-.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
Go to
Custom Log Settings
Click
Add Category
Enter category name (e.g.,
checkout
,
payment
)
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