or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-configuration.mdcore-logging.mderror-handling.mdevent-time.mdindex.mdstream-integration.mdwinston-integration.md
tile.json

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;
}