Frontend Logging

Last Updated: May 20, 2025

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

Overview

The frontend logging system in Typus provides a robust solution for capturing, formatting, and transmitting logs from client applications. It supports multiple output modes, batched API logging, and seamless integration with the backend logging infrastructure.

Key Features

• Multiple Log Levels: debug, info, warn, error
• Contextual Logging: Component/service identification
• Structured Metadata: Support for complex data objects
• Error Object Handling: Automatic extraction of error details
• Batched API Logging: Efficient network usage
• Vue Integration: Easy access in components
• Auto-Import Support: Available throughout the application

Output Modes

The frontend logger supports multiple output modes that can be configured via environment variables:

Console Mode

Outputs logs to the browser console with appropriate formatting:

• Debug logs use console.log (to ensure visibility)
• Info logs use console.info
• Warning logs use console.warn with a warning triangle icon (⚠️)
• Error logs use console.error with an error icon (❌)

Example console output:

[2025-05-20T05:04:32.651Z] [App] [UserProfile] User profile loaded {userId: 123, sections: ["personal", "preferences"]}

API Mode

Sends logs to the backend API endpoint for centralized storage and analysis:

• Logs are batched to reduce network requests
• Batches are sent when:
  • The batch reaches the maximum size (default: 50 logs)
  • The maximum wait time is reached (default: 5 seconds)
  • The page is about to unload (with best effort)
• Large metadata objects are truncated to prevent excessive payload sizes

Configuration

Frontend logging is configurable through environment variables:

VITE_LOG_LEVEL=info           # Minimum log level to process
VITE_LOG_MODE=api             # 'console', 'api', 'both', or 'none'
VITE_LOG_API_ENDPOINT=/api/logs
VITE_LOG_BATCH_SIZE=50        # Maximum logs per batch
VITE_LOG_FLUSH_INTERVAL=5000  # Milliseconds between batches
VITE_LOG_MAX_BATCH_SIZE_MB=10 # Maximum batch size in MB

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

Integration with Vue Components

The logger is available through a composable hook for easy access in Vue components, and is configured for auto-import in the application, making it available without explicit imports.

Advanced Features

Error Object Handling

The logger can accept an Error object directly, which automatically extracts the message and stack trace for comprehensive error reporting.

Circular Reference Handling

The logger automatically handles circular references in metadata objects, preventing JSON.stringify errors that would otherwise occur.

Metadata Size Management

Large metadata objects are automatically managed to prevent excessive log sizes, with truncation applied when necessary.

Context Support

The context parameter helps identify the source of logs, making it easier to trace logs back to specific components or services.

Log Flow to Backend

When configured for API mode, logs follow this flow:

Security Considerations

Sensitive Data

The system encourages careful handling of sensitive information:

• Avoid logging passwords, tokens, and other sensitive data
• Log only necessary information for debugging and monitoring
• Be mindful of personally identifiable information (PII)

Network Exposure

When sending logs to the backend:

1. Always use HTTPS in production
2. Consider what information is appropriate to send
3. Be aware of data privacy regulations (GDPR, CCPA, etc.)

Performance Considerations

The frontend logging system is designed for minimal performance impact:

1. Conditional Processing: Logs below the configured level are skipped early
2. Batched API Requests: Reduces network overhead
3. Throttled Transmission: Prevents excessive API calls
4. Size Limits: Automatic truncation of large payloads

Best Practices

Component Context

Always include the component or service name as context to make logs more traceable.

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 to make logs more searchable and analyzable.

Error Logging

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

Integration with Backend

The frontend logging system integrates seamlessly with the backend:

1. Logs are sent to the /api/logs endpoint (configurable)
2. The backend stores logs in the same format as backend-generated logs
3. All logs can be queried and analyzed together
4. Frontend logs include additional context like IP address and user ID (when available)

Conclusion

The frontend logging system in Typus provides comprehensive visibility into client-side 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 improving the user experience.