b2c-logging

日志记录技能

本技能将指导你使用 Logger 和 Log 类在 B2C Commerce 中实现日志记录。

概览

B2C Commerce 提供了一个日志框架，包含：

功能	描述
日志级别	debug、info、warn、error、fatal
类别	按功能区域组织日志
自定义文件	写入专用日志文件
NDC	用于跟踪的嵌套诊断上下文
BM 配置	按类别启用/禁用日志级别

日志级别

级别	方法	描述	默认状态
debug	debug()	详细的调试信息	已禁用（生产环境中永远不会启用）
info	info()	常规信息	默认已禁用
warn	warn()	警告情况	始终启用
error	error()	错误情况	始终启用
fatal	fatal()	严重故障	始终启用，可发送电子邮件

基本日志记录

使用 Logger（静态方法）

Logger 类提供了用于快速记录日志的静态方法：

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);

使用 Log（实例方法）

Log 类提供了基于实例并支持类别的日志记录：

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);

类别

类别有助于组织和筛选日志消息：

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);

可在 Business Manager 的 Administration > Operations > Custom Log Settings 中配置类别。

自定义命名日志文件

将日志写入专用文件，而不是标准自定义日志文件：

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);

文件名规则

fileNamePrefix 参数必须遵循以下规则：

规则	要求
长度	3-25 个字符
字符	a-z、A-Z、0-9、-、_
开头/结尾	必须以字母数字字符开头和结尾
不允许	不能以 - 或 _ 开头或结尾

文件命名模式

自定义日志文件遵循以下模式：

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

示例：custom-orderexport-blade0-1-appserver-20240115.log

配额

每个 appserver 每天最多可使用 200 个不同的日志文件名。

检查日志级别状态

在执行开销较大的操作之前，检查相应日志级别是否已启用：

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

静态级别检查

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

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

消息格式

消息支持 Java MessageFormat 语法：

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));

嵌套诊断上下文（NDC）

NDC 有助于跟踪请求中的相关日志消息：

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 方法

方法	描述
push(message)	向堆栈添加上下文
pop()	移除并返回顶部上下文
peek()	查看顶部上下文但不移除
remove()	清除整个上下文

最佳实践

1. 使用类别

// 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. 在执行开销较大的操作前检查级别

// 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. 在消息中包含上下文

// 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. 使用适当的级别

// 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. 为集成使用自定义日志文件

// 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. 不要记录敏感数据

// 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 配置

在 Administration > Operations > Custom Log Settings 中配置自定义日志记录：

设置	描述
Log to File	为每个级别启用文件日志记录
Receive Email	接收严重故障通知的电子邮件地址
Root Category	所有类别的默认设置
Custom Categories	按类别覆盖设置

配置类别

1. 前往 Custom Log Settings
2. 点击 Add Category
3. 输入类别名称（例如 checkout、payment）
4. 设置要启用的日志级别

日志输出格式

日志条目遵循以下格式：

[timestamp] [level] [category] message

示例：

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

详细参考

• 日志文件 - 日志文件类型、位置和保留期限

Script API 类

类	描述
dw.system.Logger	静态日志记录方法和日志记录器工厂
dw.system.Log	支持类别的日志记录器实例
dw.system.LogNDC	用于跟踪的嵌套诊断上下文