TF-4136 docs(adr): add logging standardization and best practices

2026-01-02 12:18:51 +07:00
parent a23d15a9ca
commit 492755f97f
1 changed files with 72 additions and 0 deletions
@@ -0,0 +1,72 @@
+# 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 | logWTF | 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