SyntropyLog

The Observability Framework for High-Performance Teams.
Ship resilient, secure, and cost-effective Node.js applications with confidence.

SyntropyLog

The Observability Framework for High-Performance Teams. Ship resilient, secure, and cost-effective Node.js applications with confidence.

🚀 Project Status: Alpha Version v0.5.11 🚀

SyntropyLog is currently in alpha phase with a solid foundation and comprehensive test coverage.

The core API is taking shape with 94.53% test coverage across 604+ tests. While the framework shows great promise, it's still in active development and not yet ready for production use.

🎯 Latest Achievements (v0.5.9)

• Robust Serialization Pipeline: Implemented intelligent serialization with precise complexity tracking
• Enhanced Test Suite: Achieved 94.53% coverage with 604+ comprehensive tests
• Precision Architecture: Pipeline terminates immediately on serialization failures (no rescue attempts)
• Real Functionality Testing: Tests validate actual behavior, not just mocks

We're actively working on completing examples, refining the API, and adding missing features. Your feedback and contributions are highly welcome!

The SyntropyLog Advantage: A Framework for Every Role

graph TD
    A["HTTP Request<br/>(X-Correlation-ID: 123)"] --> B(API Gateway);
    B -- "Adds ID to Log" --> C{Log Stream};
    B -- "Forwards ID in Header" --> D[User Service];
    D -- "Adds ID to Log" --> C;
    D -- "Publishes Message with ID" --> E(Kafka Topic);
    E --> F[Dispatch Service];
    F -- "Extracts ID from Message" --> F;
    F -- "Adds ID to Log" --> C;

⚡ Quick Start

This example shows how to initialize the logger and make an instrumented HTTP request.

import { syntropyLog, PrettyConsoleTransport } from 'syntropylog';
import { AxiosAdapter } from '@syntropylog/adapters';
import axios from 'axios';

// 1. Configure SyntropyLog once in your application's entry point.
syntropyLog.init({
  logger: {
    level: 'info',
    serviceName: 'my-app',
    transports: [new PrettyConsoleTransport()], // Human-readable for dev
  },
  // Define what context gets logged. Keep it minimal by default, but verbose on error.
  loggingMatrix: {
    default: ['correlationId'],
    error: ['*'], // '*' means log the entire context
    fatal: ['*'],
  },
  context: {
    correlationIdHeader: 'X-Correlation-ID',
  },
  http: {
    instances: [
      {
        instanceName: 'myApi',
        adapter: new AxiosAdapter(axios.create({ baseURL: 'https://api.example.com' })),
      },
    ],
  },
});

// 2. Get the instrumented client and logger anywhere you need them.
const apiClient = syntropyLog.getHttp('myApi');
const logger = syntropyLog.getLogger();

// 3. Use them. The framework handles the rest.
async function main() {
    // Add extra data to the context for this specific operation
    syntropyLog.getContextManager().set('userId', 123);

    logger.info('Fetching user data...'); // Will only have `correlationId` in the context
    
    try {
      await apiClient.request({
        method: 'GET',
        url: '/users/1/posts',
      });
    } catch (err) {
      // This log will contain the full context, including `userId`, because the level is 'error'.
      logger.error({ err }, 'Failed to fetch posts');
    }
}

main();

🔌 External Adapters

SyntropyLog provides a rich ecosystem of external adapters for various databases, HTTP clients, and message brokers. These adapters are available as a separate package for maximum flexibility.

Quick Install

npm install @syntropylog/adapters

Available Adapters

• Database Serializers: Prisma, TypeORM, MySQL, PostgreSQL, SQL Server, Oracle, MongoDB
• HTTP Clients: Axios, Fetch, Got, Request
• Message Brokers: Kafka, NATS, RabbitMQ

Usage Example

import { syntropyLog } from 'syntropylog';
import { PrismaSerializer, KafkaAdapter } from '@syntropylog/adapters';

// Use adapters independently
const prismaSerializer = new PrismaSerializer();
const kafkaAdapter = new KafkaAdapter({ brokers: ['localhost:9092'] });

