or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-logging.mderror-handling.mdevent-logging.mdindex.mdlogger-management.mdscoping.mdtransports.md
tile.json

event-logging.mddocs/

Event Logging

Automatic logging of Electron application and webContents events with customizable formatting, filtering, and comprehensive event coverage for debugging and monitoring.

Capabilities

Event Logger

Core event logging functionality for monitoring Electron application events.

interface EventLogger {
  /** String template or function which prepares event data for logging */
  format: string | ((input: EventFormatterInput) => unknown[]);
  /** Formatter callbacks for a specific event */
  formatters: Record<EventSource, Record<string, (input: EventFormatterInput) => object | unknown[]>>;
  /** Allow switching specific events on/off easily */
  events: Record<EventSource, Record<string, boolean>>;
  /** Which log level is used for logging. Default warn */
  level: LogLevel;
  /** Which log scope is used for logging. Default '' (none) */
  scope: string;
  
  /**
   * Configure event logger options
   * @param options - Event logger configuration
   */
  setOptions(options: EventLoggerOptions): void;
  
  /**
   * Start logging Electron events
   * @param options - Optional configuration override
   */
  startLogging(options?: EventLoggerOptions): void;
  
  /**
   * Stop logging Electron events
   */
  stopLogging(): void;
}

Usage Examples:

// Main process only
const log = require('electron-log/main');

// Basic event logging
log.eventLogger.startLogging();

// Configure event logging
log.eventLogger.setOptions({
  level: 'info',
  scope: 'electron-events',
  format: '[{eventSource}] {eventName}: {args}',
  events: {
    app: {
      'ready': true,
      'window-all-closed': true,
      'before-quit': true,
      'activate': false // Disable this event
    },
    webContents: {
      'did-finish-load': true,
      'did-fail-load': true,
      'crashed': true,
      'console-message': false // Too verbose
    }
  }
});

// Start with custom configuration
log.eventLogger.startLogging({
  level: 'debug',
  events: {
    app: { 'ready': true },
    webContents: { 'did-finish-load': true }
  }
});

Event Sources

Available event sources for monitoring different aspects of Electron.

type EventSource = 'app' | 'webContents';

interface EventFormatterInput {
  args: unknown[];
  event: object;
  eventName: string;
  eventSource: string;
}

Usage Examples:

const log = require('electron-log/main');

// Monitor app events
log.eventLogger.setOptions({
  events: {
    app: {
      'ready': true,
      'window-all-closed': true,
      'before-quit': true,
      'will-quit': true,
      'quit': true,
      'activate': true,
      'browser-window-created': true,
      'browser-window-focus': true,
      'browser-window-blur': true
    }
  }
});

// Monitor webContents events
log.eventLogger.setOptions({
  events: {
    webContents: {
      'did-finish-load': true,
      'did-fail-load': true,
      'did-start-loading': true,
      'did-stop-loading': true,
      'crashed': true,
      'unresponsive': true,
      'responsive': true,
      'console-message': true,
      'devtools-opened': true,
      'devtools-closed': true
    }
  }
});

Custom Event Formatting

Customize how events are formatted and displayed in logs.

interface EventFormattingOptions {
  /** Global format for all events */
  format?: string | ((input: EventFormatterInput) => unknown[]);
  /** Event-specific formatters */
  formatters?: Record<EventSource, Record<string, (input: EventFormatterInput) => object | unknown[]>>;
}

Usage Examples:

const log = require('electron-log/main');

// Custom global format
log.eventLogger.setOptions({
  format: (input) => {
    return [
      `[${input.eventSource.toUpperCase()}]`,
      `${input.eventName}:`,
      ...input.args
    ];
  }
});

// Event-specific formatters
log.eventLogger.setOptions({
  formatters: {
    app: {
      'ready': ({ eventName, args }) => {
        return [`Application ready in ${process.uptime()}s`];
      },
      'browser-window-created': ({ args }) => {
        const [window] = args;
        return [`New window created: ${window.webContents.id}`];
      }
    },
    webContents: {
      'did-finish-load': ({ args }) => {
        const [event] = args;
        return [`Page loaded: ${event.sender.getURL()}`];
      },
      'console-message': ({ args }) => {
        const [event, level, message, line, sourceId] = args;
        return [`Console ${level}: ${message} (${sourceId}:${line})`];
      },
      'crashed': ({ args }) => {
        const [event, killed] = args;
        return [`WebContents crashed - killed: ${killed}`];
      }
    }
  }
});

Selective Event Monitoring

Enable or disable specific events for focused monitoring.

interface EventSelectionOptions {
  /** Event enable/disable mapping */
  events?: Record<EventSource, Record<string, boolean>>;
}

Usage Examples:

const log = require('electron-log/main');

// Production monitoring - only critical events
log.eventLogger.setOptions({
  level: 'warn',
  events: {
    app: {
      'ready': false,
      'window-all-closed': true,
      'before-quit': true,
      'will-quit': true,
      'quit': true
    },
    webContents: {
      'did-finish-load': false,
      'did-fail-load': true,
      'crashed': true,
      'unresponsive': true,
      'console-message': false
    }
  }
});

