Node Logger Simple

Official Node.js client for Logger Simple - A complete logging solution with error tracking, performance monitoring, and real-time analytics.

🚀 Features

• Easy Integration: Get up and running in minutes with minimal configuration
• Real-time Logging: Send logs directly to Logger Simple dashboard
• Error Tracking: Automatic error capture with stack traces and context
• Performance Monitoring: Built-in operation timing and performance metrics
• Rate Limiting: Client-side rate limiting to prevent API spam
• Auto-Shutdown: Configurable automatic shutdown on critical errors
• Context-Aware Logging: Structured logging with contextual information
• TypeScript Support: Full TypeScript definitions included
• Health Monitoring: Comprehensive health checks and diagnostics
• Category Validation: Ensures application category matches Node.js

📋 Requirements

• Node.js: 14.0.0 or higher
• Application Category: Must be set to "nodejs" in Logger Simple dashboard
• Valid Credentials: Application ID and API Key from Logger Simple

📦 Installation

npm install node-logger-simple

🏁 Quick Start

1. Create Your Application

First, create a Node.js application in the Logger Simple Dashboard:

1. Go to Dashboard → Applications → Create New Application
2. Set Programming Language to "Node.js"
3. Configure your application settings
4. Copy your App ID and API Key

2. Basic Usage

const createLogger = require('node-logger-simple');

// Initialize logger
const logger = createLogger({
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  debug: true
});

// Basic logging
await logger.info('Application started successfully');
await logger.warn('This is a warning message');
await logger.error('Something went wrong', { 
  userId: 12345, 
  action: 'user_login' 
});

// Critical errors (will exit app by default)
await logger.critical('Database connection failed', {
  error: 'Connection timeout',
  database: 'primary'
});

3. Advanced Usage

const logger = createLogger({
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  debug: true,
  maxLogsPerHour: 2000,
  exitOnCritical: true
});

// Context-aware logging
const userLogger = logger.context('UserService');
await userLogger.info('User login attempt', {
  userId: 12345,
  ip: '192.168.1.1',
  userAgent: 'Mozilla/5.0...'
});

// Performance monitoring
const result = await logger.timeOperation(async () => {
  // Your expensive operation here
  return await processLargeDataset();
}, 'DataProcessing');

// Structured logging with tags and metadata
await logger.error('Payment failed', 
  { orderId: 'ORDER-123', amount: 99.99 }, // context
  'Payment processing error details...', // content
  ['payment', 'error', 'critical'], // tags
  { retryCount: 3, gateway: 'stripe' } // metadata
);

🔧 Configuration

LoggerConfig Options

const logger = createLogger({
  // Required
  appId: 'your-app-id',              // Your application ID
  apiKey: 'your-api-key',            // Your API key
  
  // Optional
  baseUrl: 'https://api.logger-simple.com',  // API base URL
  timeout: 10000,                    // Request timeout (ms)
  retries: 3,                        // Retry attempts
  debug: false,                      // Enable debug logging
  exitOnCritical: true,              // Exit on critical errors
  maxLogsPerHour: 1000,             // Rate limit
  enableRateLimiting: true,          // Enable rate limiting
  userAgent: 'custom-agent/1.0',    // Custom user agent
  enableGlobalErrorHandling: true,   // Global error handlers
  exitOnAuthError: true              // Exit on auth failures
});

📝 Logging Methods

Basic Logging

// Different log levels
await logger.success('Operation completed successfully');
await logger.info('Information message');
await logger.warn('Warning message');
await logger.error('Error message');
await logger.critical('Critical error - app will exit');

// Generic log method
await logger.log('info', 'Custom message', context, content, false, tags, metadata);

Context-Aware Logging

// Create context loggers
const dbLogger = logger.context('Database');
const apiLogger = logger.context('API');

// All logs will include context automatically
await dbLogger.error('Connection failed');
// Logs as: "Connection failed" with context: { context: "Database" }

// Nested contexts
const userDbLogger = dbLogger.subContext('Users');
await userDbLogger.info('User created');
// Context: { context: "Database::Users" }

Performance Monitoring

// Monitor operation performance
const result = await logger.timeOperation(async () => {
  const data = await fetchUserData();
  return processData(data);
}, 'UserDataProcessing');

// With custom log level
await logger.timeOperation(
  () => criticalOperation(),
  'CriticalOperation',
  'error' // Log as error level
);

🛡️ Error Handling

The logger automatically handles various error scenarios:

Critical Error Management

// Critical errors trigger app shutdown by default
try {
  await logger.critical('System failure');
} catch (error) {
  // App will exit after logging
}

// Prevent shutdown for specific critical logs
await logger.critical('Important but non-fatal error', null, null, false);

Global Error Handling

// The logger automatically catches unhandled errors
process.on('uncaughtException', (error) => {
  // Automatically logged and handled
});

process.on('unhandledRejection', (reason) => {
  // Automatically logged and handled
});

Graceful Shutdown

// Graceful shutdown with logging
await logger.gracefulShutdown('Maintenance mode', 0);

// Force exit with critical error
await logger.forceExit('Emergency shutdown', {
  reason: 'Memory limit exceeded',
  memoryUsage: process.memoryUsage()
});

📊 Monitoring & Analytics

Health Checks

// Comprehensive health check
const health = await logger.healthCheck();
console.log(health);
/*
{
  timestamp: "2024-01-15T10:30:00.000Z",
  api_connection: true,
  app_authenticated: true,
  app_category_valid: true,
  response_time: 156,
  client_stats: { ... },
  rate_limiter: { ... },
  error_handler: { ... }
}
*/

