crowd-funder-for-time-pwa/docs/development/debug-logging.md

# Debug Logging Control

## Overview

Debug logging in TimeSafari can be controlled via environment variables to reduce console noise during development and production.

## Current Behavior

By default, debug logging is **disabled** to reduce console noise. Debug logs are very verbose and include detailed information about:

- Camera operations (ImageMethodDialog, PhotoDialog)
- Database operations (CapacitorPlatformService)
- QR Scanner operations
- Platform service operations
- Component lifecycle events

## How to Enable Debug Logging

### Option 1: Environment Variable (Recommended)

Set the `VITE_DEBUG_LOGGING` environment variable to `true`:

```bash
# For development
VITE_DEBUG_LOGGING=true npm run dev

# For web builds
VITE_DEBUG_LOGGING=true npm run build:web:dev

# For Electron builds
VITE_DEBUG_LOGGING=true npm run build:electron:dev
```

### Option 2: .env File

Create or modify `.env.local` file:

```bash
# Enable debug logging
VITE_DEBUG_LOGGING=true
```

### Option 3: Package.json Scripts

Add debug variants to your package.json scripts:

```json
{
  "scripts": {
    "dev:debug": "VITE_DEBUG_LOGGING=true npm run dev",
    "build:web:debug": "VITE_DEBUG_LOGGING=true npm run build:web:dev",
    "build:electron:debug": "VITE_DEBUG_LOGGING=true npm run build:electron:dev"
  }
}
```

## Debug Logging Rules

Debug logging follows these rules:

1. **Only shows in development mode** (not production)
2. **Only shows for web platform** (not Electron)
3. **Must be explicitly enabled** via `VITE_DEBUG_LOGGING=true`
4. **Never logged to database** (to reduce noise)
5. **Very verbose** - includes detailed component state and operations

## Components with Debug Logging

The following components include debug logging:

- **ImageMethodDialog.vue** - Camera operations, preview state
- **PhotoDialog.vue** - Camera operations, video setup
- **AmountInput.vue** - Input validation, increment/decrement
- **GiftedDialog.vue** - Amount updates, form state
- **CapacitorPlatformService.ts** - Database operations, migrations
- **QRScanner services** - Camera permissions, scanner state
- **PlatformServiceMixin.ts** - Service initialization

## Example Debug Output

When enabled, you'll see output like:

```
[ImageMethodDialog] open called
[ImageMethodDialog] Camera facing mode: user
[ImageMethodDialog] Should mirror video: true
[ImageMethodDialog] Platform capabilities: {isMobile: false, hasCamera: true}
[ImageMethodDialog] Starting camera preview from open()
[ImageMethodDialog] startCameraPreview called
[ImageMethodDialog] Current showCameraPreview state: true
[ImageMethodDialog] MediaDevices available: true
[ImageMethodDialog] getUserMedia constraints: {video: {facingMode: "user"}}
[ImageMethodDialog] Setting video element srcObject
[ImageMethodDialog] Video metadata loaded, starting playback
[ImageMethodDialog] Video element started playing successfully
```

## Disabling Debug Logging

To disable debug logging:

1. **Remove the environment variable:**
   ```bash
   unset VITE_DEBUG_LOGGING
   ```

2. **Or set it to false:**
   ```bash
   VITE_DEBUG_LOGGING=false npm run dev
   ```

3. **Or remove from .env file:**
   ```bash
   # Comment out or remove this line
   # VITE_DEBUG_LOGGING=true
   ```

## Production Behavior

In production builds, debug logging is **always disabled** regardless of the environment variable setting. This ensures:

- No debug output in production
- No performance impact from debug logging
- Clean console output for end users

## Troubleshooting

### Debug Logging Not Working

1. **Check environment variable:**
   ```bash
   echo $VITE_DEBUG_LOGGING
   ```

2. **Verify it's set to "true":**
   ```bash
   VITE_DEBUG_LOGGING=true npm run dev
   ```

3. **Check if you're in development mode:**
   - Debug logging only works in development (`NODE_ENV !== "production"`)
   - Production builds always disable debug logging

### Too Much Debug Output

If debug logging is too verbose:

1. **Disable it completely:**
   ```bash
   unset VITE_DEBUG_LOGGING
   ```

2. **Or modify specific components** to use `logger.log` instead of `logger.debug`

3. **Or add conditional logging** in components:
   ```typescript
   if (process.env.VITE_DEBUG_LOGGING === "true") {
     logger.debug("Detailed debug info");
   }
   ```

## Best Practices

1. **Use debug logging sparingly** - only for troubleshooting
2. **Disable in production** - debug logging is automatically disabled
3. **Use specific component prefixes** - makes it easier to filter output
4. **Consider log levels** - use `logger.log` for important info, `logger.debug` for verbose details
5. **Test without debug logging** - ensure your app works without debug output

## Future Improvements

Potential enhancements to the debug logging system:

1. **Component-specific debug flags** - enable debug for specific components only
2. **Log level filtering** - show only certain types of debug messages
3. **Debug UI panel** - in-app debug information display
4. **Structured logging** - JSON format for better parsing
5. **Performance monitoring** - track impact of debug logging