Loggo

Logging library for Node.js and Bun with file rotation, SMTP notifications, and JSON output support.

Features

• Multiple log levels: INFO, WARN, DEBUG, ERROR, FATAL
• Automatic file rotation: Daily rotation with configurable retention
• SMTP notifications: Email alerts for fatal errors with throttling
• JSON output: Optional structured logging in JSONL format
• Caller tracking: Automatic source file and line number tracking
• TypeScript support: Full type definitions included
• Zero configuration: Works out of the box with sensible defaults

Installation

npm install @vinialx/loggo

bun add @vinialx/loggo

Quick Start

import { Loggo } from "@vinialx/loggo";

const logger = new Loggo({ client: "MyApp" });

logger.info("APP_START", "Application started");
logger.warn("HIGH_MEMORY", "Memory usage above 80%");
logger.error("API_FAIL", "External API request failed");
logger.fatal("DB_DOWN", "Database connection lost");

Configuration

Basic Configuration

const logger = new Loggo({
  client: "MyApp", // Application name
  console: true, // Enable console output
  debug: false, // Enable debug logs
  json: false, // Enable JSON output
});

File Configuration

const logger = new Loggo({
  client: "MyApp",
  directory: {
    txt: "/var/log/myapp", // Text log directory
    json: "/var/log/myapp/json", // JSON log directory
  },
  filecount: {
    txt: 31, // Keep 31 days of text logs
    json: 7, // Keep 7 days of JSON logs
  },
});

SMTP Configuration

const logger = new Loggo({
  client: "MyApp",
  smtp: {
    host: "smtp.gmail.com",
    port: 465,
    secure: true,
    username: "[email protected]",
    password: "your-password",
    from: "[email protected]",
    to: "[email protected]", // Can be string or array
  },
  throttle: 300000, // Min 5 minutes between emails
});

Environment Variables

SMTP can be configured via environment variables:

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
[email protected]
SMTP_PASSWORD=your-password
[email protected]
[email protected]

API Reference

Constructor

new Loggo(options?: Partial<LoggoConfig>)

Options:

• client: Application name (default: 'Loggo')
• console: Enable console output (default: true)
• debug: Enable debug mode (default: false)
• json: Enable JSON output (default: false)
• directory: Log directories (default: ~/[client]/logs)
• filecount: Retention days (default: { txt: 31, json: 31 })
• smtp: SMTP configuration (optional)
• throttle: Email throttle in ms (default: 30000)

Logging Methods

logger.info(code: string, message: string): void
logger.warn(code: string, message: string): void
logger.debug(code: string, message: string): void
logger.error(code: string, message: string): void
logger.fatal(code: string, message: string): void

Parameters:

• code: Short identifier for the log entry
• message: Detailed log message

Configuration Access

// Read configuration
logger.config.client; // string
logger.config.debug; // boolean
logger.config.console; // boolean
logger.config.json; // boolean
logger.config.directory; // LoggoDirectory
logger.config.filecount; // LoggoFilecount
logger.config.notify; // boolean
logger.config.smtp; // LoggoSMTPConfig | undefined
logger.config.throttle; // number

// Clone configuration
const newConfig = logger.config.clone({ client: "NewApp" });

// Update configuration
logger.config.update({ debug: true, throttle: 60000 });

Log Format

Text Format

[MyApp] [03/11/2025 14:30:45] [INFO] [APP_START] [server.ts:15]: Application started

JSON Format (JSONL)

{
  "client": "MyApp",
  "timestamp": "2025-11-03T14:30:45.123Z",
  "level": "INFO",
  "code": "APP_START",
  "caller": "server.ts:15",
  "message": "Application started"
}

File Rotation

• Logs rotate daily at midnight
• Old logs are automatically deleted based on filecount setting
• Separate rotation for text and JSON logs
• Rotation happens asynchronously without blocking logging

Email Notifications

• Only sent for fatal() logs
• Throttled to prevent spam (configurable via throttle)
• Includes timestamp, code, caller location, and message
• HTML formatted emails

Examples

Express.js Integration

import express from "express";
import { Loggo } from "@vinialx/loggo";

const app = express();
const logger = new Loggo({ client: "API" });

app.use((req, res, next) => {
  logger.info("REQUEST", `${req.method} ${req.path}`);
  next();
});

app.use((err, req, res, next) => {
  logger.error("ERROR", err.message);
  res.status(500).json({ error: "Internal Server Error" });
});

Database Connection Monitoring

async function connectDatabase() {
  try {
    await db.connect();
    logger.info("DB_CONNECT", "Database connected successfully");
  } catch (error) {
    logger.fatal("DB_CONNECT_FAIL", error.message);
    process.exit(1);
  }
}

Scheduled Task Logging

import cron from "node-cron";

cron.schedule("0 0 * * *", () => {
  logger.info("CRON_START", "Daily cleanup task started");

  try {
    performCleanup();
    logger.info("CRON_SUCCESS", "Daily cleanup completed");
  } catch (error) {
    logger.error("CRON_FAIL", error.message);
  }
});

TypeScript Support

Full TypeScript definitions are included:

import { Loggo, LoggoConfig, LogLevel, LogEntry } from "loggo";

const config: Partial<LoggoConfig> = {
  client: "TypeScriptApp",
  debug: true,
};

const logger = new Loggo(config);

Performance Considerations

• File writes are synchronous for data integrity
• Rotation is asynchronous to avoid blocking
• Email sending is asynchronous with error handling
• Minimal overhead for disabled features

License

MIT

Support

For issues and feature requests, visit: https://github.com/vinialx/loggo/issues

Author

Email: [email protected]