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

tessl/npm-fluent-logger

A structured logger for Fluentd (Node.js implementation)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/fluent-logger@3.4.x

To install, run

npx @tessl/cli install tessl/npm-fluent-logger@3.4.0

index.mddocs/

Fluent Logger

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
}