📝 Logger

A structured logging module for Node.js services, supporting contextual logging, Pino, and Loki transport for Grafana integration.

✨ Features

• Contextual Logging: Automatically tracks trace_id, span_id, and correlation_id using AsyncLocalStorage.
• Structured Logging: Outputs logs in JSON format with metadata like service, environment, and host.
• Pino Integration: High-performance logging with multiple log levels (trace, debug, info, warn, error, fatal).
• Loki Transport: Sends logs to Grafana Loki for centralized log management.
• Error Handling: Automatically extracts and logs error messages and stack traces.
• Express Middleware: Logs HTTP request details, including latency and response status.
• Kubernetes Friendly: Designed to work seamlessly in containerized environments with distributed tracing support.

⚙️ Installation

Install the library and its dependencies:

npm install @zzazz/logger

🌍 Environment Variables

The logger can be configured using the following environment variables:

| Variable | Description | Default | |----------------------|-------------------------------------------|--------------------| | SERVICE_NAME | Name of the service | unknown-service | | NODE_ENV | Environment (development, production) | local | | LOG_LEVEL | Log level (trace, debug, info, warn, error, fatal) | info | | USE_LOKI | Enable Loki transport (true or false) | false | | LOKI_URL | Loki endpoint for centralized logging | - | | LOKI_USERNAME | Loki basic auth username | - | | LOKI_PASSWORD | Loki basic auth password | - | | LOG_BATCH_INTERVAL | Interval (in seconds) for batching logs to Loki | 5 |

💡 Usage

📝 Basic Logging

The logger provides multiple log levels (trace, debug, info, warn, error, fatal) and supports structured logging with metadata.

import { logger } from '@zzazz/logger';

// Log messages with different levels
logger.info('Application started');
logger.warn('Potential issue detected');
logger.error('Something went wrong', { error: new Error('Example error') });

// Log with additional metadata
logger.debug('Debugging details', { userId: 123, action: 'login' });

🌐 Middleware for Express

The library includes a middleware for logging HTTP requests in Express applications. It logs request details, response status, and latency. It automatically generates or propagates trace_id, span_id, and correlation_id for each request and logs the following:

• HTTP method and URL
• Query parameters and request body
• User agent and client IP
• Response status code
• Request latency (in milliseconds)

🛠️ How it Works

• Traceability Headers:

  • If x-trace-id or x-correlation-id headers are present in the incoming request, they are used. Otherwise, new IDs are generated using uuid.
  • These IDs are added to the response headers for downstream services to use.

• Distributed Context: The middleware uses AsyncLocalStorage to store and propagate trace_id, span_id, and correlation_id across asynchronous operations.

• Logging: Logs request details, including latency and response status, at appropriate log levels (info, warn, or error).

🖥️ Usage

import express from 'express';
import { requestLoggerMiddleware, logger } from '@zzazz/logger';

const app = express();

// Use the request logger middleware
app.use(requestLoggerMiddleware);

app.get('/', (req, res) => {
  logger.info('Handling request', { path: req.path });
  res.send('Hello World');
});

app.listen(3000, () => {
  logger.info('Server is running on port 3000');
});

🚨 Error Logging

The logger automatically extracts error messages and stack traces from Error objects in the metadata. Please make sure that you pass error key in the metadata.

try {
  throw new Error('Something went wrong');
} catch (error) {
  logger.error('An error occurred', { error });
}

📡 Running with Loki

To enable Loki transport, set the USE_LOKI environment variable to true and provide the LOKI_URL, LOKI_USERNAME, and LOKI_PASSWORD.

export USE_LOKI=true
export LOKI_URL='http://localhost:3100'
export LOKI_USERNAME='admin'
export LOKI_PASSWORD='password'

📊 Log Levels

Log levels classify and control log output volume, helping developers and admins filter logs by severity. Here’s a breakdown of log levels supported by this logger:

| Log Level | Description | Usage Scenario | |----------|-----------------------------------------------------------------------------------------------|--------------------------------------------------------------------| | | Indicates a critical error causing the application to terminate unexpectedly. | Unrecoverable failures (e.g., database connection failure). | | | Represents a failure or problem that the application can handle but needs attention. | Exceptions, failed operations, or critical bugs. | | | Indicates a potential issue or a situation that might require investigation. | Deprecated API usage or resource constraints (e.g., low memory). | | | Provides informational messages about the normal functioning of the application. | Startup messages, configuration settings, or significant operations.| | | Supplies detailed information useful for diagnosing problems during development. | Variable values, flow of execution, or internal state. | | | Offers the most granular level of logging, typically used for step-by-step tracing. | In-depth analysis and debugging of code paths. |

🕵️‍♂️ Distributed Tracing

The logger supports distributed tracing by maintaining trace_id, span_id, and correlation_id across requests using AsyncLocalStorage.

| Identifier | Purpose | Scope | When to Use | |-----------------|--------------------------------------|-------------|---------------------------------------------| | Trace ID | Tracks an entire request journey | Global | End-to-end tracing across microservices | | Span ID | Represents a single unit of work | Local | Individual operation tracking within a trace | | Correlation ID | Links logs of a business transaction | Global/Local | Business-level tracking and async handling |