@addon24/pino-ecs-elastic

Pino logger with ECS (Elastic Common Schema) format and Elasticsearch integration for WorldOfTextcraft projects.

Features

• 🚀 Pino-based - Fast and efficient logging
• 📊 ECS Format - Elastic Common Schema for standardized logs
• 🔍 Elasticsearch Integration - Direct streaming to Elasticsearch
• 📁 File Logging - Multiple log files (debug, info, error)
• 🎯 TypeScript - Full TypeScript support with type definitions
• 🔧 Configurable - Flexible configuration options
• 🎨 Custom Serializers - Enhanced error serialization

Installation

yarn add @addon24/pino-ecs-elastic

Usage

Basic Usage

import { createLogger } from "@addon24/pino-ecs-elastic";

const logger = createLogger({
  appName: "my-app",
  logDir: "/var/log/my-app",
  elasticsearchNode: "http://localhost:9200",
  useElasticsearch: true,
  logLevel: "info",
});

logger.info({ userId: "123" }, "User logged in");
logger.error({ error: new Error("Test error") }, "An error occurred");

Configuration Options

interface LoggerConfig {
  appName: string;                    // Required: Application name
  logDir?: string;                    // Optional: Log directory (default: /var/log/app)
  elasticsearchNode?: string;         // Optional: Elasticsearch URL (default: http://localhost:9200)
  useElasticsearch?: boolean;         // Optional: Enable Elasticsearch (default: true)
  logLevel?: string;                  // Optional: Log level (default: debug)
  enableFileLogging?: boolean;        // Optional: Enable file logging (default: true)
}

Environment Variables

You can also configure the logger using environment variables:

LOG_DIR=/var/log/backend
ELASTICSEARCH_NODE=http://elasticsearch:9200
USE_ELASTICSEARCH=true
LOG_LEVEL=debug

Advanced Usage

import { createLogger, serializeError } from "@addon24/pino-ecs-elastic";

const logger = createLogger({
  appName: "backend",
  logDir: process.env.LOG_DIR || "/var/log/backend",
  elasticsearchNode: process.env.ELASTICSEARCH_NODE || "http://localhost:9200",
  useElasticsearch: process.env.USE_ELASTICSEARCH !== "false",
  logLevel: "debug",
  enableFileLogging: true,
});

// Log with structured data
logger.info({
  userId: "abc123",
  action: "login",
  ip: "192.168.1.1",
}, "User authentication successful");

// Log errors with full stack traces
try {
  throw new Error("Something went wrong");
} catch (error) {
  logger.error({ error }, "Operation failed");
}

// Use custom error serialization
const serializedError = serializeError(error);
console.log(serializedError);

Log Files

When file logging is enabled, the logger creates three separate log files:

• app.debug.log - All logs (debug level and above)
• app.info.log - Info logs and above
• app.error.log - Error logs only

Elasticsearch Integration

Logs are automatically streamed to Elasticsearch with:

• Index pattern: {appName}-logs
• ECS format for consistent field mapping
• Automatic retry on connection failures
• Configurable flush intervals

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { LoggerConfig, ExtendedLogger } from "@addon24/pino-ecs-elastic";

const config: LoggerConfig = {
  appName: "my-app",
  logLevel: "info",
};

const logger: ExtendedLogger = createLogger(config);

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please open an issue on GitHub.