microtec-logger v0.1.11

Logger

[TOC]

1. Description

"Logger" is a library for logging and tracking program activities. The output can be sent to a log file and/or to the JavaScript console.

2. Format of the output

YYYY-MM-DD HH:MM:SS.FFF | AppName | ModuleName | LogType | Message

AppName: The name of the app set in the LoggerSettings. Will be omitted if the value is missing.

ModuleName: Optional. The name of the module sent per log command, or the standardModuleName of the LoggerSettings. Will be omitted if both values are missing.

LogType: INFO or WARNING or ERROR.

3. LoggerSettings

interface LoggerSettings {
    appName?: string;
    standardModuleName?: string;
    fileName?: string;
    logToConsole?: boolean;
    countMessages?: boolean;
    
    defaultPriority?: number;
    minPriorityToWriteInLogFile?: number;

    logFileSizeLimitInMB?: number;
    zippedLogFileArchivesToKeep?: number;
    zippedLogFileArchivesMaxAgeInSeconds?: number;

    startMessage?: string;
    endMessage?: string;

    useBuffer?: boolean;
    bufferAutoFlushIntervalInSeconds?: number;

    keepMessagesInMemory? : number;
}

3.1 appName

Optional. The name of the app, shown in the output of each log message.

3.2 standardModuleName

Optional. The name of the module inside the app. can be overwritten by the module parameter of the log commands.

3.3 fileName

Optional. If missing, the output is not written to a file, but only eventually to the console.

3.4 logToConsole

Optional. Indicates if the output is written to the JavaScript console. Defaults to false if ommited.

3.5 countMessages

Optional. Indicates if the logged messages should be count. Defaults to false if ommited.

3.6 defaultPriority

Optional. The default priority, if in the log methods is not sent another priority. Defaults to 2 if ommited.

3.7 minPriorityToWriteInLogFile

Optional. The minimum priority of the log message to be written in the log file. With this setting it is at example possible to log some messages only to the console, and others in the log file too. Defaults to 2 if ommited.

3.8 logFileSizeLimitInMB

Optional. If the log file grows to a size bigger than this setting in megabytes, the actual file is zipped and archived. After zipping, the actual log file is emptied. If the value is -1, there is no limit for the log file size. Defaults to -1 if ommited.

3.9 zippedLogFileArchivesToKeep

Optional. The count of zip archives the library should keep. If this number is exceeded, always the oldest zip archive will be deleted, when a new archive is created. If the value is -1, there is no limit. Defaults to -1 if ommited.

3.10 zippedLogFileArchivesMaxAgeInSeconds

Optional. The max age in seconds the library should keep zip archive. Older zip archives are deleted automatically. If the value is -1, there is no limit. Defaults to -1 if ommited.

3.11 startMessage

Optional. If set, this message is logged before the first "real" log message. But if never a "real" log message will occur, even this message will not be printed.

3.12 endMessage

Optional. If set, this message is logged when the method exit() is called, but only if the startMessage happened.

3.13 useBuffer

Optional. If set, log messages are not printed directly to the log file, but cached in a buffer. The buffer can be flushed automatically in a defined time interval (bufferAutoFlushIntervalInSeconds), or by calling the method flush() or by calling the method exit(). Defaults to false if ommited.

3.14 bufferAutoFlushIntervalInSeconds

Optional. Time interval in seconds to automatically flush the buffer. Has only effect, if useBuffer is true. The value -1 disables the automatic flush. Defaults to 5 if ommited.

3.15 keepMessagesInMemory

Optional. Keeps this number of messages in the memory to have the possiblity to read them without touching a file. The option can be disabled by not setting this option or by setting it to 0. The in the memory stored messages can be fetched with the method getMessagesInMemory(), which returns an array of MessageInMemory. Example: keepMessagesInMemory: 10000

4. Installation

npm install microtec-logger

5. Constructor

The constructor takes a parameter of the type LoggerSettings.

import { Logger } from 'microtec-logger';

let logger: Logger;

try {
    logger = new Logger({
        appName: "AppName",
        fileName: "logs/logFile.log",
        ...
    });
}
catch (err) {
    // error handling
}

The constructor creates automatically and recursively the directory of the log file, if not exists.

