@webcontext/winston v0.1.12

Overview

This logger module is built with Winston and integrates with both Google Cloud Logging and local file logging. It supports daily log file rotation and formats logs for both human-readable and machine-readable outputs. This logger is customisable for various services and environments (development or production).

Prerequisites

• Node.js 14.x or later
• Winston logging library
• Google Cloud Logging setup (optional for cloud logging)

Installation

1. Clone or download the project repository.
2. Install dependencies using npm:

npm install winston winston-daily-rotate-file @google-cloud/logging-winston

3. (Optional) For Google Cloud Logging, you need to set up a service account on your Google Cloud project and download the credentials file (JSON format).

Usage

1. Import the createLogger function:

import { createLogger } from './logger.js';

2. Call the createLogger function and configure the options as needed:

const logger = createLogger({
  relativePath: './logs', // Custom path to save logs
  service: 'myService', // Name of the service using this logger
  googleCloudConfig: {
    projectId: 'your-project-id',
    keyFilename: './path-to-your-google-credentials-file.json',
  },
});

3. Log messages at different levels (e.g., info, error, warn, debug):

logger.info('This is an info message');
logger.error('This is an error message');

Configuration Options

• relativePath: Directory where log files will be saved. Defaults to ../../logs.
• service: Name of the service (used for log categorisation). Defaults to defaultService.
• googleCloudConfig: Configuration object for Google Cloud Logging. Requires projectId and keyFilename.

Log File Structure

Logs are stored in the specified directory, rotated daily, and follow this naming convention:

• combined-%DATE%.log: Machine-readable JSON logs.
• combined-pretty-%DATE%.log: Human-readable logs.
• error-%DATE%.log: Error logs.
• exception.log: Logs unhandled exceptions.
• rejections.log: Logs unhandled promise rejections.

Each log file rotates daily and is automatically deleted after 90 days. Individual log files are limited to a maximum size of 20MB.

Google Cloud Logging

Logs can be sent to Google Cloud Logging if the googleCloudConfig object is set correctly. You must provide the following properties:

• projectId: Google Cloud project ID.
• keyFilename: Path to the service account credentials file (JSON).

Ensure the service account has appropriate permissions for writing logs to Google Cloud.

Logging in Different Environments

• Production: By default, logs are set to info level in production, meaning only significant logs are recorded. Unhandled promise rejections will terminate the process.
• Development: Logs are set to debug level in development, providing more detailed logs, including stack traces for easier debugging.

Example Code

import { createLogger } from './logger.js';

const logger = createLogger({
  relativePath: './logs',
  service: 'myAppService',
  googleCloudConfig: {
    projectId: 'my-gcp-project-id',
    keyFilename: './path-to-my-gcp-credentials.json',
  },
});

logger.info('Application has started');
logger.error('An error occurred while connecting to the database');

Error Handling

Unhandled promise rejections and exceptions are automatically caught and logged. In production, the application will exit after logging an unhandled rejection.

Contributing Feel free to open a pull request or issue if you find any bugs or have suggestions for improvements.