@logscout/node

Official Node.js client for LogScout - Modern log management platform.

Installation

npm install @logscout/node
# or
yarn add @logscout/node
# or
pnpm add @logscout/node

Quick Start

import { LogScout } from '@logscout/node';

const logger = new LogScout({
  apiKey: 'your-api-key',
});

// Log messages at different levels
await logger.info('Application started');
await logger.debug('Processing request', { metadata: { requestId: '123' } });
await logger.warn('High memory usage detected');
await logger.error('Failed to connect to database', { 
  source: 'database',
  metadata: { host: 'localhost', port: 5432 } 
});
await logger.fatal('Unrecoverable error, shutting down');

Configuration

import { LogScout } from '@logscout/node';

const logger = new LogScout({
  // Required
  apiKey: 'your-api-key',
  
  // Optional
  dev: false,              // Use development API (api.dev.logscout.dev)
  defaultSource: 'app',    // Default source for all logs
  defaultMetadata: {       // Default metadata included with all logs
    environment: 'production',
    version: '1.0.0',
  },
  timeout: 10000,          // Request timeout in ms
  retry: true,             // Retry failed requests
  maxRetries: 3,           // Maximum retry attempts
});

API Reference

Log Levels

• DEBUG - Detailed debug information
• INFO - Interesting events
• WARN - Exceptional occurrences that are not errors
• ERROR - Runtime errors
• FATAL - Critical errors causing shutdown

Methods

log(level, message, options?)

Send a log entry with a specific level.

await logger.log('ERROR', 'Something went wrong', {
  source: 'api',
  metadata: { userId: 123 },
});

debug(message, options?)

info(message, options?)

warn(message, options?)

error(message, options?)

fatal(message, options?)

Convenience methods for each log level.

await logger.error('Connection failed', {
  source: 'database',
  metadata: { error: err.message },
});

Options

interface LogOptions {
  source?: string;                    // Override default source
  metadata?: Record<string, unknown>; // Additional metadata
}

Response

All logging methods return a LogResponse:

interface LogResponse {
  success: boolean;
  id?: string;      // Log entry ID on success
  error?: string;   // Error message on failure
}

Development Mode

Use the dev flag to send logs to the development API:

const logger = new LogScout({
  apiKey: 'your-dev-api-key',
  dev: true, // Sends to api.dev.logscout.dev
});

Factory Function

You can also use the factory function:

import { createLogScout } from '@logscout/node';

const logger = createLogScout({
  apiKey: 'your-api-key',
});

TypeScript Support

This package includes TypeScript definitions. All types are exported:

import type { 
  LogLevel, 
  LogScoutConfig, 
  LogPayload, 
  LogOptions, 
  LogResponse 
} from '@logscout/node';

Error Handling

The client handles errors gracefully and returns them in the response:

const result = await logger.error('Something failed');

if (!result.success) {
  console.error('Failed to send log:', result.error);
}

Retry Logic

By default, failed requests are retried with exponential backoff:

• Attempt 1: Immediate
• Attempt 2: After 1 second
• Attempt 3: After 2 seconds

Disable retries:

const logger = new LogScout({
  apiKey: 'your-api-key',
  retry: false,
});

License

MIT