Backend Logging

Last Updated: May 20, 2025

This document provides an overview of the backend logging system in the Typus Development Framework.

Overview

The backend logging system in Typus is built on a flexible, multi-transport architecture that allows logs to be directed to various outputs simultaneously. It provides rich contextual information, automatic caller tracking, and sophisticated error handling to facilitate debugging and monitoring.

Key Features

• Multiple Log Levels: debug, info, warn, error
• Contextual Information: Automatic source file and line tracking
• Structured Metadata: Support for complex data structures
• Color-Coded Output: Visual differentiation in console
• Secret Masking: Automatic protection of sensitive information
• Error Enhancement: Detailed error reporting with stack traces
• Table Support: Formatted display of tabular data

Output Transports

The backend logger supports multiple output transports that can be configured via environment variables:

Console Transport

Outputs logs to the terminal with color-coding for improved readability:

• Tags are color-coded by module/component
• Error messages are highlighted in red
• File paths are highlighted in blue
• Different log levels have distinct colors

Example console output:

[2025-05-20T05:04:32.651Z] [INFO] [AuthService] User login successful {userId: 123, ip: "192.168.1.1"} {/src/modules/auth/services/AuthService.ts:42}

File Transport

Writes logs to files in the logs directory:

• combined.log: Contains all log levels
• error.log: Contains only error-level logs

Database Transport

Stores logs in the database for persistent storage and advanced querying:

• Structured format for efficient querying
• Separate storage for error details
• Support for complex metadata

Configuration

Backend logging is configured through environment variables:

LOG_LEVEL=info                # Minimum log level to process
LOG_MODE=console,file,database # Comma-separated list of output modes

Available log levels (in order of verbosity):

1. debug - Most verbose, includes all logs
2. info - General operational logs
3. warn - Warning conditions
4. error - Error conditions only

Advanced Features

Automatic Caller Tracking

The logger automatically captures the source file and line number for each log entry, making it easier to trace the origin of logs.

Tag-Based Module Identification

Logs are automatically tagged with the module and component name, which helps in filtering and identifying the source of logs.

Secret Masking

Sensitive information is automatically masked in logs:

// Input with sensitive data
User authenticated {userId: 123, password: "secret123", token: "eyJhbGciOiJ..."}

// Output after masking
User authenticated {userId: 123, password: "***MASKED***", token: "***MASKED***"}

The system automatically masks sensitive fields like passwords, tokens, API keys, and authorization headers.

Error Enhancement

Error logging includes detailed information:

• Error message
• Stack trace
• Error type
• Additional context

Console output for errors is enhanced with color-coding and formatting for better readability.

Metadata Truncation

Large metadata objects are automatically truncated to prevent excessive log sizes, which helps in maintaining performance and readability.

Integration with Core System

The backend logger is integrated with the core system in several ways:

1. Global Logger: Available throughout the application without explicit imports
2. Base Class Integration: Automatically available in all core classes
3. Middleware Integration: Integrated with the request processing pipeline

Performance Considerations

The backend logging system is designed for minimal performance impact:

1. Conditional Processing: Logs below the configured level are skipped early
2. Asynchronous Database Writes: Database logging doesn't block request processing
3. Efficient Formatting: Log formatting is optimized for performance
4. Metadata Truncation: Large objects are automatically truncated

Best Practices

Contextual Logging

Always include relevant context with logs:

// Good practice
[UserService] User profile updated {userId: 123, updatedFields: ["name", "email"]}

// Avoid
Profile updated

Appropriate Log Levels

Use the appropriate log level for each message:

• debug: Detailed information for development and troubleshooting
• info: Normal application flow and important events
• warn: Potential issues that don't prevent operation
• error: Errors that affect functionality

Structured Metadata

Use structured metadata instead of string concatenation:

// Good practice
[PaymentService] Payment processed {amount: 99.99, currency: "USD", paymentMethod: "credit_card"}

// Avoid
[PaymentService] Payment of $99.99 USD processed with credit_card

Error Logging

Pass Error objects directly to provide stack traces, which helps in troubleshooting and debugging.

Conclusion

The backend logging system in Typus provides comprehensive visibility into application behavior while maintaining performance and security. By following the best practices outlined in this document, developers can create logs that are valuable for debugging, monitoring, and auditing.