🦦 stoat-tracks

A powerful, production-ready logging system for Stoat bots.
Supports console logs, daily JSON log files, automatic log rotation, and Stoat channel logging with masquerade colors.

⚠️ For use with revbot.js

✨ Features

• 🎨 Colored console output with timestamps
• 📁 Daily JSON file logs stored in /logs
• 🔄 Automatic log rotation (size-based, keeps older numbered logs)
• 🦦 Stoat channel logging using embeds, colors, and masquerading
• 🛑 Error-object awareness (extracts name, message, stack)
• 📡 Bot auto-detection (require("../bot")) with manual override
• 🎚 Per-destination log-level filtering:
  • Console: minLevel
  • File: always logs above minLevel
  • Stoat: stoatMinLevel
• 🧩 Full support for extra data (string, object, JSON, errors)
• 🚫 Auto-trims overly large Stoat messages to stay under limits

📦 Installation

npm install stoat-tracks revbot.js

🚀 Basic Usage

const logger = require("stoat-tracks");

logger.info("Startup", "Bot has logged in!");
logger.warn("Auth", "Token expired soon");

try {
    throw new Error("Something exploded");
} catch (err) {
    logger.error("CrashHandler", "Caught exception", err);
}

🧱 Log Levels

| Level | Priority | Color | Use case | | ---------- | -------- | ------- | ------------------------ | | DEBUG | 0 | Cyan | Dev messages | | INFO | 1 | Green | Normal flow | | WARN | 2 | Yellow | Suspicious but not fatal | | ERROR | 3 | Red | Something failed | | CRITICAL | 4 | Magenta | Major breakdowns |

⚙️ Configuration

You can create your own logger instance:

const Logger = require("stoat-tracks/src/index.js");

const customLogger = new Logger({
    minLevel: "DEBUG",      // console + file minimum
    enableConsole: true,
    enableFile: true,
    enableStoat: false,
    maxFileSize: 5 * 1024 * 1024, // rotate after 5MB
    maxFiles: 5,
    stoatMinLevel: "ERROR", // only send ERROR+ to Stoat
});

📁 File Logging

Logs are stored in:

logs/YYYY-MM-DD.log
logs/YYYY-MM-DD.log.1
logs/YYYY-MM-DD.log.2

Each line is a single JSON object:

{
  "timestamp": "2025-01-01T13:00:00.123Z",
  "level": "INFO",
  "category": "Startup",
  "message": "Ready!"
}

Rotation happens automatically when the file exceeds maxFileSize.

🎨 Console Logging

Console logs are timestamped and colorized:

[2025-01-01T13:00:00Z] [INFO] [Startup] Ready!

Extra data is printed below the main line:

logger.info("HTTP", "Request received", { route: "/auth" });

Output:

[INFO] [HTTP] Request received
{ route: "/auth" }

🦦 Stoat Logging

Stoat logging is disabled by default. Enable it with:

logger.setLogChannel("SERVER_ID", "CHANNEL_ID");

You may also attach a bot instance manually:

logger.setBot(bot);

Stoat Message Format

The logger sends formatted embeds using masquerading:

## ERROR | CrashHandler
**Time:** 2025-01-01T12:00:00Z
**Message:** Something exploded

**Data:**
```json
{
  "name": "Error",
  "message": "Something exploded",
  "stack": "..."
}

Message length is auto-trimmed if over 2000 characters.

🤖 Bot Auto-Detection

If setBot() is not used, the logger will try:

require("../bot")

It supports:

• module.exports = bot
• exports.bot = bot
• exports.default = bot

If the bot cannot be loaded, Stoat logging is skipped.

🧾 Extra Data & Error Objects

All log methods accept data:

logger.error("DB", "Query failed", { query: "SELECT * FROM users" });

Error objects are automatically expanded:

try {
  bad();
} catch (err) {
  logger.critical("System", "Fatal crash", err);
}

Resulting file entry:

{
  "name": "ReferenceError",
  "message": "bad is not defined",
  "stack": "..."
}

📤 Exported Default (Singleton)

The module exports a ready-to-use singleton:

const logger = require("stoat-tracks");

Defaults:

• minLevel: "INFO"
• Console enabled
• File logging enabled
• Stoat logging disabled
• Stoat logs only ERROR+ unless configured

🧪 Full API

Logging methods

logger.debug(category, message, data)
logger.info(category, message, data)
logger.warn(category, message, data)
logger.error(category, message, data)
logger.critical(category, message, data)
logger.system(event, message, data) // wrapper for system events

Stoat controls

logger.setBot(bot)
logger.getBot()

logger.setLogChannel(serverId, channelId)

Internals (only if making custom instances)

logger.log(level, category, message, data)
logger.shouldLog(level, minLevel)
logger.rotateLogFile(path)

📝 License

MIT License Copyright © BrandonTheDev