Statistics

// Client-side statistics
const stats = logger.getClientStats();
console.log(stats);
/*
{
  totalLogs: 1523,
  successfulLogs: 1495,
  failedLogs: 28,
  rateLimitedLogs: 5,
  success_rate: 98,
  avg_logs_per_minute: 12.5,
  uptime_human: "2h 15m 30s"
}
*/

// Server-side log statistics
const logStats = await logger.getLogStats(30); // Last 30 days
console.log(logStats.data);

Rate Limiting

// Check rate limit status
const rateLimiter = logger.rateLimiter;
const status = rateLimiter.getStatus();

console.log(`Rate limit: ${status.currentHourRequests}/${status.maxRequestsPerHour}`);
console.log(`Available tokens: ${status.availableTokens}`);
console.log(`Utilization: ${status.utilizationPercent}%`);

// Get timing recommendations for bulk operations
const timing = rateLimiter.calculateOptimalTiming(100);
if (!timing.canProceed) {
  console.log(`Recommendation: ${timing.recommendation}`);
}

🎯 Advanced Features

Data Retrieval

// Get recent logs
const logs = await logger.getLogs({
  level: 'error',
  limit: 50,
  search: 'payment failed'
});

// Get log statistics
const stats = await logger.getLogStats(7); // Last 7 days

Default Context

// Set default context for all logs
logger.setDefaultContext({
  version: '1.0.0',
  environment: 'production',
  server: 'web-01'
});

// All subsequent logs will include this context
await logger.info('User action'); 
// Includes: { version: '1.0.0', environment: 'production', server: 'web-01' }

Custom Configuration

// Update configuration at runtime
logger.updateConfig({
  debug: true,
  maxLogsPerHour: 2000
});

// Get current configuration
const config = logger.getConfig();
console.log(config);

🚨 Error Types

The logger provides specific error types for better error handling:

const { 
  LoggerError, 
  ValidationError, 
  NetworkError, 
  RateLimitError,
  ApplicationError,
  AuthenticationError 
} = require('node-logger-simple');

try {
  await logger.info('test');
} catch (error) {
  if (error instanceof ValidationError) {
    console.log('Validation failed:', error.field, error.value);
  } else if (error instanceof NetworkError) {
    console.log('Network error:', error.statusCode);
  } else if (error instanceof RateLimitError) {
    console.log('Rate limited. Reset at:', error.resetTime);
  }
}

🔍 Debugging

Enable debug mode to see detailed logging information:

const logger = createLogger({
  appId: 'your-app-id',
  apiKey: 'your-api-key',
  debug: true  // Enable debug output
});

// Debug output will show:
// [2024-01-15T10:30:00.000Z] [Logger-Simple] [INFO] Logger instance created successfully
// [2024-01-15T10:30:01.000Z] [Logger-Simple] [INFO] API Request: GET /api.php
// [2024-01-15T10:30:01.000Z] [Logger-Simple] [INFO] Log sent successfully: INFO - User login...

🧪 Testing

The logger is designed to be testable and includes utilities for testing:

// Disable automatic shutdown for testing
const logger = createLogger({
  appId: 'test-app-id',
  apiKey: 'test-api-key',
  exitOnCritical: false,
  enableGlobalErrorHandling: false
});

// Mock API responses for testing
// (See test examples in /examples/testing.js)

🌐 Environment Variables

You can configure the logger using environment variables:

# .env file
LOGGER_SIMPLE_APP_ID=your-app-id
LOGGER_SIMPLE_API_KEY=your-api-key
LOGGER_SIMPLE_DEBUG=true
LOGGER_SIMPLE_MAX_LOGS_PER_HOUR=2000

const logger = createLogger({
  appId: process.env.LOGGER_SIMPLE_APP_ID,
  apiKey: process.env.LOGGER_SIMPLE_API_KEY,
  debug: process.env.LOGGER_SIMPLE_DEBUG === 'true',
  maxLogsPerHour: parseInt(process.env.LOGGER_SIMPLE_MAX_LOGS_PER_HOUR) || 1000
});

📁 Examples

Check out the /examples directory for complete usage examples:

• Basic Usage
• Express.js Integration
• Error Handling
• Performance Monitoring
• Testing Setup

🆘 Troubleshooting

Common Issues

1. "Application category mismatch"

   • Ensure your application is set to "Node.js" in the dashboard
   • Check that you're using the correct App ID

2. "Rate limit exceeded"

   • Reduce log frequency or increase maxLogsPerHour
   • Check rate limit status with rateLimiter.getStatus()

3. "Authentication failed"

   • Verify your API key is correct and active
   • Ensure the application is active in the dashboard

4. Network errors

   • Check internet connectivity
   • Verify the API URL is accessible
   • Check firewall settings

Debug Information

// Get comprehensive debug information
const health = await logger.healthCheck();
const stats = logger.getClientStats();
const config = logger.getConfig();

console.log('Health:', health);
console.log('Stats:', stats);
console.log('Config:', config);

🤝 Support

• Documentation: https://logger-simple.com/docs
• Discord Community: https://discord.gg/26HvypuvxR
• Email Support: [email protected]
• GitHub Issues: Report bugs and request features

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.

📊 Changelog

See CHANGELOG.md for a detailed list of changes and version history.

---

Made with ❤️ by the Logger Simple Team

Website • Dashboard • Documentation