@caregenix/sumo-logger

A production-ready, TypeScript-first logging library for shipping logs to Sumo Logic HTTP Sources. Optimized for Node.js (18+) and Next.js backends.

🚀 Features

• High Performance: Built-in batching and buffering to minimize network overhead.
• Request Tracking: Automatic requestId tracing using AsyncLocalStorage.
• TypeScript Native: Full typing support for a superior developer experience.
• Smart Error Handling: Automatically preserves and formats stack traces for Error objects.
• Isomorphic: Works seamlessly in Node.js, Next.js (API routes & Middleware), and Edge functions.
• Flexible: Supports both Singleton and Instance-based usage for better testability.

📦 Installation

npm install @caregenix/sumo-logger

🛠️ Usage Guide

1. Initialization (Best Practices)

Is a Singleton right for me? Yes, for most applications, initializing once globally is the correct approach. It ensures all parts of your app share the same connection pool, batching queue, and configuration.

Step A: Create a logger configuration file

Create a file like lib/logger.ts in your project.

import SumoLogger from '@caregenix/sumo-logger';

// Initialize once
SumoLogger.initialize({
  httpSourceUrl: process.env.SUMO_LOGIC_URL!,
  sourceName: 'my-production-app',
  defaultMetadata: {
    env: process.env.NODE_ENV,
    version: '1.0.0'
  },
  batchInterval: 5000, // Batch every 5 seconds
  batchSize: 100,      // Or every 100 logs
});

// Export the instance for use throughout your app
export const logger = SumoLogger.getInstance();

Step B: Use it anywhere

import { logger } from './lib/logger';

logger.info('User logged in', { userId: '123' });

2. Advanced Usage

Request Tracing (Next.js/Node.js Middleware)

To correlate all logs within a single request, wrap your handler:

import { runWithRequestId } from '@caregenix/sumo-logger';
import { logger } from './lib/logger';

export default async function handler(req, res) {
  const requestId = req.headers['x-request-id'] || 'gen-' + Date.now();
  
  return runWithRequestId(requestId, async () => {
    logger.info('Processing API request'); // Will include requestId in Sumo Logic
    // ... logic
  });
}

Error Logging

try {
  throw new Error('Database connection failed');
} catch (err) {
  // Automatically captures error message and stack trace
  logger.error('Critical Error', err);
}

Graceful Shutdown

To ensure pending logs are sent before the process exits:

process.on('SIGTERM', async () => {
  await logger.flush();
  process.exit(0);
});

3. Instance-based Usage (DI)

Useful for unit testing or if you need multiple distinct loggers.

import { SumoLogger, SumoTransport } from '@caregenix/sumo-logger';

const transport = new SumoTransport({ httpSourceUrl: '...' });
const logger = new SumoLogger({ httpSourceUrl: '...' }, transport);

⚙️ Configuration Options

| Option | Type | Default | Description | | :--- | :--- | :--- | :--- | | httpSourceUrl | string | - | Required. Sumo Logic HTTP Source URL. | | sourceName | string | - | X-Sumo-Name header. | | sourceCategory| string | - | X-Sumo-Category header. | | defaultMetadata| object | {} | Metadata included in every log. | | batchInterval | number | 5000 | Batching interval in ms (0 to disable). | | batchSize | number | 100 | Max messages per batch. | | internalLogger| object | console | Logger for internal library health. |

📜 License

MIT