fix: replace console statements with centralized logger utility (#1057)

* fix: replace console statements with centralized logger utility

- Create environment-aware logger utility (dev/prod)
- Migrate all 150 console.* statements to logger
- Add Sentry-ready structure for future integration
- Configure logger with category-based filtering
- Document logger usage in frontend CLAUDE.md
- Zero ESLint console warnings remaining

Logger features:
- Debug/info only in development
- Warn/error always logged
- Context support for errors
- Performance timing utilities
- TypeScript fully typed

* style: apply prettier formatting to modified files

* docs: fix duplicate logger declarations and remove obsolete TODO

- Fix CLAUDE.md examples to avoid duplicate const declarations
- Remove TODO comment about Sentry since logger is already Sentry-ready
- Clarify logger usage patterns with proper variable names

* refactor: polish Svelte logging patterns

- Remove redundant import.meta.env.DEV checks (logger handles environment automatically)
- Move template logging to proper functions using snippets
- Add comprehensive component context to all error logs
- Update documentation with Svelte-specific logging best practices

Fixed issues:
- NotificationBell: Improved error context for loadNotifications and markAsRead
- DailySummaryCard: Moved template logging to snippet pattern
- FilterSettingsPage: Simplified environment-aware logging
- Added Svelte logging patterns to frontend CLAUDE.md

* refactor: enhance logging practices and documentation

- Standardized logger usage across components by replacing `getLogger('app')` with specific loggers like `loggers.analytics` and `loggers.auth`.
- Improved error logging context in `DailySummaryCard` for better traceability.
- Updated `CLAUDE.md` to include critical guidelines on PII protection and logging best practices.
- Added security-aware logging patterns to prevent exposure of sensitive data.

These changes aim to streamline logging practices and enhance security measures in the codebase.

* feat: implement URL credential redaction in RTSPUrlInput component

- Added a function to redact credentials from RTSP URLs for safer logging.
- Enhanced error logging in the addUrl function to include redacted URLs, improving security and traceability.

These changes aim to protect sensitive information during logging while maintaining functionality.

* refactor: enhance logging context and improve logger utility

- Updated logger usage in NotificationBell and DailySummaryCard components to include detailed context for warnings, improving traceability of issues.
- Renamed logger instance in CLAUDE.md for clarity.
- Enhanced logger interface to support throttling, preventing excessive log messages and improving performance.

These changes aim to streamline logging practices and provide better insights during debugging.

Author: tphakala

frontend/CLAUDE.md

@@ -197,6 +197,198 @@ function getCsrfToken(): string | null {
 headers.set('X-CSRF-Token', getCsrfToken());
 ```
 
+## Logging
+
+Use the centralized logger utility instead of console statements:
+
+```typescript
+import { getLogger, loggers } from '$lib/utils/logger';
+
+// Option 1: Create a custom logger for your module
+const customLogger = getLogger('myModule');
+
+// Option 2: Use predefined category loggers
+const apiLogger = loggers.api; // For API-related logging
+const authLogger = loggers.auth; // For authentication
+const sseLogger = loggers.sse; // For SSE connections
+const audioLogger = loggers.audio; // For audio components
+const uiLogger = loggers.ui; // For UI components
+const settingsLogger = loggers.settings; // For settings
+
+// Most common pattern - choose one logger per file:
+const logger = loggers.ui; // For UI components
+```
+
+**Important**: Call `getLogger()` once when the module loads and reuse the returned logger instance throughout the module. This prevents creating multiple logger instances inside functions, reducing unnecessary object allocation and ensuring consistent category scoping.
+
+### Logger Methods
+
+```typescript
+// Debug information (dev only)
+logger.debug('Component initialized', props);
+
+// Informational messages (dev only)
+logger.info('Connection established');
+
+// Warnings (always logged)
+logger.warn('Deprecated method used');
+
+// Errors with context (always logged)
+logger.error('Failed to save', error, {
+  component: 'SettingsPage',
+  action: 'save',
+  userId: user.id,
+});
+
+// Performance timing (development only - no-op in production)
+logger.time('dataLoad');
+// ... expensive operation
+logger.timeEnd('dataLoad'); // Logs: [category] dataLoad: 123.45ms
+
+// Grouping (development only - no-op in production)
+logger.group('Processing items');
+items.forEach(item => logger.debug('Item:', item));
+logger.groupEnd();
+```
+
+### Key Features
+
+- **Environment-aware**: Debug/info logs only in development
+- **Zero configuration**: Works immediately
+- **Category-based**: Helps identify log sources
+- **Sentry-ready**: Structured for future integration
+- **Type-safe**: Full TypeScript support
+- **No console warnings**: Properly configured for ESLint
+- **Security-aware**: Built-in PII protection guidelines
+
+### Security and PII Protection
+
+**CRITICAL**: Never log personally identifiable information (PII) or sensitive data:
+
+```typescript
+// ❌ Don't log PII or sensitive data
+logger.error('Login failed', error, {
+  username: 'john.doe@example.com', // PII
+  password: 'secret123', // Sensitive
+  sessionToken: 'abc123xyz', // Sensitive
+});
+
+// ✅ Log safe identifiers and context
+logger.error('Login failed', error, {
+  component: 'LoginForm',
+  action: 'authenticate',
+  userId: user.id, // Safe: non-PII identifier
+  attemptCount: 3, // Safe: operational data
+});
+
+// ✅ Sanitize or redact sensitive fields
+logger.debug('API request', {
+  endpoint: '/api/user/profile',
+  method: 'POST',
+  headers: { 'content-type': 'application/json' }, // Safe headers only
+  bodyFields: Object.keys(requestBody), // Field names, not values
+});
+```
+
+**Safe to log**: Component names, action names, non-PII IDs, counts, timestamps, status codes, error types
+**Never log**: Emails, usernames, passwords, tokens, API keys, personal data, request/response bodies with PII
+
+### Log Levels by Build Target
+
+| Log Level | Development | Production | Purpose                                     |
+| --------- | ----------- | ---------- | ------------------------------------------- |
+| `debug`   | ✅ Logged   | ❌ Silent  | Development details, state changes          |
+| `info`    | ✅ Logged   | ❌ Silent  | Important flow information                  |
+| `warn`    | ✅ Logged   | ✅ Logged  | Deprecations, fallbacks, recoverable issues |
+| `error`   | ✅ Logged   | ✅ Logged  | Failures requiring attention                |
+| `time`    | ✅ Logged   | ❌ No-op   | Performance timing measurements             |
+| `group`   | ✅ Logged   | ❌ No-op   | Console grouping for organization           |
+
+**Key Points:**
+
+- Only `warn` and `error` logs appear in production builds
+- Timing and grouping functions are no-op in production (zero overhead)
+- Development logs help with debugging but are stripped from production bundles
+
+### Best Practices
+
+1. Use appropriate log levels:
+   - `debug`: Development details, state changes
+   - `info`: Important flow information
+   - `warn`: Deprecations, fallbacks
+   - `error`: Failures requiring attention
+
+2. Always provide context for errors:
+
+   ```typescript
+   logger.error('API request failed', error, {
+     component: 'DetectionsPage',
+     action: 'loadDetections',
+     endpoint: '/api/v2/detections',
+   });
+   ```
+
+3. Use categories that match your module's purpose
+4. Keep production logs minimal (warn/error only)
+
+### Svelte-Specific Patterns
+
+**Avoid redundant environment checks** - Logger handles dev/prod automatically:
+
+```svelte
+<!-- ✅ Do this - logger handles environment -->
+<script>
+  $effect(() => {
+    logger.debug('Component state updated', { state });
+  });
+</script>
+
+<!-- ❌ Don't do this - redundant check -->
+{#if import.meta.env.DEV}
+  {logger.debug('Component state:', state)}
+{/if}
+```
+
+**Move logging out of templates** - Use functions or effects:
+
+```svelte
+<!-- ✅ Log in reactive statements -->
+<script>
+  $effect(() => {
+    if (someCondition) {
+      logger.warn('Unexpected condition', { component: 'MyComponent' });
+    }
+  });
+</script>
+
+<!-- ❌ Don't log in templates -->
+{#if someCondition}
+  {logger.warn('Unexpected condition')}
+  <div>Content</div>
+{/if}
+```
+
+**Provide component context** - Always include component name and action:
+
+```svelte
+<script>
+  import { loggers } from '$lib/utils/logger';
+
+  const logger = loggers.ui;
+
+  async function handleSubmit() {
+    try {
+      await submitData();
+    } catch (error) {
+      logger.error('Form submission failed', error, {
+        component: 'MyForm',
+        action: 'handleSubmit',
+      });
+    }
+  }
+</script>
+```
+
 ## Server-Sent Events (SSE)
 
 Use `reconnecting-eventsource` package for real-time updates with automatic reconnection handling.

frontend/src/App.svelte

@@ -4,6 +4,9 @@
   import DashboardPage from './lib/desktop/features/dashboard/pages/DashboardPage.svelte'; // Keep dashboard for initial load
   import type { Component } from 'svelte';
   import type { BirdnetConfig } from './app.d.ts';
+  import { getLogger } from './lib/utils/logger';
+
+  const logger = getLogger('app');
 
   // Dynamic imports for heavy pages - properly typed component references
   let Analytics = $state<Component | null>(null);
@@ -145,7 +148,11 @@
           break;
       }
     } catch (error) {
-      console.error(`Failed to load component for route "${route}":`, error);
+      logger.error(`Failed to load component for route "${route}"`, error, {
+        component: 'App',
+        action: 'loadComponent',
+        route,
+      });
       // Fall back to generic error page on component load failure
       currentRoute = 'error-generic';
       currentPage = 'error-generic';
@@ -157,7 +164,10 @@
           const module = await import('./lib/desktop/views/GenericErrorPage.svelte');
           GenericErrorPage = module.default;
         } catch (fallbackError) {
-          console.error('Failed to load fallback error component:', fallbackError);
+          logger.error('Failed to load fallback error component', fallbackError, {
+            component: 'App',
+            action: 'loadFallbackError',
+          });
         }
       }
     } finally {

frontend/src/lib/desktop/components/forms/RTSPUrlInput.svelte

@@ -1,5 +1,8 @@
 <script lang="ts">
   import type { RTSPUrl } from '$lib/stores/settings';
+  import { loggers } from '$lib/utils/logger';
+
+  const logger = loggers.ui;
 
   interface Props {
     urls: RTSPUrl[];
@@ -30,6 +33,21 @@
     }
   }
 
+  // Redact credentials from URL for safe logging
+  function redactUrlCredentials(url: string): string {
+    try {
+      const urlObj = new URL(url);
+      if (urlObj.username || urlObj.password) {
+        // Replace credentials with [REDACTED]
+        return url.replace(/(rtsp:\/\/)[^@]+(@)/, '$1[REDACTED]$2');
+      }
+      return url;
+    } catch {
+      // If URL parsing fails, redact anything that looks like credentials
+      return url.replace(/(rtsp:\/\/)[^@]+(@)/, '$1[REDACTED]$2');
+    }
+  }
+
   function addUrl() {
     const trimmedUrl = newUrl.trim();
     if (trimmedUrl && isValidRtspUrl(trimmedUrl)) {
@@ -38,7 +56,11 @@
       newUrl = '';
     } else if (trimmedUrl && !isValidRtspUrl(trimmedUrl)) {
       // URL is not empty but invalid - could add user feedback here
-      console.error('Invalid RTSP URL format:', trimmedUrl); // TODO: Replace with Sentry.io logging
+      logger.error('Invalid RTSP URL format', null, {
+        url: redactUrlCredentials(trimmedUrl),
+        component: 'RTSPUrlInput',
+        action: 'addUrl',
+      });
     }
   }
 

frontend/src/lib/desktop/components/media/AudioPlayer.svelte

@@ -30,6 +30,9 @@
   import { cn } from '$lib/utils/cn.js';
   import { mediaIcons } from '$lib/utils/icons.js';
   import { t } from '$lib/i18n';
+  import { loggers } from '$lib/utils/logger';
+
+  const logger = loggers.audio;
 
   // Web Audio API types - these are built-in browser types
   /* global AudioContext, MediaElementAudioSourceNode, GainNode, DynamicsCompressorNode, BiquadFilterNode, EventListener, ResizeObserver */
@@ -202,8 +205,7 @@
       return audioContext;
       // eslint-disable-next-line no-unused-vars
     } catch (_e) {
-      // eslint-disable-next-line no-console
-      console.warn('Web Audio API is not supported in this browser');
+      logger.warn('Web Audio API is not supported in this browser');
       audioContextAvailable = false;
       audioContextError =
         'Advanced audio features (volume control, filtering) are not available in this browser.';
@@ -264,7 +266,7 @@
         await audioElement.play();
       }
     } catch (err) {
-      console.error('Error playing audio:', err);
+      logger.error('Error playing audio:', err);
       error = 'Failed to play audio';
     }
   };
@@ -464,8 +466,8 @@
         // eslint-disable-next-line no-unused-vars
       } catch (_e) {
         // Nodes may already be disconnected, ignore errors
-        // eslint-disable-next-line no-console
-        console.warn('Error disconnecting audio nodes during cleanup');
+
+        logger.warn('Error disconnecting audio nodes during cleanup');
       }
       audioNodes = null;
     }
@@ -477,8 +479,8 @@
         // eslint-disable-next-line no-unused-vars
       } catch (_e) {
         // Context may already be closed, ignore errors
-        // eslint-disable-next-line no-console
-        console.warn('Error closing audio context during cleanup');
+
+        logger.warn('Error closing audio context during cleanup');
       }
       audioContext = null;
     }

frontend/src/lib/desktop/components/ui/AudioLevelIndicator.svelte

@@ -2,6 +2,9 @@
   import { cn } from '$lib/utils/cn';
   import ReconnectingEventSource from 'reconnecting-eventsource';
   import { mediaIcons } from '$lib/utils/icons';
+  import { loggers } from '$lib/utils/logger';
+
+  const logger = loggers.audio;
 
   interface AudioLevelData {
     level: number;
@@ -180,7 +183,7 @@
       });
 
       eventSource.onopen = () => {
-        console.log('Audio level SSE connection opened');
+        logger.debug('Audio level SSE connection opened');
       };
 
       eventSource.onmessage = event => {
@@ -226,17 +229,17 @@
             });
           }
         } catch (error) {
-          console.error('Failed to parse audio level data:', error);
+          logger.error('Failed to parse audio level data:', error);
         }
       };
 
       eventSource.onerror = (error: Event) => {
-        console.error('Audio level SSE error:', error);
+        logger.error('Audio level SSE error:', error);
         // ReconnectingEventSource handles reconnection automatically
         // No need for manual reconnection logic
       };
     } catch (error) {
-      console.error('Failed to create ReconnectingEventSource:', error);
+      logger.error('Failed to create ReconnectingEventSource:', error);
       // Try again in 5 seconds if initial setup fails
       globalThis.setTimeout(() => setupEventSource(), 5000);
     }

frontend/src/lib/desktop/components/ui/ErrorAlert.svelte

@@ -4,6 +4,9 @@
   import type { Snippet } from 'svelte';
   import type { HTMLAttributes } from 'svelte/elements';
   import { t } from '$lib/i18n';
+  import { loggers } from '$lib/utils/logger';
+
+  const logger = loggers.ui;
 
   type AlertType = AlertIconType;
 
@@ -44,7 +47,7 @@
     try {
       onDismiss();
     } catch (error) {
-      console.error('Error occurred in ErrorAlert onDismiss callback:', error);
+      logger.error('Error occurred in ErrorAlert onDismiss callback:', error);
     }
   }
 </script>