// Development monitoring - verbose events
log.eventLogger.setOptions({
  level: 'debug',
  events: {
    app: {
      'ready': true,
      'activate': true,
      'browser-window-created': true,
      'browser-window-focus': true,
      'browser-window-blur': true
    },
    webContents: {
      'did-start-loading': true,
      'did-finish-load': true,
      'did-fail-load': true,
      'console-message': true,
      'devtools-opened': true
    }
  }
});

// Minimal monitoring - errors only
log.eventLogger.setOptions({
  events: {
    app: {
      'ready': false,
      'activate': false,
      'quit': false
    },
    webContents: {
      'did-fail-load': true,
      'crashed': true,
      'unresponsive': true
    }
  }
});

Advanced Event Processing

Complex event processing with conditional logging and data enrichment.

interface AdvancedEventProcessing {
  /** Conditional event processing */
  shouldLog?: (input: EventFormatterInput) => boolean;
  /** Event data enrichment */
  enrichEvent?: (input: EventFormatterInput) => EventFormatterInput;
}

Usage Examples:

const log = require('electron-log/main');

// Advanced event processing with custom logic
log.eventLogger.setOptions({
  format: (input) => {
    // Add timestamp
    const timestamp = new Date().toISOString();
    
    // Conditional processing
    if (input.eventName === 'console-message') {
      const [event, level, message] = input.args;
      
      // Only log console errors and warnings
      if (level !== 1 && level !== 2) return null;
      
      return [
        `[${timestamp}]`,
        `Console ${level === 1 ? 'ERROR' : 'WARN'}:`,
        message,
        `from ${event.sender.getURL()}`
      ];
    }
    
    // Add memory usage for performance events
    if (input.eventName.includes('loading')) {
      const memoryUsage = process.memoryUsage();
      return [
        `[${timestamp}]`,
        `${input.eventSource}:${input.eventName}`,
        `Memory: ${Math.round(memoryUsage.heapUsed / 1024 / 1024)}MB`,
        ...input.args
      ];
    }
    
    // Default formatting
    return [
      `[${timestamp}]`,
      `${input.eventSource}:${input.eventName}`,
      ...input.args
    ];
  }
});

// Event filtering and enrichment
const originalFormat = log.eventLogger.format;
log.eventLogger.format = (input) => {
  // Filter out noisy events during development
  if (process.env.NODE_ENV === 'development') {
    const noisyEvents = ['browser-window-focus', 'browser-window-blur'];
    if (noisyEvents.includes(input.eventName)) {
      return null; // Skip logging
    }
  }
  
  // Enrich with additional context
  const enrichedInput = {
    ...input,
    args: [
      ...input.args,
      { pid: process.pid, uptime: process.uptime() }
    ]
  };
  
  return originalFormat.call(this, enrichedInput);
};

Event Configuration Patterns

Common configuration patterns for different use cases.

interface EventConfigurationPatterns {
  /** Production configuration */
  production: EventLoggerOptions;
  /** Development configuration */
  development: EventLoggerOptions;
  /** Debug configuration */
  debug: EventLoggerOptions;
  /** Minimal configuration */
  minimal: EventLoggerOptions;
}

Usage Examples:

const log = require('electron-log/main');

// Configuration presets
const eventConfigs = {
  production: {
    level: 'warn',
    scope: 'app-events',
    events: {
      app: { 'quit': true, 'before-quit': true },
      webContents: { 'crashed': true, 'unresponsive': true, 'did-fail-load': true }
    }
  },
  
  development: {
    level: 'info',
    scope: 'dev-events',
    events: {
      app: { 'ready': true, 'browser-window-created': true },
      webContents: { 'did-finish-load': true, 'console-message': true }
    }
  },
  
  debug: {
    level: 'debug',
    scope: 'debug-events',
    format: (input) => [`[DEBUG] ${input.eventSource}:${input.eventName}`, ...input.args],
    events: {
      app: Object.fromEntries(
        ['ready', 'activate', 'browser-window-created', 'browser-window-focus'].map(e => [e, true])
      ),
      webContents: Object.fromEntries(
        ['did-start-loading', 'did-finish-load', 'devtools-opened'].map(e => [e, true])
      )
    }
  }
};

// Apply configuration based on environment
const config = process.env.NODE_ENV === 'production' 
  ? eventConfigs.production 
  : eventConfigs.development;

log.eventLogger.setOptions(config);
log.eventLogger.startLogging();

Types

interface EventLoggerOptions {
  /** String template or function which prepares event data for logging */
  format?: string | ((input: EventFormatterInput) => unknown[]);
  /** Formatter callbacks for a specific event */
  formatters?: Record<EventSource, Record<string, (input: EventFormatterInput) => object | unknown[]>>;
  /** Allow switching specific events on/off easily */
  events?: Record<EventSource, Record<string, boolean>>;
  /** Which log level is used for logging. Default warn */
  level?: LogLevel;
  /** Which log scope is used for logging. Default '' (none) */
  scope?: string;
}

type EventSource = 'app' | 'webContents';

interface EventFormatterInput {
  args: unknown[];
  event: object;
  eventName: string;
  eventSource: string;
}

interface EventLogger extends Required<EventLoggerOptions> {
  setOptions(options: EventLoggerOptions): void;
  startLogging(options?: EventLoggerOptions): void;
  stopLogging(): void;
}