📖 Full Adapters Documentation

📂 Learn by Example

The best way to learn SyntropyLog is to see it in action. We have a comprehensive collection of examples in our dedicated examples repository.

Each example is a self-contained project that demonstrates a specific feature, from data masking to building a fully correlated full-stack application.

➡️ Explore the Examples

Example Categories:

• 00-setup-initialization: ✅ Complete - Application setup and initialization
• 01-hello-world: ✅ Complete - Basic logging concepts
• 10-basic-context: 🚧 In Progress - Context management fundamentals
• 20-context-ts: 🚧 In Progress - TypeScript context examples
• 30-data-masking: 🚧 In Progress - Security and data protection
• 40-basic-http-correlation: 🚧 In Progress - HTTP request correlation
• 45-custom-http-adapter: 🚧 In Progress - Custom HTTP adapters
• 50-basic-kafka-correlation: 🚧 In Progress - Message broker correlation
• 60-advanced-rabbitmq-broker: 🚧 In Progress - Advanced RabbitMQ integration
• 70-full-stack-correlation: 🚧 In Progress - Complete distributed tracing
• 75-full-stack-correlation-http-redis: 🚧 In Progress - HTTP + Redis correlation
• 80-full-stack-nats: 🚧 In Progress - NATS microservices architecture
• 90-compliance-retention: 🚧 In Progress - Log retention and compliance
• 100-custom-serializers: 🚧 In Progress - Custom data serialization
• 110-diagnostics-doctor: 🚧 In Progress - Configuration validation
• 120-private-package-registry: 🚧 In Progress - Private package registry setup
• 130-github-packages-consumer: 🚧 In Progress - GitHub packages integration

🧪 Testing & Quality

SyntropyLog is built with quality and reliability in mind:

• 94.53% Test Coverage across 604+ tests
• 45 Test Files covering all major components
• Integration Tests for end-to-end scenarios
• Comprehensive Mock System for easy testing
• Type Safety with full TypeScript support

Run the test suite:

npm test                    # Unit tests
npm run test:integration    # Integration tests
npm run test:coverage       # Coverage report

🛠️ Development

Project Structure

SyntropyLog is organized into multiple repositories:

• syntropyLog/: Main library source code and tests
• syntropylog-examples-: Complete examples demonstrating framework features
• syntropylog-adapters-: External adapters for HTTP clients and message brokers

Prerequisites

• Node.js 18+
• npm or yarn

Setup

git clone https://github.com/Syntropysoft/SyntropyLog.git
cd syntropylog
npm install

Build

npm run build              # Build library and types
npm run build:types        # Generate type definitions only

Development Workflow

npm run dev                # Start development mode
npm run lint               # Run linter
npm run format             # Format code

📦 Installation

⚠️ Alpha Version Warning: SyntropyLog is currently in alpha phase. The API may change between versions. Use with caution in production environments.

npm install syntropylog

🔌 Supported Dependencies

SyntropyLog includes built-in adapters for popular libraries. Here are the supported versions:

HTTP Clients

• Axios: ^1.10.0 ✅ Available in @syntropylog/adapters
• Fetch: Native browser API ✅ Available in @syntropylog/adapters
• Got: ^12.0.0 (planned)
• Request: ^2.88.2 ✅ Available in @syntropylog/adapters

Message Brokers

• Kafka: kafkajs ^2.2.4 (planned)
• RabbitMQ: amqplib ^0.10.8 (planned)
• NATS: nats ^2.17.0 (planned)

Database Serializers

• Prisma: (planned)
• TypeORM: (planned)
• MySQL: (planned)
• PostgreSQL: (planned)

Usage Example

import { syntropyLog } from 'syntropylog';
import { AxiosAdapter } from '@syntropylog/adapters';
import axios from 'axios';

// Use the AxiosAdapter from the adapters package
const adapter = new AxiosAdapter(axios.create({ 
  baseURL: 'https://api.example.com' 
}));

📄 License

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

🤝 Contributing

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

📞 Support

• 📖 Documentation
• 🐛 Issues
• 💬 Discussions