magiclogger - v0.1.0
    Preparing search index...

    Interface LoggerOptions

    Configuration options for a MagicLogger instance. These settings control the logger's behavior, output format, identity, and destination.

    interface LoggerOptions {
        context?: Record<string, unknown>;
        fallbackToSync?: boolean;
        file?: string;
        forceFlush?: boolean;
        id?: string;
        idGenerator?: () => string;
        level?: string;
        logDir?: string;
        logRetentionDays?: number;
        maxStoredLogs?: number;
        mode?: "sync" | "async" | "auto" | "balanced";
        performance?: "features" | "balanced" | "speed";
        performanceMode?: boolean;
        prettyPrint?: "json" | "inspect";
        printMetaInDebug?: boolean;
        queueManager?: QueueManagerOptions | QueueManager;
        rateLimiter?: RateLimiterOptions | RateLimiter;
        redactor?: RedactorOptions | Redactor;
        sampler?: SamplerOptions | Sampler;
        storageName?: string;
        storeInBrowser?: boolean;
        strictLevels?: boolean;
        tags?: string[];
        theme?: string | ThemeDefinition;
        themeByTag?: Record<string, string>;
        transports?: Transport[];
        useColors?: boolean;
        useConsole?: boolean;
        useDefaultTransports?: boolean;
        useLocalStorage?: boolean;
        verbose?: boolean;
        writeToDisk?: boolean;
    }

    Hierarchy (View Summary)

    Index

    Properties

    context? fallbackToSync? file? forceFlush? id? idGenerator? level? logDir? logRetentionDays? maxStoredLogs? mode? performance? performanceMode? prettyPrint? printMetaInDebug? queueManager? rateLimiter? redactor? sampler? storageName? storeInBrowser? strictLevels? tags? theme? themeByTag? transports? useColors? useConsole? useDefaultTransports? useLocalStorage? verbose? writeToDisk?

    Properties

    context?: Record<string, unknown>

    Optional default context applied to all logs. Can include environment metadata, user data, etc. Individual log calls may override this.

    { env: 'staging', region: 'us-east-1' }
    fallbackToSync?: boolean

    Fallback to synchronous logging when async buffers are full. Only applies when mode is 'async' or 'balanced'.

    true
    file?: string

    File path for log output (SyncLogger only). When provided, logs will be written to this file synchronously.

    './audit.log'
    forceFlush?: boolean

    Force flush to disk after each write (SyncLogger only). Uses fsync to ensure data is written to disk.

    true
    id?: string

    Unique identifier for the logger instance. Used for filtering logs across services or systems.

    'auth-service'
    idGenerator?: () => string

    Custom ID generator function for log entries.

    level?: string

    Minimum log level to output. Messages below this level will be filtered out.

    'info' // Only info, warn, error, fatal will be logged

    'info'
    logDir?: string

    Directory to store log files in (Node only).

    'logs'
    logRetentionDays?: number

    Number of days to retain log files before pruning (Node only).

    30
    maxStoredLogs?: number

    Maximum number of log entries to keep in browser storage. Has no effect in Node.js environments.

    1000
    mode?: "sync" | "async" | "auto" | "balanced"

    Logger performance mode configuration.

    • 'sync': Always synchronous (immediate output)
    • 'async': Always asynchronous (uses internal AsyncLogger)
    • 'auto': Smart detection based on environment
    • 'balanced': Micro-async buffer with sync fallback
    'sync'
    performance?: "features" | "balanced" | "speed"

    Performance target hint for auto mode detection.

    • 'features': Prioritize rich styling and features (sync)
    • 'speed': Prioritize throughput (async)
    • 'balanced': Balance between features and speed
    'balanced'
    performanceMode?: boolean

    Enable performance mode to disable styling for maximum throughput. When enabled, all styling is bypassed for 3x+ performance improvement.

    false
    prettyPrint?: "json" | "inspect"

    Pretty-printing mode for non-string variadic args. 'inspect' uses util.inspect in Node (with colors when enabled); 'json' uses JSON.stringify; default is 'inspect'.

    printMetaInDebug?: boolean

    When true, and verbose mode is enabled, append a compact [meta] summary of selected keys after the printed message. Meta remains structured for transports. Default: false

    queueManager?: QueueManagerOptions | QueueManager

    Queue management configuration for handling backpressure. Can be a QueueManager instance or options to create one.

    // Using options
    queueManager: { maxSize: 10000, dropPolicy: 'tail', highWaterMark: 0.8 }

    // Using instance
    queueManager: new QueueManager({ maxSize: 5000, dropPolicy: 'priority' })
    rateLimiter?: RateLimiterOptions | RateLimiter

    Rate limiting configuration for log throttling. Can be a RateLimiter instance or options to create one.

    // Using options
    rateLimiter: { max: 1000, window: 60000, strategy: 'sliding' }

    // Using instance
    rateLimiter: new RateLimiter({ max: 100, window: 10000 })
    redactor?: RedactorOptions | Redactor

    PII and sensitive data redaction configuration. Can be a Redactor instance or options to create one.

    // Using preset
    redactor: { preset: 'strict' }

    // Using instance
    redactor: new Redactor({ preset: 'paranoid', auditTrail: true })
    sampler?: SamplerOptions | Sampler

    Statistical sampling configuration for volume control. Can be a Sampler instance or options to create one.

    // Using options
    sampler: { rate: 0.1, strategy: 'adaptive', targetRate: 1000 }

    // Using instance
    sampler: createSamplerPreset('production')
    storageName?: string

    Name to use for browser storage (localStorage key or IndexedDB name). Has no effect in Node.js environments.

    'magiclogger-logs'
    storeInBrowser?: boolean

    Whether to store logs in browser storage when in browser environment. Has no effect in Node.js environments.

    false
    strictLevels?: boolean

    Enforces strict log level behavior. If true, unknown levels passed to .log() will throw. If false, unknown levels are treated as custom and passed to .custom().

    false
    tags?: string[]

    Optional static tags applied to all logs from this logger. Helps group or filter logs by functional or organizational tag.

    ['api', 'auth']
    theme?: string | ThemeDefinition

    Theme used to style logger output. Can be a string (theme name from ThemeManager) or a full object.

    'dark'

    {
       *   info: ['cyan', 'bold'],
       *   error: ['brightRed', 'bold'],
       *   header: ['brightWhite', 'bgBlue', 'bold']
       * }
    themeByTag?: Record<string, string>

    Optional mapping of tags to theme names. When provided, if a logger has any tag present in this map and no explicit theme is set, the mapped theme will be auto-applied. This enables brand/company-specific themes via tags.

    { acme: 'acme', contoso: 'contoso-dark' }
    transports?: Transport[]

    Array of transports to use for logging.

    []
    useColors?: boolean

    Enables or disables terminal or console color output.

    true
    useConsole?: boolean

    Whether to use console transport by default. Set to false to disable automatic console output.

    true
    useDefaultTransports?: boolean

    Whether to automatically create default transports.

    false
    useLocalStorage?: boolean

    Whether to use localStorage (true) or IndexedDB (false) for browser storage. Has no effect in Node.js environments.

    true
    verbose?: boolean

    If enabled, debug-level logs will be shown.

    false
    writeToDisk?: boolean

    Writes logs to disk in timestamped .log files (Node only). Ignored in browsers.

    false

    Settings

    Member Visibility

    On This Page

    Properties