CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-fluent-logger

A structured logger for Fluentd (Node.js implementation)

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

winston-integration.mddocs/

Winston Integration

Winston transport integration for using Fluent Logger as a Winston logging destination with full Winston v3+ compatibility.

Capabilities

Winston Transport Factory

Get the FluentTransport class for Winston integration.

/**
 * Get the FluentTransport class for Winston integration
 * @returns FluentTransport class constructor
 */
function support.winstonTransport();

Usage Examples:

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

// Get the transport class
const FluentTransport = logger.support.winstonTransport();

// Create Winston logger with Fluent transport
const winstonLogger = winston.createLogger({
  transports: [
    new FluentTransport('winston', {
      host: 'localhost',
      port: 24224,
      timeout: 3.0,
      requireAckResponse: true
    }),
    new winston.transports.Console()
  ]
});

// Use Winston logger normally
winstonLogger.info('Application started', { version: '1.0.0' });
winstonLogger.error('Database connection failed', { error: 'ECONNREFUSED' });

FluentTransport Class

Winston transport class for sending Winston log entries to Fluentd.

/**
 * Winston transport for Fluent Logger
 * @param tag - Tag prefix for log events (default: 'winston')
 * @param options - Fluent Logger configuration options
 */
class FluentTransport extends Transport {
  constructor(tag?, options?);
  
  /**
   * Log a Winston info object to Fluentd
   * @param info - Winston log info object
   * @param callback - Completion callback
   */
  log(info, callback);
  
  /**
   * Gracefully close the transport
   * @param callback - Completion callback
   */
  _final(callback);
}

Usage Examples:

const winston = require('winston');
const FluentTransport = require('fluent-logger').support.winstonTransport();

// Basic Winston integration
const transport = new FluentTransport('app', {
  host: 'log-server.example.com',
  port: 24224
});

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [transport]
});

// Winston logs are automatically sent to Fluentd
logger.info('User logged in', { 
  userId: 12345, 
  ip: '192.168.1.100',
  userAgent: 'Mozilla/5.0...'
});

logger.warn('Rate limit exceeded', {
  userId: 12345,
  endpoint: '/api/data',
  attempts: 10
});

logger.error('Database query failed', {
  query: 'SELECT * FROM users',
  error: 'Connection timeout',
  duration: 5000
});

Advanced Winston Configuration

Configure Winston with multiple transports and advanced Fluent Logger options.

// Winston transport with advanced Fluent Logger configuration
const advancedTransport = new FluentTransport('production', {
  host: 'production-logs.example.com',
  port: 24224,
  tls: true,
  tlsOptions: {
    ca: fs.readFileSync('/path/to/ca.pem')
  },
  security: {
    clientHostname: 'web-server-01',
    sharedKey: 'production-shared-key'
  },
  eventMode: 'PackedForward',
  requireAckResponse: true,
  ackResponseTimeout: 10000
});

Usage Examples:

const winston = require('winston');
const fs = require('fs');
const FluentTransport = require('fluent-logger').support.winstonTransport();

// Production Winston configuration with multiple destinations
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.errors({ stack: true }),
    winston.format.json()
  ),
  transports: [
    // Local file for debugging
    new winston.transports.File({ 
      filename: 'error.log', 
      level: 'error' 
    }),
    
    // Console for development
    new winston.transports.Console({
      format: winston.format.simple()
    }),
    
    // Fluentd for centralized logging
    new FluentTransport('app', {
      host: 'log-aggregator.example.com',
      port: 24224,
      eventMode: 'CompressedPackedForward',
      flushInterval: 100,
      requireAckResponse: true,
      tls: true,
      tlsOptions: {
        ca: fs.readFileSync('/etc/ssl/fluentd-ca.pem')
      },
      security: {
        clientHostname: process.env.HOSTNAME,
        sharedKey: process.env.FLUENTD_SHARED_KEY
      }
    })
  ]
});

// Add error handling for the Fluent transport
logger.transports[2].on('error', (error) => {
  console.error('Fluentd transport error:', error);
});

logger.transports[2].on('connect', () => {
  console.log('Connected to Fluentd');
});

Transport Event Handling

Handle transport-specific events for monitoring and error handling.

// FluentTransport extends EventEmitter and emits:
// - 'error': When logging fails
// - 'logged': When log is successfully sent  
// - Plus all FluentSender events: 'connect', 'error'

transport.on('error', (error) => { });
transport.on('logged', (info) => { });

Usage Examples:

const FluentTransport = require('fluent-logger').support.winstonTransport();

const transport = new FluentTransport('monitored', {
  host: 'localhost',
  port: 24224,
  enableReconnect: true,
  reconnectInterval: 30000
});

// Monitor transport events
transport.on('error', (error) => {
  console.error('Fluent transport error:', error);
  // Could implement fallback logging, metrics, etc.
});

transport.on('logged', (info) => {
  console.log('Successfully logged to Fluentd:', info.level, info.message);
});

// Monitor underlying FluentSender events
transport.sender.on('connect', () => {
  console.log('Fluentd connection established');
});

transport.sender.on('error', (error) => {
  console.error('Fluentd connection error:', error);
});

const logger = winston.createLogger({
  transports: [transport]
});

// Graceful shutdown
process.on('SIGINT', () => {
  logger.end(() => {
    console.log('Winston logger closed');
    process.exit(0);
  });
});

Multiple Winston Loggers

Use multiple Winston loggers with different Fluent Logger configurations.

Usage Examples:

const winston = require('winston');
const FluentTransport = require('fluent-logger').support.winstonTransport();

// Application logger
const appLogger = winston.createLogger({
  transports: [
    new FluentTransport('app', {
      host: 'app-logs.example.com',
      port: 24224,
      eventMode: 'Message'
    })
  ]
});

// Access logger for HTTP requests
const accessLogger = winston.createLogger({
  transports: [
    new FluentTransport('access', {
      host: 'access-logs.example.com', 
      port: 24224,
      eventMode: 'PackedForward',
      flushInterval: 50  // Fast flush for access logs
    })
  ]
});

// Audit logger with high reliability
const auditLogger = winston.createLogger({
  transports: [
    new FluentTransport('audit', {
      host: 'audit-logs.example.com',
      port: 24224,
      requireAckResponse: true,
      ackResponseTimeout: 30000,
      tls: true,
      tlsOptions: {
        ca: fs.readFileSync('/etc/ssl/audit-ca.pem')
      }
    })
  ]
});

// Use different loggers for different purposes
appLogger.info('Application started');
accessLogger.info('GET /api/users', { ip: '192.168.1.1', responseTime: 45 });
auditLogger.warn('Admin login', { userId: 1, ip: '10.0.0.5' });

Winston v2 vs v3 Compatibility

Fluent Logger supports both Winston v2 and v3+:

  • Winston v2: Use fluent-logger@2.7.0 or earlier
  • Winston v3+: Use fluent-logger@2.8.0 or later (current)

The API is the same for both versions, but Winston v3+ provides better error handling and performance.

Transport Properties

interface FluentTransport extends Transport {
  name: 'fluent';                   // Transport name
  sender: FluentSender;             // Underlying FluentSender instance
  
  // Inherited from Winston Transport
  level?: string;
  silent?: boolean;
  handleExceptions?: boolean;
  handleRejections?: boolean;
}

docs

advanced-configuration.md

core-logging.md

error-handling.md

event-time.md

index.md

stream-integration.md

winston-integration.md

tile.json