Core Logging API

/**
 * Configure the global logger instance
 * @param tag - Tag prefix for all log events
 * @param options - Configuration options for the logger
 */
function configure(tag, options);

const logger = require('fluent-logger');

// Basic configuration
logger.configure('myapp', {
  host: 'localhost',
  port: 24224
});

// Configuration with advanced options
logger.configure('production', {
  host: 'log-server.example.com',
  port: 24224,
  timeout: 5.0,
  reconnectInterval: 300000, // 5 minutes
  enableReconnect: true
});

/**
 * Create a new FluentSender instance
 * @param tag - Tag prefix for log events from this sender
 * @param options - Configuration options for this sender
 * @returns FluentSender instance
 */
function createFluentSender(tag, options);

const logger = require('fluent-logger');

// Create sender for application logs
const appLogger = logger.createFluentSender('app', {
  host: 'app-logs.example.com',
  port: 24224
});

// Create sender for metrics
const metricsLogger = logger.createFluentSender('metrics', {
  host: 'metrics-server.example.com', 
  port: 24225,
  eventMode: 'PackedForward'
});

// Use different senders for different purposes
appLogger.emit('user_action', { action: 'login', user_id: 123 });
metricsLogger.emit('response_time', { endpoint: '/api/users', ms: 42 });

/**
 * Send a log event using the singleton logger
 * @param label - Event label (optional, appended to configured tag)
 * @param data - Log data object (required)
 * @param timestamp - Event timestamp (optional, defaults to current time)
 * @param callback - Completion callback (optional)
 */
function emit(label, data, timestamp?, callback?);

// Alternative signatures:
function emit(data, timestamp?, callback?);
function emit(data, callback?);

const logger = require('fluent-logger');
logger.configure('myapp');

// Basic event emission
logger.emit('access', {
  path: '/api/users',
  method: 'GET', 
  status: 200
});

// Event without label (uses only configured tag)
logger.emit({
  level: 'error',
  message: 'Database connection failed',
  error_code: 'DB_CONN_ERR'
});

// Event with custom timestamp
const customTime = new Date('2023-01-01T00:00:00Z');
logger.emit('scheduled_task', {
  task: 'backup',
  status: 'completed'
}, customTime);

// Event with callback
logger.emit('critical', {
  message: 'System overload detected'
}, (error) => {
  if (error) {
    console.error('Failed to send log:', error);
  } else {
    console.log('Critical alert sent successfully');
  }
});

/**
 * Send a log event using a FluentSender instance
 * @param label - Event label (optional, appended to sender's tag)
 * @param data - Log data object (required)
 * @param timestamp - Event timestamp (optional)
 * @param callback - Completion callback (optional)
 */
FluentSender.prototype.emit(label, data, timestamp?, callback?);

const sender = logger.createFluentSender('api');

// Instance-based event emission
sender.emit('request', {
  endpoint: '/users/123',
  method: 'GET',
  response_time: 45,
  status_code: 200
});

// With error handling
sender.emit('error', {
  message: 'Authentication failed',
  user_id: 456
}, (error) => {
  if (error) {
    console.error('Log emission failed:', error);
  }
});

/**
 * Close connection with optional final log event (singleton)
 * @param label - Final event label (optional)
 * @param data - Final event data (optional)  
 * @param callback - Completion callback (optional)
 */
function end(label?, data?, callback?);

/**
 * Close connection with optional final log event (instance)
 * @param label - Final event label (optional)
 * @param data - Final event data (optional)
 * @param callback - Completion callback (optional)
 */
FluentSender.prototype.end(label?, data?, callback?);

// Graceful shutdown with final event
logger.end('shutdown', {
  reason: 'application_exit',
  uptime: process.uptime()
}, () => {
  console.log('Logger closed successfully');
  process.exit(0);
});

// Simple shutdown
logger.end(() => {
  console.log('Logger closed');
});

// Instance shutdown
sender.end('instance_shutdown', { sender_id: 'api-logger' });

interface BasicOptions {
  host?: string;                    // Fluentd hostname (default: 'localhost')
  port?: number;                    // Fluentd port (default: 24224)  
  path?: string;                    // Unix domain socket path (overrides host/port)
  timeout?: number;                 // Socket timeout in seconds (default: 3.0)
  enableReconnect?: boolean;        // Enable automatic reconnection (default: true)
  reconnectInterval?: number;       // Reconnect interval in ms (default: 600000)
}

// ✅ Valid log data
logger.emit('event', { message: 'Hello', count: 42, active: true });
logger.emit('user', { id: 123, name: 'Alice', email: 'alice@example.com' });

// ❌ Invalid log data (will throw DataTypeError)
logger.emit('event', 'just a string'); 
logger.emit('event', 42);
logger.emit('event', true);