strogger

📊 Strogger

📊 A modern structured logging library with functional programming, duck-typing, and comprehensive third-party integrations

Strogger is a modern, developer-friendly structured logging library built with functional programming principles, dependency injection, and duck-typing for maximum flexibility and extensibility.

🎯 Core Focus: Structured Logging

This library is built around the principle that all logs should be structured data. Every log entry is automatically formatted as structured JSON with a consistent schema, making logs easy to parse, search, and analyze.

Why Structured Logging?

• 🔍 Searchable: JSON format enables powerful log searching and filtering
• 📊 Analyzable: Structured data can be easily aggregated and analyzed
• 🔗 Correlatable: Consistent schema enables correlation across services
• 🤖 Machine-readable: Perfect for log aggregation systems and monitoring tools
• 📈 Scalable: Efficient parsing and storage in modern logging systems

✨ Features

🚀 Core Logging

• 📊 Structured JSON Logging - All logs automatically formatted as structured JSON with consistent schema
• 🔄 Functional Programming - Pure functions with dependency injection and duck-typing
• 🚚 Multiple Transports - Console, DataDog, Splunk, Elasticsearch, New Relic, CloudWatch, File
• 🌍 Environment-aware - Automatic configuration based on environment variables

🛠️ Developer Experience

• 📝 TypeScript Support - Full TypeScript support with comprehensive type definitions
• ⚡ AWS Lambda Optimized - Designed to work seamlessly in AWS Lambda environments
• 🔧 Extensible - Easy to add custom transports and formatters using duck-typing
• 📈 Performance Monitoring - Built-in performance tracking and metrics

🔒 Advanced Features

• 🛡️ Comprehensive Error Handling - Clear, actionable error messages with solutions
• 🔍 Advanced Features - Log filtering, validation, redaction, sampling, rate limiting, enrichment, and batching
• 🔐 Security - Built-in support for forbidden keys filtering and redaction
• 🔗 Correlation Tracking - Distributed tracing support

🚀 Quick Start

1. Install Strogger

npm install strogger

2. Basic Usage

import { strogger } from 'strogger';

// Simple logging
strogger.info('Application started');
strogger.debug('Processing request', { requestId: '123' });
strogger.warn('Deprecated feature used');
strogger.error('Something went wrong', { userId: '456' }, new Error('Database connection failed'));

3. Functional Approach with Dependency Injection

import { 
  createLogger, 
  createConsoleTransport, 
  createJsonFormatter, 
  getEnvironment,
  LogLevel 
} from 'strogger';

// Get environment configuration
const env = getEnvironment();

// Create dependencies
const formatter = createJsonFormatter();
const transport = createConsoleTransport({ 
  formatter, 
  level: LogLevel.DEBUG 
});

// Create logger with dependency injection
const logger = createLogger({
  config: { 
    serviceName: 'my-service', 
    stage: 'dev' 
  },
  transports: [transport],
  formatter,
  env,
});

// Use the logger
logger.info('Application started with functional approach');

📖 Usage Guide

🎯 Installation Methods

Method	Install Command	Import Statement	Best For
NPM	npm install strogger	import { strogger } from 'strogger'	Production projects
Yarn	yarn add strogger	import { strogger } from 'strogger'	Yarn-based projects
PNPM	pnpm add strogger	import { strogger } from 'strogger'	PNPM-based projects

🔍 API Reference

Conventional vs Branded APIs

Strogger provides both conventional and branded function names:

// Conventional approach (recommended for most users)
import { createLogger, createConsoleTransport } from 'strogger';

// Branded approach (for brand consistency)
import { createStrogger, createStroggerConsoleTransport } from 'strogger';

// Both work identically:
const logger = createLogger({...});
const strogger = createStrogger({...});

Core Functions

// Logger creation
createLogger(config)
createStrogger(config)

// Transport creation
createConsoleTransport(options)
createStroggerConsoleTransport(options)
createCloudWatchTransport(options)
createDataDogTransport(options)
createSplunkTransport(options)
createElasticsearchTransport(options)
createNewRelicTransport(options)
createFileTransport(options)

// Formatter creation
createJsonFormatter(options)

// Environment utilities
getEnvironment()
getEnvironmentVariables()

Logging Levels

import { LogLevel } from 'strogger';

// Available levels
LogLevel.DEBUG   // 0
LogLevel.INFO    // 1
LogLevel.WARN    // 2
LogLevel.ERROR   // 3
LogLevel.FATAL   // 4

📦 Transport Examples

Console Transport

import { createConsoleTransport, createJsonFormatter } from 'strogger';

const formatter = createJsonFormatter();
const transport = createConsoleTransport({ 
  formatter, 
  level: LogLevel.DEBUG,
  useColors: true 
});

CloudWatch Transport

import { createCloudWatchTransport, createJsonFormatter } from 'strogger';

const formatter = createJsonFormatter();
const transport = createCloudWatchTransport({
  formatter,
  logGroupName: '/aws/lambda/my-function',
  logStreamName: 'production',
  region: 'us-east-1'
});

DataDog Transport

import { createDataDogTransport, createJsonFormatter } from 'strogger';

const formatter = createJsonFormatter();
const transport = createDataDogTransport({
  formatter,
  apiKey: process.env.DATADOG_API_KEY,
  service: 'my-service',
  source: 'nodejs'
});

🎯 Convenience Methods

import { strogger } from 'strogger';

