logger

Usage

const {createLogger} = require(`@vizydrop/logger`);

const log = createLogger({
    level: `info`,
    mode: process.env.NODE_ENV,
    correlationId: {
        enabled: true,
        fieldName: `correlationId`, // default name is correlationId
        getCorrelationId: () => `correlation-id-value`, // required
        emptyValue: null, // used when correlation id is missing
    },
    additionalFields: {field1: `value`},
});

log.info(`message`);

NestJS

createNestLogger returns an object that satisfies the LoggerService interface of @nestjs/common, so it can be passed to app.useLogger() as is. Nest is not a dependency of this package, neither at runtime nor in the types.

// main.ts
import {NestFactory} from "@nestjs/core";
import {createNestLogger} from "@vizydrop/logger";

const app = await NestFactory.create(AppModule, {bufferLogs: true});

app.useLogger(
    createNestLogger({
        mode: process.env.NODE_ENV,
        level: process.env.LOG_LEVEL,
        correlationId: {
            enabled: true,
            getCorrelationId: () => als.getStore()?.correlationId,
            emptyValue: null,
        },
    }),
);

bufferLogs: true keeps the bootstrap records, they are replayed once the logger is set.

To share a single logger between Nest and the request log middleware, adapt an existing one:

const {
    createLogger,
    toNestLogger,
    createExpressRequestLogMiddleware,
} = require(`@vizydrop/logger`);

const log = createLogger({mode: process.env.NODE_ENV});

app.useLogger(toNestLogger(log));
app.use(createExpressRequestLogMiddleware({logger: log}));

Both are also available as @vizydrop/logger/nest.

How Nest calls are translated:

| Nest | this package | | --------------------------------- | -------------------------------------- | | log | info | | warn, error, debug, fatal | same level | | verbose | debug | | trailing context string | context field | | trailing stack string | stack field | | Error as a message | message plus stack, __errorMessage | | object as a message | stringified message |

verbose is mapped to debug on purpose: trace has the same priority as info in this package, so verbose records would not be filtered out on the info level.

The underlying logger stays reachable through the logger property, use it for trace and for the raw log(level, message) call. startTimer() and additionalFields are exposed directly.

setLogLevels is not implemented: it is optional in LoggerService and Nest calls it through optional chaining. Set the minimum level through the level option instead, winston keeps a single threshold rather than a list of levels.

Request logging

const {
    createExpressRequestLogMiddleware,
    createKoaRequestLogMiddleware,
} = require(`@vizydrop/logger`);

app.use(
    createExpressRequestLogMiddleware({
        logger: log,
        skip: (req) => req.url.startsWith(`/internal`), // /status, /assets and /health are skipped by default
    }),
);

Each request produces an inbound record and an outbound one with timeMs, size and statusCode. Query string values of token, jwt and sessionId are masked.

Other options

const log = createLogger({
    metadata: {
        enabled: true,
        getMetadata: () => ({`trace.id`: getTraceId()}), // required when enabled
    },
    transports: [myWinstonTransport], // the console transport is always added
    additionalFields: {pid: () => process.pid}, // functions are evaluated per record
});

log.additionalFields.add({tenant: `acme`});
log.additionalFields.remove([`tenant`]);

const timer = log.startTimer();
timer.done(`work is done`); // adds durationMs

trace.id, transaction.id and span.id are kept at the top level of a production record, everything else goes into @fields.

Development

yarn lint   # eslint
yarn test   # vitest, then tsc over the type tests, then the build, then the nest compatibility check