log-mate
Version:
log-mate makes logging effortless & powerful—log to console, files, databases, or cloud with structured logs, encryption, real-time streaming, and auto-rotation. It’s plug & play, supports multi-transport logging, and boosts performance with async, lazy l
249 lines (196 loc) • 8.5 kB
Markdown
# log-mate
**A flexible and powerful logging library for Node.js**
log-mate makes logging effortless & powerful—log to console, files, databases, or cloud with structured logs, encryption, real-time streaming, and auto-rotation. It’s plug & play, supports multi-transport logging, and boosts performance with async, lazy logging, and batching. Plus, it keeps your data secure with masking & encryption—perfect for everything from debugging to production!
[](https://www.npmjs.com/package/log-mate) [](LICENSE)
## **📖 Overview**
**log-mate** is a lightweight yet feature-rich logging library for Node.js applications. It provides structured logging, multiple log levels, customizable transports (console, file, database, cloud), log rotation, contextual logging, encryption, and real-time log streaming.
✅ **Highly configurable** – Customize output formats, storage, and integrations.
✅ **Multi-transport support** – Log to console, files, databases, cloud, or webhooks.
✅ **Structured logging** – Supports JSON and other formats.
✅ **Contextual logging** – Add metadata, user IDs, and request contexts.
✅ **Optimized for performance** – Lazy evaluation, batching, and async logging.
✅ **Secure logging** – Mask sensitive data and encrypt logs.
## **📦 Installation**
Install **log-mate** via npm:
```sh
npm install log-mate
```
or via yarn:
```sh
yarn add log-mate
```
## **🚀 Usage**
### **Basic Example**
```javascript
const logme = require('log-mate');
logme.trace("This is a trace message");
logme.debug("Debugging details here");
logme.info("Informational message");
logme.warn("This is a warning!");
logme.error("Something went wrong!", { code: 500, details: "Internal Server Error" });
logme.fatal("Critical failure! Shutting down...");
logme.custom("info", "User logged in");
```
### **Logging to a File**
```javascript
logme.toFile("logs/app.log", { rotation: true });
logme.info("This will be logged to a file.");
```
### **Logging to a Database**
```javascript
logme.toDatabase({
host: "localhost",
user: "root",
password: "password",
database: "logs",
});
logme.info("This message will be stored in the database");
```
### **Logging to Cloud (AWS, GCP, Azure)**
```js
logme.toCloud("aws", { bucket: "my-log-bucket" });
logme.error("Logging error to the cloud");
```
### **Masking Sensitive Data**
```js
logme.maskSensitive(["password", "token"]);
logme.info("User logged in with password: 123456 and token: abcdefg");
// OUTPUT: [INFO] User logged in with password: ****** and token: ******
```
### **Streaming Logs in Real-Time**
```javascript
logme.enableStreaming(3000); // Streams logs over WebSocket at port 3000
logme.info("Streaming logs in real-time...");
```
### **Encrypted Logging**
```js
logme.encrypt("my-secret-key");
logme.info("This log is now encrypted!");
```
### **Batch Logging**
```js
logme.setBatchSize(5);
logme.info("Log message 1");
logme.info("Log message 2");
logme.flush(); // Manually flush logs before batch size is reached
```
### **Log Rotation**
```js
logme.enableRotation({ maxSize: 1024 * 1024, maxFiles: 3 }); // Rotate at 1MB, keep 3 files
logme.info("This log will be rotated when it reaches max size");
```
### **Contextual Logging**
```js
logme.setContext({ userId: "1234", sessionId: "abcd" });
logme.info("User performed an action");
// OUTPUT: [INFO] [userId:1234] [sessionId:abcd] User performed an action
```
### **Namespace (Scoped) Logging**
```js
const authLogger = logme.get("auth");
authLogger("INFO", "User logged in");
// Output: [auth] [INFO] User logged in
```
### **Using Plugins**
```js
logme.use((message) => console.log(`[PLUGIN] ${message}`));
logme.info("This log passes through a plugin");
```
### **CLI Usage**
```sh
node index.js view logs.txt # View log file
node index.js clear logs.txt # Clear log file
```
## **📜 API Reference**
### **1️⃣ Core Logging Functions**
| **Function** | **Description** |
|------------------------------|----------------|
| `logme.trace(message, ...args)` | Logs a trace message (detailed debugging). |
| `logme.debug(message, ...args)` | Logs a debug message. |
| `logme.info(message, ...args)` | Logs an informational message. |
| `logme.notice(message, ...args)` | Logs a notice message. |
| `logme.warn(message, ...args)` | Logs a warning message. |
| `logme.error(message, ...args)` | Logs an error message. |
| `logme.fatal(message, ...args)` | Logs a fatal error message. |
| `logme.custom(level, message, ...args)` | Logs with a custom log level. |
### **2️⃣ Log Output & Transport**
| **Function** | **Description** |
|------------------------------------|----------------|
| `logme.toConsole(enable = true)` | Enables/disables console logging. |
| `logme.toFile(filepath, options)` | Logs messages to a file. |
| `logme.toDatabase(dbConfig)` | Logs messages to a database. |
| `logme.toCloud(service, options)` | Sends logs to AWS, GCP, Azure, etc. |
| `logme.toWebhook(url, options)` | Sends logs to a webhook URL. |
### **3️⃣ Formatting & Encryption**
| **Function** | **Description** |
|------------------------------------|----------------|
| `logme.setFormat(type)` | Sets log format (`json`, `yaml`, `text`). |
| `logme.maskSensitive(keys)` | Masks sensitive data (e.g., passwords). |
| `logme.encrypt(key)` | Encrypts logs using AES-256. |
### **4️⃣ Log Rotation & Performance**
| **Function** | **Description** |
|------------------------------------|----------------|
| `logme.enableRotation(options)` | Enables automatic log rotation. |
| `logme.setBatchSize(size)` | Sets batch size for buffered logging. |
| `logme.flush()` | Flushes all batched logs immediately. |
### **5️⃣ Namespacing & Contextual Logging**
| **Function** | **Description** |
|-----------------------------------|----------------|
| `logme.get(namespace)` | Creates a namespaced logger (`log.get("auth")`). |
| `logme.setContext(contextObject)` | Adds metadata/context to logs. |
### **6️⃣ Advanced Features**
| **Function** | **Description** |
|------------------------------------|----------------|
| `logme.enableStreaming(port)` | Streams logs in real-time via WebSocket. |
| `logme.lazy(() => message)` | Lazy logging (evaluates message only if needed). |
| `logme.retry(attempts, delay)` | Retries failed log writes automatically. |
### **7️⃣ CLI & Plugins**
| **Function** | **Description** |
|-----------------------------------|----------------|
| `logme.use(plugin)` | Loads a plugin (e.g., Slack, Sentry). |
| `logme.cli()` | Provides CLI commands (`log-mate view`, `log-mate clear`). |
## **🛠 Configuration Example**
```javascript
const logme = require("log-mate");
logme.setConfig({
level: "debug",
format: "json",
transports: [
{ type: "console" },
{ type: "file", path: "logs/app.log" }
],
maskSensitive: ["password", "email"],
encrypt: true
});
console.log(logme.getConfig()); // Check updated config
```
## **📌 Features Comparison**
| Feature | log-mate | Other Loggers |
|------------------------|----------|--------------|
| Log Levels | ✅ Yes | ✅ Yes |
| File Logging | ✅ Yes | ✅ Yes |
| Database Logging | ✅ Yes | ❌ No |
| Cloud Integration | ✅ Yes | ❌ No |
| Real-time Streaming | ✅ Yes | ❌ No |
| Log Encryption | ✅ Yes | ❌ No |
| Lazy Logging | ✅ Yes | ❌ No |
| Custom Log Levels | ✅ Yes | ✅ Yes |
## **🤝 Contributing**
Contributions are welcome! If you have suggestions or want to add features:
1. Fork the repo
2. Create a new branch (`feature-name`)
3. Commit your changes
4. Submit a Pull Request