The Log API provides log output functionality for debugging, error tracking, and application monitoring.

Overview

The puppet.log namespace provides the following features:

• Information log output
• Warning log output
• Error log output

Methods

setFile()

Sets log file save path, supporting custom format strings.

puppet.log.setFile(pathPattern: string): void

Parameters:

• pathPattern (string) - Log file path pattern, supporting date-time formatting

Supported Format Placeholders:

Placeholder	Description	Example
{yyyy}	4-digit year	2026
{yy}	2-digit year	26
{MM}	Month (01-12)	03
{dd}	Day (01-31)	29
{HH}	Hour (00-23)	14
{mm}	Minute (00-59)	30
{ss}	Second (00-59)	45
{fff}	Millisecond (000-999)	123
{%i}	Incrementing sequence number	839472

Example:

// Basic usage: Set fixed log file
puppet.log.setFile('logs/app.log');

// Use date-time formatting
puppet.log.setFile('logs/app-{yyyy-MM-dd}.log');

// Use full date-time
puppet.log.setFile('logs/app-{yyyy-MM-dd HH-mm-ss}.log');

// Use date and sequence number
puppet.log.setFile('logs/app-{yyyy-MM-dd}_{%i}.log');

// Custom format
puppet.log.setFile('Puppet_log-{yy-MM-dd HH:MM:SS - %i}.log');

// Include subdirectory (will be created automatically)
puppet.log.setFile('logs/2026/03/app.log');

Notes:

Security Note

• Writing to Windows system sensitive folders (such as Windows, Program Files) will show a security confirmation dialog
• User can cancel the operation to prevent log writing to system folders
• Non-existent subdirectories will be created automatically

info()

Outputs information level log.

puppet.log.info(message: string): void

Parameters:

• message (string) - Log message

Example:

// Output information log
puppet.log.info('Application started');
puppet.log.info('User logged in: john');
puppet.log.info('Operation completed');

warn()

Outputs warning level log.

puppet.log.warn(message: string): void

Parameters:

• message (string) - Log message

Example:

// Output warning log
puppet.log.warn('Configuration file missing, using default configuration');
puppet.log.warn('Connection timeout, retrying');
puppet.log.warn('High memory usage: 85%');

error()

Outputs error level log.

puppet.log.error(message: string): void

Parameters:

• message (string) - Log message

Example:

// Output error log
puppet.log.error('File read failed: permission denied');
puppet.log.error('Network connection failed');
puppet.log.error('Operation timeout');

Usage Examples

Log File Configuration

// Configure log file when application starts
async function initLogging() {
    // Use date as log file name
    puppet.log.setFile('logs/app-{yyyy-MM-dd}.log');
    
    puppet.log.info('Log system initialized');
    puppet.log.info('Application started');
}

// Use full date-time format
async function initDetailedLogging() {
    puppet.log.setFile('logs/app-{yyyy-MM-dd HH-mm-ss}.log');
    
    puppet.log.info('Detailed log system initialized');
}

// Use date and sequence number to prevent file name conflicts
async function initSequencedLogging() {
    puppet.log.setFile('logs/app-{yyyy-MM-dd}_{%i}.log');
    
    puppet.log.info('Sequenced log system initialized');
}

// Archive logs by month
async function initMonthlyLogging() {
    puppet.log.setFile('logs/{yyyy}/{MM}/app-{dd}.log');
    
    puppet.log.info('Monthly archived log system initialized');
}

Basic Logging

// Application start
puppet.log.info('=== Application Started ===');

// Load configuration
try {
    const config = await loadConfig();
    puppet.log.info('Configuration loaded successfully');
} catch (error) {
    puppet.log.error('Failed to load configuration: ' + error.message);
}

// User operation
puppet.log.info('User clicked save button');

Structured Logging

// Structured log object
function logEvent(level, event, data) {
    const timestamp = new Date().toISOString();
    const logEntry = {
        timestamp,
        level,
        event,
        data
    };
    
    const message = JSON.stringify(logEntry);
    
    switch (level) {
        case 'info':
            puppet.log.info(message);
            break;
        case 'warn':
            puppet.log.warn(message);
            break;
        case 'error':
            puppet.log.error(message);
            break;
    }
}

// Use structured logging
logEvent('info', 'user_login', { username: 'john' });
logEvent('warn', 'slow_query', { duration: 5000 });
logEvent('error', 'api_failure', { code: 500, message: 'Internal Server Error' });

Error Tracking

class ErrorTracker {
    static track(error, context = {}) {
        const errorInfo = {
            message: error.message,
            stack: error.stack,
            timestamp: new Date().toISOString(),
            context
        };
        
        // Output to Puppet log
        puppet.log.error(JSON.stringify(errorInfo));
        
        // Show user-friendly message
        showError('Operation failed, please try again');
        
        // Optional: Report to error tracking service
        this.report(errorInfo);
    }
    
