API Reference

Complete API documentation for the node-syslog library.

Core Classes

Syslog

The main class for syslog functionality.

import { Syslog } from 'node-syslog'

const logger = new Syslog({
  ident: 'myapp',
  facility: 'local0',
  options: ['pid', 'odelay']
})

Constructor 

constructor(options: SyslogOptions)

Creates a new syslog instance with the specified options.

Parameters:

  • options - Configuration options for the syslog instance

Example:

const logger = new Syslog({
  ident: 'myapp',
  facility: SyslogFacility.LOCAL0,
  options: [SyslogOption.PID, SyslogOption.NDELAY],
  logLevel: SyslogLevel.INFO
})

Methods

emerg(message: string, context?: object): void

Log an emergency message.

logger.emerg('System is unusable!', { service: 'database' })
alert(message: string, context?: object): void

Log an alert message.

logger.alert('Immediate action required!', { threshold: '90%' })
crit(message: string, context?: object): void

Log a critical message.

logger.crit('Critical system failure', { component: 'auth' })
error(message: string, context?: object): void

Log an error message.

logger.error('Database connection failed', { 
  host: 'localhost',
  port: 5432,
  error: 'ECONNREFUSED'
})
warning(message: string, context?: object): void

Log a warning message.

logger.warning('High memory usage', { 
  usage: '85%',
  threshold: '80%'
})
notice(message: string, context?: object): void

Log a notice message.

logger.notice('Server configuration updated', { 
  config: 'nginx.conf',
  version: '1.20.2'
})
info(message: string, context?: object): void

Log an info message.

logger.info('User logged in successfully', { 
  userId: 12345,
  ip: '192.168.1.100'
})
debug(message: string, context?: object): void

Log a debug message.

logger.debug('Processing request', { 
  requestId: 'req_abc123',
  method: 'POST',
  url: '/api/users'
})
close(): void

Close the syslog connection and clean up resources.

logger.close()
isDebugEnabled(): boolean

Check if debug logging is enabled.

if (logger.isDebugEnabled()) {
  logger.debug('Expensive debug operation', { data: getLargeObject() })
}

Types and Constants

SyslogOptions

Configuration options for creating a Syslog instance.

interface SyslogOptions {
  ident: string                    // Required: Identifier for log messages
  facility?: SyslogFacilityType   // Optional: Syslog facility (default: 'user')
  options?: SyslogOptionType[]     // Optional: Syslog options (default: [])
  logLevel?: SyslogLevelType       // Optional: Minimum log level (default: 'info')
}

SyslogFacility

Syslog facility constants.

const SyslogFacility = {
  KERN: 0,         // Kernel messages
  USER: 1,         // User-level messages (default)
  MAIL: 2,         // Mail system
  DAEMON: 3,       // System daemons
  AUTH: 4,         // Security/authorization
  SYSLOG: 5,       // Internal syslog messages
  LPR: 6,          // Line printer subsystem
  NEWS: 7,         // Network news subsystem
  UUCP: 8,         // UUCP subsystem
  CRON: 9,         // Clock daemon
  AUTHPRIV: 10,    // Security/authorization (private)
  FTP: 11,         // FTP daemon
  LOCAL0: 16,      // Local use 0
  LOCAL1: 17,      // Local use 1
  LOCAL2: 18,      // Local use 2
  LOCAL3: 19,      // Local use 3
  LOCAL4: 20,      // Local use 4
  LOCAL5: 21,      // Local use 5
  LOCAL6: 22,      // Local use 6
  LOCAL7: 23       // Local use 7
} as const

SyslogLevel

Log level constants.

const SyslogLevel = {
  EMERG: 0,        // Emergency: system is unusable
  ALERT: 1,        // Alert: action must be taken immediately
  CRIT: 2,         // Critical: critical conditions
  ERR: 3,          // Error: error conditions
  WARNING: 4,      // Warning: warning conditions
  NOTICE: 5,       // Notice: normal but significant condition
  INFO: 6,         // Informational: informational messages
  DEBUG: 7         // Debug: debug-level messages
} as const

SyslogOption

Syslog option constants.

const SyslogOption = {
  PID: 0x01,       // Log the process ID with each message
  CONS: 0x02,      // Write to console if there's an error sending to syslog
  ODELAY: 0x04,    // Delay connection until first message is logged
  NDELAY: 0x08,    // Connect immediately
  NOWAIT: 0x10,    // Don't wait for child processes that log messages
  PERROR: 0x20     // Log to stderr as well
} as const

Convenience Functions

For quick logging without creating an instance:

import { info, error, warning, debug } from 'node-syslog'

// Uses default configuration
info('Application started')
error('Something went wrong')
warning('Warning message')
debug('Debug information')

Error Handling

The library throws descriptive errors for common issues:

import { SyslogError } from 'node-syslog'

try {
  const logger = new Syslog({
    ident: 'myapp',
    facility: 'invalid' as any  // This will throw
  })
} catch (error) {
  if (error instanceof SyslogError) {
    console.error('Syslog configuration error:', error.message)
  }
}

Common Errors

  • SyslogError: Invalid facility: invalid - Invalid facility name
  • SyslogError: Invalid option: invalid - Invalid option name
  • SyslogError: Invalid log level: invalid - Invalid log level name
  • SyslogError: ident is required - Missing ident parameter

Performance Considerations

Memory Usage

The library is designed for minimal memory usage:

  • Zero allocations in the hot logging path
  • Static buffers for message formatting
  • Efficient string concatenation

CPU Performance

Typical performance characteristics:

  • Latency: < 1μs overhead vs raw syslog(3)
  • Throughput: > 500,000 messages/second
  • Event Loop Impact: < 0.01% at 10,000 logs/second

Best Practices

  1. Reuse logger instances - Avoid creating new instances for each log message
  2. Check log levels - Use isDebugEnabled() to skip expensive operations
  3. Batch context - Include relevant context in a single log call
  4. Avoid string concatenation - Let the library handle message formatting
// Good - reuse instance
const logger = new Syslog({ ident: 'myapp' })

// Good - check debug level
if (logger.isDebugEnabled()) {
  logger.debug('Expensive operation', { data: expensiveComputation() })
}

// Good - structured context
logger.error('Request failed', {
  url: req.url,
  method: req.method,
  statusCode: res.statusCode,
  duration: Date.now() - startTime
})

// Avoid - creating instances repeatedly
for (const item of items) {
  const logger = new Syslog({ ident: 'loop' })  // Bad!
  logger.info('Processing item')
}