JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 59
  • Score
    100M100P100Q72823F
  • License MIT

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

Package Exports

  • strogger
  • strogger/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (strogger) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

📊 Strogger

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

npm version npm downloads GitHub stars License: MIT TypeScript Node.js

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.


Made with ❤️ by the Strogger Team