Arc Log*

*This readme was AI generated

Arc Log is a lightweight, environment-aware logging and profiling library for Node.js.
It provides colorized console logs for development, structured logging for production, and simple profiling utilities with performance thresholds.

📦 Installation

npm install arc-logger

🧭 Overview

Arc Log adapts automatically to your environment:

• Development → Colorized and human-friendly console logs.
• Staging → Controlled logs with optional bypass list for debugging specific labels.
• Production → Structured logs for analysis and aggregation, with optional custom transport.

It also includes a profiling API for performance measurement and supports detailed error tracing with V8 stack inspection or regex fallback.

🚀 Quick Start

import Log from 'arc-log';

// Set up your logger
Log.setServiceName('my-service');
Log.setEnvironment('production');
Log.enableProductionLogging(true);

// Log to console or a custom destination
Log.setDestination('console');

// Log some events
Log.info('Server started', { port: 8080 });
Log.ops('User signup', { userId: 123 });
Log.warning('Cache miss rate high', { rate: 0.42 });
Log.error('Unexpected exception', { err });

// Error handling helper
try {
  throw new Error('Database connection failed');
} catch (err) {
  Log.catch(err, { traceId: 'TRACE-1' });
}

⚙️ Environment Configuration

| Environment | Logging Enabled | Profiling Enabled | Default Threshold | Notes | |---------------|----------------|------------------|-------------------|-------| | Development | ✅ Yes (colorized console) | ✅ | 0 (debug+) | Always prints to console | | Staging | ⚙️ Configurable | ⚙️ Configurable | 1 (info+) | Can bypass labels | | Production | ⚙️ Configurable | ⚙️ Configurable | 2 (ops+) | Ideal for structured logging |

Example (Custom Transport)

const customTransport = (service, record) => {
  // Send logs to remote collector
  console.log('Sending to collector:', service, record);
};

Log.setEnvironment('production');
Log.enableProductionLogging(true);
Log.setDestination('custom', customTransport);

Log.critical('Payment system offline', { status: 500 });

🧩 Profiling

Profile sections of your code and automatically log aggregate timings.

Log.setEnvironment('production');
Log.enableProductionLogging(true);
Log.enableProductionProfiling(true);
Log.setDestination('custom', myTransport);

const id = Log.profile('db-query', { query: 'SELECT * FROM users' }, { 
  profileThresholds: { critical: 1000, warning: 500, info: 200 },
  sendAggregate: 1
});

// Simulate work
await runQuery();

Log.profileEnd(id);

Behavior:
When profiling ends, Arc Log aggregates timings and logs with mapped severity levels depending on the configured thresholds.

🧱 Catching Errors

Log.catch() automatically extracts filename, line, and column using V8’s structured stack API when available, or a regex fallback otherwise.

try {
  throw new Error('Fatal: connection refused');
} catch (e) {
  Log.catch(e, { traceId: 'ABC-123' });
}

If the environment is production and logging is enabled, the structured record will be delivered to your destination.

🧰 Advanced Features

Instance Facades

const scoped = Log.instance({ traceId: 'REQ-123' });
scoped.info('Request handled');
scoped.ops('Cache updated', { cache: true });
scoped.catch(new Error('Worker timeout'));

Each instance applies the given config automatically (like traceId or threshold).

Bypass Lists

Log.addToProductionBypassList('debug-label');
Log.debug('debug-label', { extra: 'visible in prod now' });

Bypass lists allow certain labels to always log even if the current environment or threshold would normally filter them.

Development Output Options

Log.setSimpleOutput(true);  // One-line messages
Log.setOutputRaw(true);     // Print raw JSON or values directly

🧪 Testing

This module has a comprehensive Jest test suite covering:

• All environments (dev/staging/prod)
• Thresholds and bypass logic
• Profiling aggregation
• Error capture with V8 and regex fallback
• Console vs custom destinations

Run tests with:

npm test

📄 License

MIT License

This project is released under The Unlicense, placing it in the public domain.