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

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Fluent Logger

Name: tessl/npm-fluent-logger
Author: tessl

Fluent Logger is a Node.js client library for sending structured log data to Fluentd, a popular open-source data collector. It provides both singleton and instance-based logging patterns, supports various authentication methods including shared key and TLS/SSL encryption, and offers integration with popular logging frameworks like Winston.

Package Information

Package Name: fluent-logger
Package Type: npm
Language: JavaScript
Installation: npm install fluent-logger

Core Imports

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

For ES modules:

import fluentLogger from 'fluent-logger';
// or 
import { createFluentSender, EventTime } from 'fluent-logger';

Basic Usage

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

// Singleton pattern - configure once, use anywhere
logger.configure('app', {
  host: 'localhost',
  port: 24224,
  timeout: 3.0,
  reconnectInterval: 600000 // 10 minutes
});

// Send structured log events
logger.emit('access', { 
  path: '/api/users', 
  method: 'GET', 
  status_code: 200,
  response_time: 42
});

// Instance pattern - create dedicated senders  
const sender = logger.createFluentSender('app', {
  host: 'log-server.example.com',
  port: 24224
});

sender.emit('debug', { message: 'User login attempt', user_id: 12345 });

Architecture

Fluent Logger is built around several key components:

Singleton API: Global logger instance for simple application-wide logging
FluentSender Class: Individual sender instances for multi-destination logging
Event Transmission Modes: Message, PackedForward, and CompressedPackedForward protocols
Security Layer: Shared key authentication, TLS encryption, and mutual TLS support
Integration Layer: Winston transport and stream interfaces for framework compatibility
EventTime Support: High-precision timestamps for event-time logging

Capabilities

Core Logging API

Basic logging functionality including singleton configuration, instance creation, and event emission. Essential for getting started with structured logging.

// Singleton configuration
function configure(tag, options);

// Instance creation  
function createFluentSender(tag, options);

// Event emission (singleton)
function emit(label, data, timestamp?, callback?);

Core Logging

Advanced Configuration

Advanced configuration options including security authentication, TLS encryption, event transmission modes, and performance tuning settings.

interface FluentLoggerOptions {
  host?: string;
  port?: number; 
  timeout?: number;
  security?: SecurityOptions;
  tls?: boolean;
  tlsOptions?: TLSOptions;
  eventMode?: 'Message' | 'PackedForward' | 'CompressedPackedForward';
  enableReconnect?: boolean;
  reconnectInterval?: number;
}

interface SecurityOptions {
  clientHostname?: string;
  sharedKey?: string;
  username?: string;
  password?: string;
}

Advanced Configuration

Winston Integration

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

function support.winstonTransport();

class FluentTransport extends Transport {
  constructor(tag?, options?);
  log(info, callback);
}

Winston Integration

EventTime Support

High-precision timestamp support using Fluentd's EventTime format for microsecond-precision event timing.

class EventTime {
  constructor(epoch, nano);
  static now(): EventTime;
  static fromDate(date: Date): EventTime;
  static fromTimestamp(timestamp: number): EventTime;
}

EventTime Support

Stream Integration

Stream interface support for integrating with Node.js streams, Console output, and stream-based libraries like Morgan.

// Create writable streams that send to Fluentd
FluentSender.prototype.toStream(options);

// Stream options
interface StreamOptions {
  label: string;                    // Event label for stream output
  encoding?: string;                // Text encoding (default: 'UTF-8')
}

Stream Integration

Error Handling

Comprehensive error handling with specific error types for different failure scenarios and event-based error reporting.

// Error event handling
sender.on('error', (error) => { });
sender.on('connect', () => { });

// Error types
class ConfigError extends Error { }
class MissingTag extends Error { }  
class ResponseError extends Error { }
class ResponseTimeout extends Error { }
class DataTypeError extends Error { }
class HandshakeError extends Error { }

Error Handling

Types

interface FluentLoggerOptions {
  host?: string;                    // Fluentd hostname (default: 'localhost')
  port?: number;                    // Fluentd port (default: 24224)
  path?: string;                    // Unix domain socket path
  timeout?: number;                 // Socket timeout in seconds (default: 3.0)
  tls?: boolean;                    // Enable TLS encryption (default: false)
  tlsOptions?: object;              // TLS connection options
  enableReconnect?: boolean;        // Enable automatic reconnection (default: true)
  reconnectInterval?: number;       // Reconnect interval in ms (default: 600000)
  requireAckResponse?: boolean;     // Wait for acknowledgment (default: false)
  ackResponseTimeout?: number;      // Ack timeout in ms (default: 190000)
  eventMode?: EventMode;            // Event transmission mode (default: 'Message')
  flushInterval?: number;           // Flush interval in ms for PackedForward modes (default: 100)
  messageQueueSizeLimit?: number;   // Queue size limit for Message mode (default: 0)
  sendQueueSizeLimit?: number;      // Queue size limit in bytes for PackedForward modes (default: 8MB)
  milliseconds?: boolean;           // Use millisecond precision timestamps (default: false)
  internalLogger?: object;          // Internal logger object (default: console)
  security?: SecurityOptions;       // Security configuration
}

type EventMode = 'Message' | 'PackedForward' | 'CompressedPackedForward';

interface SecurityOptions {
  clientHostname?: string;          // Client hostname for authentication
  sharedKey?: string;               // Shared key for authentication
  username?: string;                // Username for authentication  
  password?: string;                // Password for authentication
}

interface FluentSender {
  emit(label?, data, timestamp?, callback?): void;
  end(label?, data?, callback?): void;
  toStream(options): stream.Writable;
  on(event, listener): void;
  // ... other EventEmitter methods
}