dab246
73 lines
2.3 KiB
Markdown
73 lines
2.3 KiB
Markdown
# 69. Logger Standardization and Logging Best Practices
|
|
|
|
Date: 2025-08-18
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The `tmail-flutter` application uses a custom `app_logger` abstraction to unify logging across platforms (Web and Mobile) and environments (debug vs production).
|
|
|
|
Over time, logging usage became inconsistent:
|
|
- `logError` was used in non-critical or recoverable scenarios.
|
|
- Error-level logs generated excessive noise in monitoring tools (e.g. Sentry).
|
|
- There was no clear, documented guideline describing when to use each log level.
|
|
- Reviewers requested a descriptive piece of developer documentation explaining good logging practices.
|
|
|
|
As part of PR #4205, the logging system was refactored to normalize log severity usage and prepare the codebase for reliable integration with Sentry and similar monitoring tools.
|
|
|
|
## Decision
|
|
|
|
### Defined log levels and intent
|
|
|
|
| Level | Function | Intended usage |
|
|
|------|---------|----------------|
|
|
| critical | logCritical | System-level, unrecoverable failures (extremely rare) |
|
|
| error | logError | Critical, actionable failures that must be monitored |
|
|
| warning | logWarning | Recoverable issues or degraded behavior |
|
|
| info | logInfo / log | Normal application lifecycle events |
|
|
| debug | logDebug | Developer debugging information |
|
|
| trace | logVerbose | High-volume diagnostic logs |
|
|
|
|
### Restriction of logError usage
|
|
|
|
`logError` is restricted to infrastructure-level classes where failures are non-recoverable and must be monitored.
|
|
|
|
Allowed classes:
|
|
- AuthorizationInterceptors
|
|
- CacheExceptionThrower
|
|
- RemoteExceptionThrower
|
|
|
|
All other cases must use `logWarning`.
|
|
|
|
### Logger behavior
|
|
|
|
- Platform-aware formatting (Web vs Mobile)
|
|
- Consistent message normalization
|
|
- Debug-only printing unless explicitly enabled
|
|
|
|
### Error boundary
|
|
|
|
Global error handling is implemented via `initLogger`, ensuring framework and async errors are logged as warnings rather than errors.
|
|
|
|
## Consequences
|
|
|
|
### Benefits
|
|
- Reduced noise in error monitoring
|
|
- Clear logging conventions
|
|
- Improved reviewability
|
|
- Better Sentry signal quality
|
|
|
|
### Trade-offs
|
|
- Stricter logging rules
|
|
- Reduced visibility for non-critical failures
|
|
|
|
## Developer Logging Guidelines
|
|
|
|
- Use logError only for critical, non-recoverable issues
|
|
- Use logWarning for handled or recoverable failures
|
|
- Avoid logging sensitive data
|
|
- Prefer descriptive messages with context
|