ConsoleIQ

Enhanced console logging with remote capabilities for any JavaScript environment.

ConsoleIQ is a powerful, lightweight logging library that enhances the standard JavaScript console with features like remote logging, automatic error capturing, output colorization, and sensitive data masking. It's designed to be a drop-in replacement for the standard console, providing a consistent and feature-rich logging experience in both browser and Node.js environments.

Core Features

• 🌐 Universal Compatibility: Works seamlessly in browsers, Node.js, and other JavaScript runtimes.
• ☁️ Remote Logging: Send logs to any HTTP endpoint with fine-grained control over log levels.
• 🛡️ Automatic Error Handling: Captures uncaught exceptions and unhandled promise rejections, providing rich contextual information.
• 🎨 Colorized Output: Improves readability in development with customizable, color-coded log levels.
• 🎭 Data Masking: Automatically masks sensitive data like passwords, API keys, and tokens from your logs.
• 📦 Log Batching: Reduces network traffic by batching logs before sending them to a remote server.
• 💾 Offline Caching: Caches logs when offline and automatically sends them when connectivity is restored.
• 🪶 Lightweight & Zero-dep: Minimal footprint with axios as its only dependency for remote logging.

Installation

npm install consoleiq

Quick Start

const { createConsoleIQ } = require('consoleiq');

// Initialize with default options
const consoleIQ = createConsoleIQ().init();

// Use the console as you normally would
console.log('This is a standard log message.');
console.info('This is an informational message.');
console.warn('This is a warning.');
console.error(new Error('This is an error.'));

// Use the custom .text() method for remote logging
console.text('This log will be sent to your remote endpoint.');

// When your application is shutting down, restore the original console
consoleIQ.restore();

Configuration

ConsoleIQ is highly configurable. You can pass a configuration object to createConsoleIQ to tailor its behavior to your needs.

const { createConsoleIQ } = require('consoleiq');

const config = {
  // Remote Logging
  endpoint: 'https://api.your-log-service.com/logs',
  apiKey: 'your-secret-api-key',
  allowedLevels: ['error', 'warn', 'text'],

  // Log Batching & Caching
  batchSize: 20,
  batchInterval: 10000, // 10 seconds
  offlineCaching: true,

  // Data Masking
  sensitiveKeys: ['password', 'token', 'apiKey'],

  // Local Console Behavior
  colorize: true,
  silent: false,
  name: 'MyAppLogger',

  // Error Capturing
  captureGlobalErrors: true,
  captureUnhandledRejections: true,
  autoTraceErrors: true,
  enhanceErrors: true,
};

const consoleIQ = createConsoleIQ(config).init();

All Configuration Options

| Option | Type | Default | Description | |---|---|---|---| | endpoint | string | "" | The URL of your remote logging endpoint. | | apiKey | string | null | An API key to be sent as a Bearer token in the Authorization header. | | allowedLevels | Array<string> | ["error", "text"] | The log levels that should be sent to the remote endpoint. | | batchSize | number | 10 | The number of logs to queue before sending them as a batch. | | batchInterval | number | 5000 | The maximum time (in ms) to wait before sending a batch, even if batchSize is not reached. | | offlineCaching | boolean | true | If true, logs will be cached locally (localStorage/file) if the endpoint is unreachable and sent later. | | sensitiveKeys | Array<string> | [] | An array of object keys whose values should be masked (replaced with ***). | | colorize | boolean | true | Whether to apply colors to the local console output. | | silent | boolean | false | If true, all local console output from ConsoleIQ will be suppressed. | | name | string | "ConsoleIQ" | A name for the logger instance, included in remote log metadata. | | captureGlobalErrors | boolean | true | If true, captures window.onerror and process.on('uncaughtException'). | | captureUnhandledRejections | boolean | true | If true, captures unhandled promise rejections. | | captureConsoleErrors | boolean | true | If true, automatically captures calls to console.error. | | autoTraceErrors | boolean | true | If true, automatically adds stack traces to error logs. | | enhanceErrors | boolean | true | If true, error objects are enhanced with additional context (environment, URL, etc.). | | maxErrorDepth | number | 5 | The maximum depth for serializing error objects to prevent infinite recursion. | | environment | string | auto-detected | Manually specify the environment ('browser' or 'node'). |

Advanced Features

Sensitive Data Masking

Protect sensitive information by specifying keys to mask. Any value associated with these keys in logged objects will be replaced with ***.

const consoleIQ = createConsoleIQ({
  sensitiveKeys: ['password', 'token', 'apiKey']
}).init();

console.log({
  user: 'test-user',
  password: 'my-secret-password', // Will be logged as '***'
  data: {
    token: 'another-secret' // Will also be masked
  }
});

Log Batching and Offline Caching

For applications that generate a high volume of logs, batching can significantly reduce network overhead. If your application might run in environments with intermittent connectivity, offline caching ensures that no logs are lost.

const consoleIQ = createConsoleIQ({
  endpoint: '...',
  batchSize: 50,        // Send logs in batches of 50
  batchInterval: 15000, // Or every 15 seconds
  offlineCaching: true, // Enable offline caching
}).init();

Automatic Error Capturing

ConsoleIQ automatically captures uncaught errors and enhances them with valuable context, such as the user's browser, the page URL, and Node.js process information. This provides a more complete picture for debugging.

// Example of an enhanced error object sent to your remote endpoint
{
  "level": "error",
  "message": "Error: Something went wrong",
  "timestamp": "2025-01-01T12:00:00.000Z",
  "name": "MyAppLogger",
  "environment": "browser",
  "metadata": {
    "type": "browser",
    "url": "https://example.com/my-app",
    "userAgent": "Mozilla/5.0...",
    "platform": "Win32"
  },
  "stack": "Error: Something went wrong\n    at ..."
}

Setting Up a Custom Log Receiver

You can easily create your own API endpoint to receive and process logs from ConsoleIQ. Here’s a basic example using Node.js and Express:

1. Install Dependencies

npm install express body-parser

2. Create the Server

// server.js
const express = require('express');
const bodyParser = require('body-parser');

const app = express();
const port = 4000;

app.use(bodyParser.json());

app.post('/logs', (req, res) => {
  const logs = req.body; // An array of log objects

  // Optional: Validate an API key
  const apiKey = req.headers['authorization'];
  if (apiKey !== 'Bearer your-secret-api-key') {
    return res.status(401).send('Unauthorized');
  }

  console.log('Received logs:', JSON.stringify(logs, null, 2));
  
  // Process the logs: save to a database, forward to another service, etc.

  res.status(200).send('Logs received');
});

app.listen(port, () => {
  console.log(`Log receiver listening at http://localhost:${port}`);
});

3. Run the Server

node server.js

4. Configure ConsoleIQ

Point ConsoleIQ to your new endpoint in your client-side or server-side application:

const consoleIQ = createConsoleIQ({
  endpoint: 'http://localhost:4000/logs',
  apiKey: 'your-secret-api-key',
}).init();

console.text('This log will be sent to your custom API.');

License

MIT © 2025 ConsoleIQ

Links

• GitHub Repository
• Issues