    static report(errorInfo) {
        // Send to error tracking service
        // fetch('https://error-tracking.com/api', {
        //     method: 'POST',
        //     body: JSON.stringify(errorInfo)
        // });
    }
}

// Use error tracking
try {
    await riskyOperation();
} catch (error) {
    ErrorTracker.track(error, { action: 'loadData' });
}

Performance Monitoring

class PerformanceMonitor {
    constructor() {
        this.metrics = new Map();
    }
    
    start(label) {
        this.metrics.set(label, performance.now());
    }
    
    end(label) {
        const startTime = this.metrics.get(label);
        if (!startTime) return;
        
        const duration = performance.now() - startTime;
        
        if (duration > 1000) {
            puppet.log.warn(`[Performance] ${label}: ${duration.toFixed(2)}ms`);
        } else {
            puppet.log.info(`[Performance] ${label}: ${duration.toFixed(2)}ms`);
        }
        
        this.metrics.delete(label);
        return duration;
    }
    
    measureAsync(label, asyncFn) {
        this.start(label);
        const result = await asyncFn();
        this.end(label);
        return result;
    }
}

// Use performance monitoring
const monitor = new PerformanceMonitor();

await monitor.measureAsync('loadData', async () => {
    return await loadData();
});

Best Practices

1. Log File Management

Manage log files reasonably to avoid log files becoming too large:

// Split logs by date
puppet.log.setFile('logs/app-{yyyy-MM-dd}.log');

// Archive by month
puppet.log.setFile('logs/{yyyy}/{MM}/app.log');

// Use sequence number to prevent file name conflicts
puppet.log.setFile('logs/app-{yyyy-MM-dd}_{%i}.log');

// Periodically clean old logs (recommended to implement externally)
async function cleanupOldLogs(daysToKeep = 30) {
    const cutoffDate = new Date();
    cutoffDate.setDate(cutoffDate.getDate() - daysToKeep);
    
    // Traverse log directory and delete old logs
    // This needs to be implemented at the application layer
}

2. Log Level Usage

Choose appropriate log level based on message severity:

// INFO: Normal operations
puppet.log.info('Application started');
puppet.log.info('User logged in');
puppet.log.info('Data saved successfully');

// WARN: Potential issues
puppet.log.warn('Configuration missing, using default value');
puppet.log.warn('Long response time');
puppet.log.warn('Cache miss');

// ERROR: Errors and exceptions
puppet.log.error('File read failed');
puppet.log.error('Database connection failed');
puppet.log.error('API request failed');

3. Structured Messages

Use structured log messages for easy parsing:

// Recommended: Structured message
puppet.log.info(JSON.stringify({
    event: 'user_action',
    action: 'click',
    target: 'save_button',
    timestamp: Date.now()
}));

// Not recommended: Non-structured message
puppet.log.info('User clicked save button');

4. Context Information

Include sufficient context information:

// Include context
puppet.log.error(JSON.stringify({
    error: 'File read failed',
    path: '/path/to/file.txt',
    reason: 'Permission denied',
    user: 'john'
}));

// No context
puppet.log.error('File read failed');

5. Avoid Sensitive Information

Do not include sensitive information in logs:

// Not recommended: Contains sensitive information
puppet.log.info('User logged in: john password: secret123');

// Recommended: No sensitive information
puppet.log.info('User logged in: john');

Related Resources

• JavaScript Console API: Browser console API
• Logging Best Practices: Error handling best practices

Common Questions

Q: Where are logs saved?

A: By default, logs are saved in the puppet.log file in the application directory. You can use the puppet.log.setFile() method to customize the log file path and format.

Q: How to clear logs?

A: Logs are continuously appended to the file. If you need to clear logs, you can:

• Delete or clear the log file
• Use a new log file name (through date-time formatting)

Q: Can I customize log format?

A: Yes! Using the puppet.log.setFile() method, you can customize the log file path and format, supporting date-time and sequence number placeholders.

Q: Will logging affect performance?

A: Log operations use thread-safe file writing, which has minimal impact on performance. However, avoid outputting logs frequently in loops.

Q: Why does a confirmation dialog appear when writing to system folders?

A: For security reasons, writing to Windows system sensitive folders (such as Windows, Program Files) will show a security confirmation dialog to prevent accidental operations from affecting system security.

Changelog

4/5/26, 4:22 AM

View All Changelog

• db86e-docs: add TypeScript type definitions documentationon 4/5/26

Edit this page

Contributors: bil-fis

Previous pageFile System

Next pageSystem