Implementation Guide - Unified Logger (@x-developer/unified-logger)

A comprehensive guide for developers to implement and integrate the unified logger into their Node.js applications.

📚 Table of Contents

1. Quick Start
2. Installation Methods
3. Configuration Setup
4. Papertrail Integration
5. Express/Fastify Integration
6. Environment Variables
7. TypeScript Setup
8. UDP Relay Transport
9. Production Deployment
10. Troubleshooting
11. Examples

🚀 Quick Start

1. Install the Package

npm install @x-developer/unified-logger

2. Create Configuration File

Create logger.json in your project root:

{
  "service": "your-service-name",
  "env": "development",
  "level": "DEBUG",
  "transports": {
    "console": { "enabled": true },
    "papertrail": {
      "enabled": false,
      "host": "logs.papertrailapp.com",
      "port": 12345,
      "program": "your-service"
    },
    "udpRelay": {
      "enabled": false,
      "host": "127.0.0.1",
      "port": 9999,
      "maxPacketBytes": 1400
    }
  },
  "sampling": { "debug": 1.0, "info": 1.0 },
  "redact": {
    "headers": ["authorization", "cookie"],
    "queryParams": ["password", "token"]
  }
}

3. Initialize in Your Application

import { initLogger, logger } from "@x-developer/unified-logger";

// Initialize once at application start
initLogger("./logger.json");

// Use anywhere in your application
logger.info("Application started");
logger.error("Error occurred", { userId: 123, action: "login" });

📦 Installation Methods

Node.js Version Requirements

• Minimum: Node.js v18.0.0
• Recommended: Node.js v22.x.x (LTS)
• ESM Support: Full ES module support

Package Manager Options

# NPM
npm install @x-developer/unified-logger

# Yarn
yarn add @x-developer/unified-logger

# PNPM
pnpm add @x-developer/unified-logger

Package Configuration

For ESM (recommended):

{
  "type": "module",
  "dependencies": {
    "@x-developer/unified-logger": "^1.0.10"
  }
}

For CommonJS:

{
  "dependencies": {
    "@x-developer/unified-logger": "^1.0.10"
  }
}

⚙️ Configuration Setup

Basic Configuration

{
  "service": "my-api",
  "env": "production",
  "level": "INFO",
  "transports": {
    "console": { "enabled": true },
    "papertrail": { "enabled": false },
    "udpRelay": { "enabled": false, "host": "", "port": 0 }
  }
}

Advanced Configuration

{
  "service": "my-api",
  "env": "production",
  "level": "INFO",
  "transports": {
    "console": { "enabled": true, "colorize": true },
    "papertrail": {
      "enabled": true,
      "host": "logs.collector.eu-01.cloud.solarwinds.com",
      "port": 443,
      "program": "my-api-prod",
      "disableTlsVerify": false
    },
    "udpRelay": {
      "enabled": true,
      "host": "log-relay.internal",
      "port": 5140,
      "maxPacketBytes": 65000
    }
  },
  "sampling": { "debug": 0.1, "info": 0.5 },
  "redact": {
    "headers": ["authorization", "cookie", "x-api-key"],
    "queryParams": ["password", "token", "secret"],
    "bodyKeys": ["creditCard", "ssn"]
  },
  "correlation": { "enabled": true, "header": "X-Request-ID" }
}

📄 Papertrail Integration

1. Login to Papertrail and get host/port/program
2. Configure the papertrail transport
3. Optionally set PAPERTRAIL_TOKEN for HTTP transport auth

🌐 Express/Fastify Integration

Express:

import express from "express";
import {
  initLogger,
  logger,
  createRequestLogger,
  createCorrelationId,
} from "@x-developer/unified-logger";

initLogger("./logger.json");
const app = express();
app.use(createCorrelationId());
app.use(createRequestLogger());

Fastify:

import fastify from "fastify";
import {
  initLogger,
  logger,
  createRequestLoggerHook,
  createCorrelationIdHook,
} from "@x-developer/unified-logger";

initLogger("./logger.json");
const server = fastify();
server.addHook("onRequest", createCorrelationIdHook());
server.addHook("onRequest", createRequestLoggerHook());

🌍 Environment Variables

Key overrides:

LOG_LEVEL=INFO
LOG_TRANSPORTS_CONSOLE_ENABLED=true
LOG_TRANSPORTS_PAPERTRAIL_ENABLED=true
LOG_SAMPLING_DEBUG=0.1
LOG_SAMPLING_INFO=0.5
LOG_REDACT_HEADERS=authorization,cookie
LOG_REDACT_QUERYPARAMS=password,token

Note: WARN and ERROR levels are always logged (100% sampling) regardless of configuration.

📘 TypeScript Setup

tsconfig.json essentials:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "skipLibCheck": true
  }
}

Type-safe config example:

import { ILoggerConfig, LogLevel } from "@x-developer/unified-logger";
const config: ILoggerConfig = {
  service: "my-api",
  env: "production",
  level: "INFO" as LogLevel,
  transports: {
    console: { enabled: true },
    papertrail: {
      enabled: true,
      host: "logs.papertrailapp.com",
      port: 12345,
      program: "my-api",
    },
    udpRelay: { enabled: false, host: "", port: 0 },
  },
  sampling: { verbose: 0.05, debug: 0.1, info: 1.0 },
  redact: { headers: ["authorization"], queryParams: ["token"] },
};

🔌 UDP Relay Transport

Fire-and-forget UDP logging for low-latency pipelines.

• maxPacketBytes: configurable (default 65000)
• Oversized messages are truncated
• Internal counters: sent, dropped, errors

Example:

{
  "transports": {
    "udpRelay": {
      "enabled": true,
      "host": "log-relay.internal",
      "port": 5140,
      "maxPacketBytes": 65000
    }
  }
}

🚀 Production Deployment

Dockerfile, compose, and Kubernetes examples provided. Expose /metrics for Prometheus.

🔧 Troubleshooting

Common issues and fixes for module resolution, ESM/CJS, Papertrail connectivity, and TypeScript.

📋 Examples

See examples/ and TEST/ for end-to-end usage and ready-to-run setups.

📚 Documentation & Resources

• Complete Guide (Simple): SIMPLE_COMPLETE_GUIDE.md
• Auto-Correlation ID Guide: AUTO_CORRELATION_GUIDE.md
• Developer Checklist: DEVELOPER_CHECKLIST.md
• Quick Reference: QUICK_REFERENCE.md
• API/Integration/Env/Deployment under docs/

Happy Logging! 🪵