// Function lifecycle logging
strogger.logFunctionStart('processOrder', { orderId: 'order-123' });
// ... function logic ...
strogger.logFunctionEnd('processOrder', 150, { orderId: 'order-123' });

// Database operations
strogger.logDatabaseOperation('SELECT', 'users', { table: 'users' });

// API requests
strogger.logApiRequest('POST', '/api/orders', 201, { orderId: 'order-123' });

⚙️ Configuration

Environment Variables

The logger automatically configures itself based on environment variables:

# Log level (DEBUG, INFO, WARN, ERROR, FATAL)
LOG_LEVEL=INFO

# Environment stage
STAGE=dev

# Service name
SERVICE_NAME=my-service

# Enable structured logging (default: true)
ENABLE_STRUCTURED_LOGGING=true

# Third-party integrations
DATADOG_API_KEY=your-datadog-api-key
SPLUNK_HEC_URL=https://your-splunk-instance:8088/services/collector
SPLUNK_HEC_TOKEN=your-splunk-hec-token
ELASTICSEARCH_URL=http://localhost:9200
ELASTICSEARCH_API_KEY=your-elasticsearch-api-key
NEW_RELIC_LICENSE_KEY=your-newrelic-license-key
NEW_RELIC_ACCOUNT_ID=your-newrelic-account-id

Custom Configuration

import { 
  createLogger, 
  LogLevel, 
  createConsoleTransport, 
  createJsonFormatter,
  getEnvironment 
} from 'strogger';

const env = getEnvironment();
const formatter = createJsonFormatter();
const transport = createConsoleTransport({ 
  formatter, 
  useColors: false 
});

const customLogger = createLogger({
  config: {
    level: LogLevel.DEBUG,
    serviceName: 'my-service',
    stage: 'production',
    enableStructuredLogging: true
  },
  transports: [transport],
  formatter,
  env
});

🏷️ Third-Party Integrations

Strogger provides built-in support for popular logging and monitoring services:

AWS CloudWatch

• Automatic log group and stream management
• Lambda-optimized with minimal cold start impact
• Batch logging for cost efficiency

DataDog

• Structured JSON logs with automatic parsing
• Service and source tagging
• Performance metrics integration

Splunk

• HEC (HTTP Event Collector) support
• Structured data with source types
• Index management and routing

Elasticsearch

• Direct indexing with bulk operations
• Mapping templates for optimal search
• Cluster health monitoring

New Relic

• Distributed tracing integration
• Custom attributes and metrics
• Error tracking and alerting

File Transport

• Rotating log files with compression
• Size and time-based rotation
• Structured JSON output

🎯 Best Practices

1. Use Structured Logging Consistently

// ✅ Good - Structured data
strogger.info('User login successful', { 
  userId: '123', 
  method: 'oauth', 
  provider: 'google' 
});

// ❌ Avoid - Unstructured strings
strogger.info('User 123 logged in via Google OAuth');

2. Leverage Context for Correlation

const context = {
  requestId: 'req-123',
  userId: 'user-456',
  sessionId: 'sess-789'
};

strogger.info('Processing payment', context, { 
  amount: 100.50, 
  currency: 'USD' 
});

3. Use Appropriate Log Levels

// DEBUG - Detailed information for debugging
strogger.debug('Database query executed', { query: 'SELECT * FROM users' });

// INFO - General application flow
strogger.info('User registration completed', { userId: '123' });

// WARN - Potentially harmful situations
strogger.warn('Deprecated API endpoint called', { endpoint: '/api/v1/users' });

// ERROR - Error events that might still allow the application to continue
strogger.error('Database connection failed', { retryCount: 3 });

// FATAL - Very severe error events that will presumably lead to application failure
strogger.fatal('Application cannot start due to missing configuration');

4. Implement Proper Error Handling

try {
  const result = await processPayment(paymentData);
  strogger.info('Payment processed successfully', { 
    paymentId: result.id, 
    amount: paymentData.amount 
  });
} catch (error) {
  strogger.error('Payment processing failed', { 
    paymentId: paymentData.id, 
    error: error.message 
  }, error);
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/TheLeePriest/strogger.git
cd strogger

# Install dependencies
npm install

# Run tests
npm test

# Run linting
npm run lint

# Build the project
npm run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation: GitHub README
• Issues: GitHub Issues
• NPM Package: strogger on NPM
• Changelog: CHANGELOG.md

Made with ❤️ by the Strogger Team

🌱 Environment Variables

Strogger supports several environment variables for configuration. All are optional—sensible defaults are provided for a smooth developer experience.

Variable	Default	Description
LOG_LEVEL	DEBUG (dev/test), INFO (prod)	Minimum log level (DEBUG, INFO, WARN, ERROR, FATAL)
STAGE	dev	Environment stage (dev, prod, test)
SERVICE_NAME	(none)	Name of the service/application
ENABLE_STRUCTURED_LOGGING	true	Output logs as structured JSON (true/false)

You do not need to set any environment variables to use strogger. Defaults are chosen for a smooth developer experience.

Quick Start: Environment Setup

You can set environment variables in your shell or .env file:

export LOG_LEVEL=INFO
export STAGE=prod
export SERVICE_NAME=my-service
export ENABLE_STRUCTURED_LOGGING=true

If you do not set any variables, strogger will use the defaults above.

Changelog

[2.0.3] - 2025-07-01 (PATCH RELEASE)

🐛 Bug Fixes

• convert vitest config to CommonJS to resolve ES module compatibility issue (6c7f3d94)

👥 Contributors

Thanks to Lee Priest for contributing to this release!