The constructor can throw errors, at example if the directory of the log file can not be created.

6. Log Methods

6.1 info

info(message: string, moduleName?: string, priority?: number);

Writes a "INFO" message to the log.

If moduleName or priority are missing or undefined, the default values defined in the settings are used.

6.2 warn

warn(message: string, moduleName?: string, priority?: number);

Writes a "WARNING" message to the log.

If moduleName or priority are missing or undefined, the default values defined in the settings are used.

6.3 error

error(message: string, moduleName?: string, priority?: number);

Writes an "ERROR" message to the log.

If moduleName or priority are missing or undefined, the default values defined in the settings are used.

6.4 errorStack

errorStack(error: Error, moduleName?: string, priority?: number);

Writes an "ERROR" message to the log. As message the message property of the Error object is used, and in addition the stack property of the Error object is written to the log, if present.

If moduleName or priority are missing or undefined, the default values defined in the settings are used.

6.5 log

log(type: LogType, message: string, moduleName?: string, priority?: number);

Depending on the type parameter, this method internally calls info(), warn() or error().

The LogType enum can be imported from the library and looks like this:

enum LogType {
    Info,
    Warning,
    Error
}

6.6 flush

flush();

If useBuffer is true, this method flushes the buffer to the log file.

6.7 exit

exit(moduleName?: string);

If endMessage is set, this method writes the end message to the log (but only if the startMessage was written too).

If useBuffer is true, this method flushes the buffer to the log file.

7. Message count methods

These functions are only relevant, if the setting countMessages is set to true. Otherwise all these functions return always 0.

7.1 getTotalMessageCount

getTotalMessageCount();

Returns the total count of messages written since the call of the constructor.

7.2 getTotalMessageCountByType

getTotalMessageCountByType(type: LogType);

Returns the total count of messages of this specific type, written since the call of the constructor.

Possible values for the parameter: LogType.Info, LogType.Warning and LogType.Error.

7.2 getTotalMessageCountByPriority

getTotalMessageCountByPriority(priority: number);

Returns the total count of messages of this specific priority, written since the call of the constructor.

7.3 getTotalMessageCountByTypeAndPriority

getTotalMessageCountByTypeAndPriority(type: LogType, priority: number);

Returns the total count of messages of this specific type and priority, written since the call of the constructor.

Possible values for the parameter type: LogType.Info, LogType.Warning and LogType.Error.

7.4 setCheckpoint

setCheckpoint();

Sets a checkpoint for the follwing methods.

7.5 getCheckpointMessageCount

getCheckpointMessageCount();

Returns the total count of messages written since the call of the constructor or the last call of setCheckpoint.

7.6 getCheckpointMessageCountByType

getCheckpointMessageCountByType(type: LogType);

Returns the total count of messages of this specific type, written since the call of the constructor or the last call of setCheckpoint.

Possible values for the parameter: LogType.Info, LogType.Warning and LogType.Error.

7.7 getCheckpointMessageCountByPriority

getCheckpointMessageCountByPriority(priority: number);

Returns the total count of messages of this specific priority, written since the call of the constructor or the last call of setCheckpoint.

7.8 getCheckpointMessageCountByTypeAndPriority

getCheckpointMessageCountByTypeAndPriority(type: LogType, priority: number);

Returns the total count of messages of this specific type and priority, written since the call of the constructor or the last call of setCheckpoint.

Possible values for the parameter type: LogType.Info, LogType.Warning and LogType.Error.

8. Messages in memory

If the settings property keepMessagesInMemory is set and greater than zero, this count of messages will be kept in memory.

8.1 MessageInMemory interface

interface MessageInMemory {
    id: number;            // sequential number. Starts with 0 when the logger is created.
    dateTime: Date;        // date and time of the message
    delta: number;         // delta in ms since the last message
    ticToc: number;        // delta in ms since the creation of the Logger
    type: LogType;         // enum; LogType.Info = 0 |  LogType.Warning = 1 | LogType.Error = 2
    appName?: string;      // the app name, if set. Else undefined
    moduleName?: string;   // the module name, if set. Else undefined
    message: string;       // the message text
}

8.2 getMessagesInMemory method

getMessagesInMemory(): MessageInMemory[];

Returns all in the memory stored messages as array of MessageInMemory.