npm package: @remus-framework/log
Description: the logger of the remus framework
Author: Lukas Baron
Latest version: 1.0.2

# Remus Log

The logger of the Remus Application Framework that is also usable in an independent manner.

## How to use

Create a logger and log to it:

    import { l } from "@remus-framework/log";
    const log = l("mycode.file"); // sets the code reference information to this logger instance
    log.error("this is my first error message"); //creates a log message and propagates it to the appenders specified

    //the output could look like this
    [timestamp][ERROR][mycode.file] this is my first error message

Providing more information to be logged:

    import { l, Categories } from "@remus-framework/log";
    const log = l("mycode.file", Categories.IO, "client"); //sets also the category and origin properties of the logger instance

    log.id("id").category(".rest").ref("handlerclass").origin("webworker").warn("this is a warning"); //specifies multiple properties for the new message, properties set to the logger are propagated to the message

    //the output could look like this
    [timestamp][client/webworker][ WARN][id][IO.rest][mycode.file:handlerclass] this is a warning

Logging things once:

    import { l } from "@remus-framework/log";
    const log = l("mycode.file");

    log.once().trace("a config should be provided"); // this message will be propagated once with the same log level (trace)
    log.once("a unique id").trace("a config should be provided"); // a call using the same once-id will be logged once independently from other message properties
    log.id("message-id").once().fatal("a config should be provided"); // only one message using the same id and log level will be logged

Providing dynamic message parameters:

    import { l } from "@remus-framework/log";
    const log = l("mycode.file");

    log.debug("parameter '%parameter%' with value '%value%' is not acceptible, try %mitigations.a%", {parameter = "XY", value = 0.5, mitigations : { a : "test"}});

    const e = new Error("E_ILLEGAL");
    log.error("an error occurred: %e.message% at %e.stack%", {e});

Configuring the appenders:

    import { Logger, Severity } from "@remus-framework/log";
    import { ColourConsoleAppender, FileAppender, Filters } from "@remus-framework/log/appenders";

    Logger.addAppender(new ColourConsoleAppender()); //logs coloured console output
    let fileAppender = new FileAppender();
    Logger.addAppender(fileAppender); //logs to a .log file in the current working directory

    fileAppender.addFilter(Filters.SEVERITY_MIN(Severity.INFO)); //add a filter to the file appender in order only to log info and above messages

Add a fallback appender that catches all not logged messages and errors from the log framework as well as disable the internal log message cache for unappended messages:

    import { Logger , setRootLoggerProperties } from "@remus/log";
    import { VoidAppender } from "@remus/log/appenders";

    //add a catch all appender as fallback
    Logger.addFallBackAppender(new VoidAppender());

    //or disable the cache manually
    setRootLoggerProperties(true);

This is only basic usage information, see [Source Code Documentation](https://leiterschleife.de/projects/serious/remus/docs) or [Remus Homepage](https://leiterschleife.de/projects/serious/remus.html) for more.

## How to develop

The following components are used for developing:

-   Typescript via `tsconfig.json` and `tsconfig.spec.json` (for testing) both inheriting from `tsconfig.base.json`. The configuration is rather restricting focusing on modern environments. In some cases, e.g. a function in a class that shall be implemented by subclasses while declaring parameters, certain rules may be locally overridden, in this case, to allow unused parameters. Call `npm run build` to generate the JavaScript sources including map and d.ts files in the `./build` directory.
-   Eslint via the `eslint.config.js`. While linting is done prior to building, it is useful to enable an eslint plugin in the IDE. Eslint is configured for the use of typescript.
-   Mocha for testing and expect as its assertion framework. All tests are located under `./test` using the `*.spec.ts` file name pattern. Test are built and executed automatically when calling `npm run test`.
-   Debugging tests is supported, use the `Debug Test` launch configuration for that and place breakpoints in the `*.ts` sources or `*.spec.ts` test sources.
-   C8 for generating coverage reports (console and in the `./reports` directory as html). Run `npm run coverage` for generating the reports. Open `/reports/coverage/index.html` in a browser to read the interactive documentation.
-   Typedoc for generating docs. Run `npm run docs` for generating them. Open `docs/index.html` in a browser to read the documentation.