feat(logging): implement configurable log levels via VITE_LOG_LEVEL

Add comprehensive logging configuration system with environment variable support.
Environment files now include appropriate log levels per build mode:
- Development: debug (maximum visibility)
- Production: warn (minimal noise)
- Testing: info (balanced output)

Includes smart default behavior based on platform and environment,
enhanced logger methods for level checking, and comprehensive documentation.
All existing logging calls remain backward compatible.

Closes logging configuration request
This commit is contained in:
Matthew Raymer
2025-08-12 03:52:46 +00:00
parent 85f0283278
commit d30597a921
8 changed files with 223 additions and 34 deletions

View File

@@ -0,0 +1,117 @@
# Logging Configuration Guide
## Overview
TimeSafari now supports configurable logging levels via the `VITE_LOG_LEVEL` environment variable. This allows developers to control the verbosity of console output without modifying code.
## Available Log Levels
| Level | Value | Description | Console Output |
|-------|-------|-------------|----------------|
| `error` | 0 | Errors only | Critical errors only |
| `warn` | 1 | Warnings and errors | Warnings and errors |
| `info` | 2 | Info, warnings, and errors | General information, warnings, and errors |
| `debug` | 3 | All log levels | Verbose debugging information |
## Environment Variable
Set the `VITE_LOG_LEVEL` environment variable to control logging:
```bash
# Show only errors
VITE_LOG_LEVEL=error
# Show warnings and errors (default for production web)
VITE_LOG_LEVEL=warn
# Show info, warnings, and errors (default for development/capacitor)
VITE_LOG_LEVEL=info
# Show all log levels including debug
VITE_LOG_LEVEL=debug
```
## Default Behavior by Platform
The logger automatically selects appropriate default log levels based on your platform and environment:
- **Production Web**: `warn` (warnings and errors only)
- **Electron**: `error` (errors only - very quiet)
- **Development/Capacitor**: `info` (info and above)
## Usage Examples
### Setting Log Level in Development
```bash
# In your terminal before running the app
export VITE_LOG_LEVEL=debug
npm run dev
# Or inline
VITE_LOG_LEVEL=debug npm run dev
```
### Setting Log Level in Production
```bash
# For verbose production logging
VITE_LOG_LEVEL=info npm run build:web
# For minimal production logging
VITE_LOG_LEVEL=warn npm run build:web
```
### Programmatic Access
The logger provides methods to check current configuration:
```typescript
import { logger } from '@/utils/logger';
// Get current log level
const currentLevel = logger.getCurrentLevel(); // 'info'
// Check if a level is enabled
const debugEnabled = logger.isLevelEnabled('debug'); // false if level < debug
// Get available levels
const levels = logger.getAvailableLevels(); // ['error', 'warn', 'info', 'debug']
```
## Database Logging
Database logging continues to work regardless of console log level settings. All log messages are still stored in the database for debugging and audit purposes.
## Migration Notes
- **Existing code**: No changes required - logging behavior remains the same
- **New feature**: Use `VITE_LOG_LEVEL` to override default behavior
- **Backward compatible**: All existing logging calls work as before
## Best Practices
1. **Development**: Use `VITE_LOG_LEVEL=debug` for maximum visibility
2. **Testing**: Use `VITE_LOG_LEVEL=info` for balanced output
3. **Production**: Use `VITE_LOG_LEVEL=warn` for minimal noise
4. **Debugging**: Temporarily set `VITE_LOG_LEVEL=debug` to troubleshoot issues
## Troubleshooting
### No Logs Appearing
Check your `VITE_LOG_LEVEL` setting:
```bash
echo $VITE_LOG_LEVEL
```
### Too Many Logs
Reduce verbosity by setting a lower log level:
```bash
VITE_LOG_LEVEL=warn
```
### Platform-Specific Issues
Remember that Electron is very quiet by default. Use `VITE_LOG_LEVEL=info` to see more output in Electron builds.