@salesforce/b2c-cli 2.3.1 → 2.5.0

package/content/guidance/b2c/b2c-logging/SKILL.md

@@ -0,0 +1,352 @@
+---
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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:
+
+```javascript
+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
+
+```javascript
+var Logger = require('dw/system/Logger');
+
+if (Logger.isDebugEnabled()) {
+    Logger.debug('Debug message');
+}
+```
+
+## Message Formatting
+
+Messages support Java MessageFormat syntax:
+
+```javascript
+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:
+
+```javascript
+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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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
+
+```javascript
+// 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](references/LOG-FILES.md) - 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 |

package/content/guidance/b2c/b2c-logging/references/LOG-FILES.md

@@ -0,0 +1,282 @@
+# Log Files Reference
+
+Complete reference for B2C Commerce log file types, locations, and management.
+
+## Log File Types
+
+### Custom Log Files
+
+Custom log files are generated by script logging:
+
+| Log File | Trigger | Default State |
+|----------|---------|---------------|
+| `customdebug` | `Logger.debug()` or `log.debug()` | Disabled |
+| `custominfo` | `Logger.info()` or `log.info()` | Disabled |
+| `customwarn` | `Logger.warn()` or `log.warn()` | Always enabled |
+| `customerror` | `Logger.error()` or `log.error()` | Always enabled |
+| `customfatal` | `log.fatal()` | Always enabled |
+
+### System Log Files
+
+System log files are generated by the platform:
+
+| Log File | Description |
+|----------|-------------|
+| `error` | System errors in scripts, templates, and platform |
+| `warn` | Lock status, slot warnings, servlet warnings |
+| `info` | System information from scripts and platform |
+| `debug` | Debug information (only when debug flag enabled) |
+| `fatal` | Critical system failures |
+| `api` | API problems and violations |
+| `deprecation` | Usage of deprecated APIs |
+| `jobs` | Job status information |
+| `staging` | Replication process information |
+| `quota` | Quota warnings and limits |
+| `sql` | SQL and replication issues |
+| `syslog` | API processing, staging, import/export info |
+| `sysevent` | Appserver registration, cartridge logs |
+| `analytics` | Analytics activity and errors |
+| `performance` | Internal performance data |
+| `console` | Internal console entries |
+| `migration` | Internal migration data |
+| `dbinit-sql` | SQL used during database initialization |
+
+### Custom Named Log Files
+
+Files created with `Logger.getLogger(prefix, category)`:
+
+```
+custom-<prefix>-<hostname>-appserver-<date>.log
+```
+
+Example: `custom-orderexport-blade0-1-appserver-20240115.log`
+
+## Log File Locations
+
+### WebDAV Access
+
+**Logs Directory:**
+```
+https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Logs
+```
+
+**Security Logs:**
+```
+https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Securitylogs
+```
+
+**Import/Export Logs:**
+```
+https://<instance>.demandware.net/on/demandware.servlet/webdav/Sites/Impex/log
+```
+
+### Business Manager Access
+
+1. **Administration > Site Development > Development Setup**
+2. Scroll to **WebDAV Access** section
+3. Click **Log files** link
+
+## Log Retention
+
+| Environment | Retention | Notes |
+|-------------|-----------|-------|
+| Production | 30 days | Auto-deleted after retention |
+| Staging | 30 days | Auto-deleted after retention |
+| Development | Not defined | Manual cleanup recommended |
+| Sandbox | Not defined | Manual cleanup recommended |
+
+**Security logs** are retained for 90 days.
+
+### Archive Process
+
+- After 3 days, logs move to `log_archive` directory
+- Archived logs are compressed to gzip format
+- Download logs locally for longer retention
+
+## Storage Limits
+
+### Custom Log Size Limits
+
+| Limit | Value |
+|-------|-------|
+| Per log level per day | 10 MB |
+| Per application server | Per log type |
+| Custom named log files | Same 10 MB limit |
+
+When the limit is reached:
+```
++++++++++++ Maximum log file size per day reached, logging suspended. +++++++++++
+```
+
+Logging resumes at 00:00 GMT the next day.
+
+### File Count Limits
+
+- Maximum 100,000 files per folder
+- Excess files deleted starting with oldest
+- Applies per folder, not across subfolders
+
+### Custom Log File Quota
+
+- Maximum 200 different log file prefixes per day
+- Per application server
+- Hard limit (throws exception when exceeded)
+
+## Log Entry Format
+
+### Standard Format
+
+```
+[timestamp GMT] [level] [category] message
+```
+
+Example:
+```
+[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] Order ORD123 submitted
+```
+
+### With NDC
+
+```
+[timestamp GMT] [level] [category] [ndc-context] message
+```
+
+Example:
+```
+[2024-01-15 10:30:45.123 GMT] [INFO] [checkout] [Order:123 Payment] Processing payment
+```
+
+## Redundancy Tracking
+
+Error and Warning messages are tracked for redundancy:
+
+- Messages appearing > 10 times in 3 minutes are suppressed
+- Suppression lasts 3 minutes
+- Suppression message:
+
+```
+The following message was generated more than 10 times within the last 180 seconds.
+It will be suppressed for 180 seconds:
+<original message>
+```
+
+## Quota Log Format
+
+Quota logs show when thresholds or limits are exceeded:
+
+```
+[timestamp] [thread-info] Quota quota.name (enforced, warn threshold, limit):
+warn threshold exceeded N time(s), max actual was X, current location: details
+```
+
+Example:
+```
+[2024-01-15 13:00:22.577 GMT] [RequestHandlerServlet|14320460|Sites-MySite|Product-Show|...]
+Quota api.jsStringLength (enforced, warn 600000, limit 1000000): warn threshold exceeded 1 time(s),
+max actual was 600010, current location: request/site Sites-MySite/top pipeline Product-Show/
+interaction node/template default.CustomDisplay
+```
+
+## Security Log Format
+
+```
+[timestamp GMT][dw-sec] (User: 'username' (realm), IP: x.x.x.x [ACTION] : details)
+```
+
+Example:
+```
+[2024-01-15 02:23:19.139 GMT][dw-sec] (User: 'admin' (Sites), IP: 192.168.1.1 [LOGIN] : logged in.)
+```
+
+Actions logged:
+- LOGIN
+- LOGOUT
+- LOGIN_FAILED
+- PASSWORD_CHANGED
+- Re-login (session timeout)
+
+## Import/Export Logs
+
+Located in `/Impex/log/`:
+
+| Log Type | Description |
+|----------|-------------|
+| Catalog | Catalog import/export logs |
+| Customer | Customer batch processing logs |
+| Inventory | Inventory import logs |
+| Price Book | Price book import/validation logs |
+| Promotion | Promotion validation logs |
+| Metadata | Metadata validation logs |
+| Coupon | Coupon validation logs |
+
+Example path:
+```
+/Impex/log/Batch-Customer-20240115192425062.log
+```
+
+## Accessing Logs Programmatically
+
+### Via WebDAV Client
+
+Configure your WebDAV client with:
+- URL: `https://<instance>/on/demandware.servlet/webdav/Sites/Logs`
+- User: Business Manager username
+- Password: Business Manager password
+
+### Via B2C CLI
+
+```bash
+# Download logs via WebDAV
+b2c webdav pull /Logs --dest ./local-logs
+
+# Download specific log
+b2c webdav pull /Logs/customerror-blade0-1-20240115.log
+```
+
+## Debug Logging on Production
+
+Debug logging is **never enabled on production instances**.
+
+On non-production instances:
+- Debug logs are "in-memory" by default
+- Enables "Show Request Log" feature
+- Does not generate log files unless explicitly enabled
+
+## Best Practices
+
+### 1. Monitor Log File Sizes
+
+Check log sizes regularly to avoid hitting limits:
+- 10 MB per custom log type per day
+- Monitor during high-traffic periods
+
+### 2. Use Custom Named Logs for Integrations
+
+```javascript
+// Separate files for each integration
+var erpLog = Logger.getLogger('erp-sync', 'erp');
+var paymentLog = Logger.getLogger('payment-gateway', 'payment');
+```
+
+### 3. Clean Up Old Logs
+
+- Delete unnecessary logs promptly
+- Don't exceed 100,000 files per folder
+- Download and archive important logs locally
+
+### 4. Configure Categories in Business Manager
+
+1. Go to **Administration > Operations > Custom Log Settings**
+2. Add categories for your code areas
+3. Enable appropriate log levels per category
+4. Set up fatal email notifications
+
+### 5. Use Appropriate Log Levels
+
+| Level | Use For |
+|-------|---------|
+| debug | Development debugging only |
+| info | Notable events, job progress |
+| warn | Recoverable issues, slow operations |
+| error | Failures requiring attention |
+| fatal | Critical failures, email notification |