ElectronEgg

English

简体中文

English

简体中文

Appearance

Introduction ​

Log module. Provides log creation, loading, and retrieval functionality. Creates three log instances based on the pino logging library:

  • logger: Application log (ee.log), records business code output
  • coreLogger: Framework core log (ee-core.log), records framework internal runtime information
  • errorLogger: Error log (ee-error.log), only records error/fatal levels

All log instances are wrapped with Proxy, compatible with multiple calling styles:

  1. pino standard: logger.info({ key: 'value' }, 'message') — first argument is merge object
  2. pino printf: logger.info('count: %d', 42) — contains %s/%d format placeholders
  3. Concatenation mode: logger.info('msg:', value) — multiple arguments auto-concatenated to 'msg: value'

Features:

  • Log file rotation based on pino-roll (daily/hourly)
  • pino-pretty colorized output in development environment
  • Supports field redaction (redact), custom log levels, custom serializers
  • Safe mode: does not throw exceptions when log write fails
  • Configurable timezone for log timestamps (IANA timezone names or UTC)

Import ​

Both CJS and ESM:

javascript
// ESM
import { loadLog, getLoggers, createLog, logger, coreLogger } from 'ee-core/log';
import type { EeLogger } from 'ee-core/log';
// CJS
const { loadLog, getLoggers, createLog, logger, coreLogger } = require('ee-core/log');

From the main entry:

javascript
// ESM
import { loadLog, getLoggers, coreLogger } from 'ee-core';
import type { EeLogger } from 'ee-core';
// CJS
const { loadLog, getLoggers, coreLogger } = require('ee-core');

API ​

EeLogger ​

Description: The framework's unified log interface, shielding pino internal implementation details. All log instances (logger, coreLogger, errorLogger) implement this interface. Supports six log levels and child sub-logger creation.

| Method | Signature | Description |
| trace | (...args: unknown[]) => void | Trace level logging |
| debug | (...args: unknown[]) => void | Debug level logging |
| info | (...args: unknown[]) => void | Info level logging |
| warn | (...args: unknown[]) => void | Warn level logging |
| error | (...args: unknown[]) => void | Error level logging |
| fatal | (...args: unknown[]) => void | Fatal level logging |
| child | (bindings: pino.Bindings) => EeLogger | Create a sub-logger with additional context bindings |

Example:

javascript
// Standard pino style
logger.info({ userId: 123 }, 'User logged in');

// Printf style (supports %s, %d, %i, %f, %o, %O, %c)
logger.info('Count: %d, name: %s', 42, 'test');

// Concatenation style
logger.info('Request completed:', { status: 200, duration: 150 });

// Create a sub-logger with context
const requestLogger = logger.child({ requestId: 'abc-123' });
requestLogger.info('Processing request');

loadLog() ​

Description: Load the log system. Creates log instances using system configuration. Called by boot.ts init() during framework startup flow. This function is part of the framework's startup lifecycle and typically does not need to be called manually.
Parameters: None
Returns: void
Example:

javascript
// Called internally during framework startup
loadLog();

See also: app.ElectronEgg lifecycle, getLoggers

getLoggers() ​

Description: Get the log instance collection (PinoLoggers). If logs have not been loaded yet, automatically triggers loading. Returns the raw pino instances, not the Proxy-wrapped versions.
Parameters: None
Returns: PinoLoggers — Object containing three pino.Logger instances: { logger, coreLogger, errorLogger }
Example:

javascript
const loggers = getLoggers();
// Access raw pino instances
loggers.logger.info('Direct pino call');
loggers.coreLogger.debug('Core debug message');
loggers.errorLogger.error('Error message');

See also: loadLog, logger, coreLogger

createLog(config) ​

Description: Create a custom log instance collection. Merges default configuration and user configuration, creating independent pino instances for each log file. Useful when you need a separate log system with different settings from the default one.
Parameters: | Parameter | Type | Required | Description |
| config | Partial<LoggerConfig> | No | Custom log configuration (overrides system configuration) |
Returns: PinoLoggers — Object containing three pino.Logger instances: { logger, coreLogger, errorLogger }
Example:

javascript
// Create log with custom configuration
const customLoggers = createLog({
  dir: '/custom/log/path',
  level: 'debug',
  appLogName: 'my-app.log',
  prettyPrint: false,
});

customLoggers.logger.info('Custom log message');

See also: LoggerConfig type, loadLog

logger ​

Description: Application log instance (Proxy-wrapped). Records business code output to ee.log (configurable via appLogName). Implements the EeLogger interface with Proxy wrapping for multi-style call compatibility.
Parameters: None (this is a pre-created singleton instance)
Returns: EeLogger — Application log proxy instance
Example:

javascript
// Multiple calling styles
logger.info('Simple message');
logger.info('User id: %d', 123);
logger.info({ action: 'login' }, 'User logged in');
logger.info('Status:', 200, 'Duration:', 150);
logger.error(new Error('Something failed'));
logger.warn('Deprecated API used');

See also: EeLogger, coreLogger, getLoggers

coreLogger ​

Description: Framework core log instance (Proxy-wrapped). Records framework internal runtime information to ee-core.log (configurable via coreLogName). Implements the EeLogger interface. Exported from both ee-core/log and the main ee-core entry.
Parameters: None (this is a pre-created singleton instance)
Returns: EeLogger — Framework core log proxy instance
Example:

javascript
coreLogger.debug('[config] Loading configuration...');
coreLogger.info('[controller] Registered: example');
coreLogger.error('[socket] Connection failed');

See also: EeLogger, logger, getLoggers

errorLogger ​

Description: Error log instance (Proxy-wrapped, error/fatal level only). Only records error level and above to ee-error.log (configurable via errorLogName). The log level is fixed to error, regardless of the configured global level. Implements the EeLogger interface. Note: errorLogger is only available via ee-core/log module import, not from the main ee-core entry.
Parameters: None (this is a pre-created singleton instance)
Returns: EeLogger — Error log proxy instance
Example:

javascript
// Only error and fatal messages are recorded
const { errorLogger } = require('ee-core/log');
errorLogger.error('Critical failure occurred');
errorLogger.fatal('Unrecoverable error');

See also: EeLogger, logger, getLoggers