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 ごとに、1 日あたり最大 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	fatal 通知を受け取るメールアドレス
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

詳細リファレンス

• ログファイル - ログファイルの種類、場所、保持期間

スクリプト API クラス

クラス	説明
dw.system.Logger	静的なロギングメソッドとロガーファクトリー
dw.system.Log	カテゴリをサポートするロガーインスタンス
dw.system.LogNDC	トレース用のネストされた診断コンテキスト