Logger Architecture

Last Updated: May 20, 2025

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

Overview

Typus implements a comprehensive logging system that spans both frontend and backend components. The logging architecture follows a unified pattern while accommodating the specific requirements of each environment. This centralized approach ensures consistent logging practices across the entire application stack.

Architecture Diagram

Core Principles

The logging system is built on several key principles:

1. Unified Interface: Both frontend and backend use a consistent logger.XXXX() pattern (debug, info, warn, error)
2. Configurable Outputs: Logs can be directed to multiple destinations based on configuration
3. Context Awareness: Logs include contextual information about their source
4. Security: Sensitive information is automatically masked
5. Performance: Batching and throttling mechanisms prevent logging from impacting application performance

Frontend Logging

Features

• Multiple Log Levels: debug, info, warn, error
• Multiple Output Modes: console, API, both, or none
• Batched API Logging: Reduces network requests by grouping logs
• Context Support: Adds component/module context to logs
• Metadata Handling: Supports structured data with circular reference handling
• Error Integration: Special handling for Error objects with stack traces
• Auto-Import Support: Available through composables

Configuration

Frontend logging is configurable through environment variables:

VITE_LOG_LEVEL=info           # 'debug', 'info', 'warn', 'error'
VITE_LOG_MODE=api             # 'console', 'api', 'both', 'none'
VITE_LOG_API_ENDPOINT=/api/logs
VITE_LOG_BATCH_SIZE=50        # Maximum logs per batch
VITE_LOG_FLUSH_INTERVAL=5000  # Milliseconds between batches

Frontend Log Flow

Backend Logging

Features

• Multiple Log Levels: debug, info, warn, error
• Multiple Output Modes: console, file, database
• Caller Tracking: Automatically identifies the source file and line
• Color Coding: Visual differentiation of log components in console
• Secret Masking: Automatic redaction of sensitive information
• Error Enhancement: Detailed error reporting with stack traces
• Database Integration: Structured storage of logs for analysis
• Table Support: Formatted display of tabular data

Configuration

Backend logging is configurable through environment variables:

LOG_LEVEL=info                # 'debug', 'info', 'warn', 'error'
LOG_MODE=console,file,database # Comma-separated list of output modes

Backend Log Flow

Log Storage and Processing

Storage Types

The logging system stores data in two primary formats:

1. Database Storage: Structured format for efficient querying

   • Log entries with metadata
   • Related error details
   • Context information

2. File Storage: Traditional log files

   • Combined logs (all levels)
   • Error-specific logs
   • JSON format for machine processing

Log Aggregation

The system supports aggregating logs from multiple sources:

1. Frontend Logs: Collected via API and stored in the database
2. Backend Logs: Written directly to database and/or files
3. System Logs: Operating system and infrastructure logs (optional)

Best Practices

When to Use Each Log Level

• debug: Detailed information useful during development and troubleshooting
• info: General application flow and important events
• warn: Potential issues that don't prevent the application from working
• error: Errors that affect functionality or user experience

Adding Context

Always include relevant context with logs:

// Good practice
User profile updated {userId: 123, changedFields: ["name", "email"]} - ProfileService

// Avoid
Updated

Structured Logging

Use structured metadata instead of string concatenation:

// Good practice
Payment failed {orderId: "ORD-123", reason: "Insufficient funds"}

// Avoid
Payment failed for order ORD-123: Insufficient funds

Error Handling

Pass Error objects directly to the error method to capture stack traces and detailed error information.

Security Considerations

The logging system automatically masks sensitive information:

• Passwords
• Authentication tokens
• API keys
• Authorization headers
• Other secrets defined in configuration

Performance Impact

The logging system is designed to minimize performance impact:

1. Frontend:

   • Batches logs to reduce API calls
   • Truncates large payloads
   • Configurable flush intervals

2. Backend:

   • Asynchronous database writes
   • Configurable log levels to control volume
   • Automatic truncation of large objects

Monitoring and Analysis

Logs can be analyzed through:

1. Database Queries: Structured queries against the log database
2. Log Files: Traditional log analysis tools
3. Integration: Export to external monitoring systems (optional)

Conclusion

The Typus logging architecture provides a comprehensive solution for application monitoring, debugging, and auditing. By implementing consistent logging practices across frontend and backend, the system ensures that developers have visibility into application behavior while maintaining performance and security.