Logger Usage Rules for Flutter App

Overview

This project uses a custom Logger class instead of

print()

and

debugPrint()

statements. The logger provides structured, categorized, and colorized logging with different levels and categories.

Import Statement

Always import the logger at the top of your files:

import 'package:pupilica_hackathon/core/helpers/logger/logger.dart';

When to Use Logger Instead of print/debugPrint

✅ ALWAYS Use Logger For:

Debugging Information
- Variable values during development
- Function entry/exit points
- State changes in BLoC
- API request/response data
Error Handling
- Exception catching and logging
- API errors
- Validation failures
- System errors
User Flow Tracking
- Navigation events
- Button clicks
- Form submissions
- Authentication events
Performance Monitoring
- Function execution times
- API response times
- Memory usage warnings
Business Logic Events
- OCR processing results
- Data processing steps
- Feature usage tracking

❌ NEVER Use print/debugPrint For:

Production Code - Logger provides better control
Structured Data - Logger handles JSON/Map formatting
Error Context - Logger includes stack traces
Categorized Logs - Logger provides category-based filtering
Colorized Output - Logger provides visual distinction

Logger Methods and Usage

1. Debug Logging

// For development debugging
Logger.debug('User tapped login button', category: LogCategory.ui);
Logger.debug('API response received', category: LogCategory.api, data: {'status': 200, 'data': responseData});

2. Info Logging

// For general information
Logger.info('User successfully logged in', category: LogCategory.auth);
Logger.info('Navigation to home screen', category: LogCategory.navigation);

3. Warning Logging

// For potential issues
Logger.warning('API response time exceeded 5 seconds', category: LogCategory.api);
Logger.warning('Low memory detected', category: LogCategory.general);

4. Error Logging

// For errors and exceptions
try {
  // Some operation
} catch (e, stackTrace) {
  Logger.error('Failed to process OCR image', 
    category: LogCategory.ocr, 
    error: e, 
    stackTrace: stackTrace);
}

// For API errors
Logger.error('Login failed', 
  category: LogCategory.auth, 
  data: {'error_code': 401, 'message': 'Invalid credentials'});

5. Success Logging

// For successful operations
Logger.success('OCR processing completed successfully', category: LogCategory.ocr);
Logger.success('Data saved to database', category: LogCategory.database);

Log Categories

Use appropriate categories for better log organization:

```
LogCategory.splash
```
- Splash screen related logs
```
LogCategory.navigation
```
- Navigation and routing logs
```
LogCategory.api
```
- API calls and responses
```
LogCategory.database
```
- Database operations
```
LogCategory.ui
```
- UI interactions and state changes
```
LogCategory.auth
```
- Authentication and authorization
```
LogCategory.ocr
```
- OCR processing and image analysis
```
LogCategory.general
```
- General purpose logs

Code Examples

BLoC Event Handling

// ❌ Wrong - using print
Future<FutureOr<void>> _onLoginEvent(
  LoginEvent event,
  Emitter<LoginState> emit,
) async {
  print('Login event received'); // ❌ Don't use print
  // ... logic
}

// ✅ Correct - using Logger
Future<FutureOr<void>> _onLoginEvent(
  LoginEvent event,
  Emitter<LoginState> emit,
) async {
  Logger.info('Login event received', category: LogCategory.auth);
  // ... logic
}

Error Handling

// ❌ Wrong - using print for errors
try {
  await apiCall();
} catch (e) {
  print('Error: $e'); // ❌ Don't use print for errors
}

// ✅ Correct - using Logger
try {
  await apiCall();
} catch (e, stackTrace) {
  Logger.error('API call failed', 
    category: LogCategory.api, 
    error: e, 
    stackTrace: stackTrace);
}

UI State Changes

// ❌ Wrong - using debugPrint
void _onButtonPressed() {
  debugPrint('Button pressed'); // ❌ Don't use debugPrint
  setState(() {
    // state change
  });
}

// ✅ Correct - using Logger
void _onButtonPressed() {
  Logger.debug('Button pressed', category: LogCategory.ui);
  setState(() {
    // state change
  });
}

API Response Logging

// ❌ Wrong - using print
Future<ApiResponse> fetchData() async {
  print('Fetching data from API'); // ❌ Don't use print
  final response = await http.get(uri);
  print('Response: ${response.body}'); // ❌ Don't use print
  return ApiResponse.fromJson(jsonDecode(response.body));
}

// ✅ Correct - using Logger
Future<ApiResponse> fetchData() async {
  Logger.info('Fetching data from API', category: LogCategory.api);
  final response = await http.get(uri);
  Logger.debug('API response received', 
    category: LogCategory.api, 
    data: {'status_code': response.statusCode, 'body_length': response.body.length});
  return ApiResponse.fromJson(jsonDecode(response.body));
}

Best Practices

1. Consistent Category Usage

Always use the most specific category
Group related logs under the same category
Use
```
LogCategory.general
```
only when no other category fits

2. Meaningful Messages

// ❌ Poor message
Logger.debug('test', category: LogCategory.general);

// ✅ Good message
Logger.debug('User profile loaded successfully', category: LogCategory.ui);

3. Structured Data

// ✅ Include relevant data for debugging
Logger.debug('OCR processing started', 
  category: LogCategory.ocr, 
  data: {
    'image_size': '${image.width}x${image.height}',
    'processing_time': '${DateTime.now().millisecondsSinceEpoch}'
  });

4. Error Context

// ✅ Always include error and stack trace for exceptions
try {
  // risky operation
} catch (e, stackTrace) {
  Logger.error('Operation failed', 
    category: LogCategory.general, 
    error: e, 
    stackTrace: stackTrace,
    data: {'operation': 'data_processing', 'user_id': userId});
}

5. Performance Logging

// ✅ Log performance metrics
final stopwatch = Stopwatch()..start();
// ... operation
stopwatch.stop();
Logger.info('Operation completed', 
  category: LogCategory.general, 
  data: {'duration_ms': stopwatch.elapsedMilliseconds});

Migration Guidelines

When refactoring existing code:

Find all print/debugPrint statements
Determine the appropriate log level (debug, info, warning, error, success)
Choose the right category based on context
Add structured data if relevant
Include error handling for try-catch blocks

Development vs Production

Development: Use all log levels liberally for debugging
Production: Consider removing or reducing debug logs
Error logs: Always keep in production for monitoring
Info logs: Keep important business logic logs

Log Output Format

The logger provides structured output with:

Timestamp
App name
Category emoji and name
Level emoji and name
Message
Additional data (if provided)
Color coding for different levels

Example output:

[2024-01-15T10:30:45.123Z] Pupilica AI 🚀 SPLASH ℹ️ INFO: Splash screen initialized
[2024-01-15T10:30:45.456Z] Pupilica AI 🌐 API 🐛 DEBUG: API request sent | Data: {url: /api/login, method: POST}

This structured approach makes debugging much more efficient and provides better insights into application behavior.

Logger Usage Rules for Flutter App

Overview

This project uses a custom Logger class instead of

print()

and

debugPrint()

statements. The logger provides structured, categorized, and colorized logging with different levels and categories.

Import Statement

Always import the logger at the top of your files:

import 'package:pupilica_hackathon/core/helpers/logger/logger.dart';

When to Use Logger Instead of print/debugPrint

✅ ALWAYS Use Logger For:

Debugging Information
- Variable values during development
- Function entry/exit points
- State changes in BLoC
- API request/response data
Error Handling
- Exception catching and logging
- API errors
- Validation failures
- System errors
User Flow Tracking
- Navigation events
- Button clicks
- Form submissions
- Authentication events
Performance Monitoring
- Function execution times
- API response times
- Memory usage warnings
Business Logic Events
- OCR processing results
- Data processing steps
- Feature usage tracking

❌ NEVER Use print/debugPrint For:

Production Code - Logger provides better control
Structured Data - Logger handles JSON/Map formatting
Error Context - Logger includes stack traces
Categorized Logs - Logger provides category-based filtering
Colorized Output - Logger provides visual distinction

Logger Methods and Usage

1. Debug Logging

// For development debugging
Logger.debug('User tapped login button', category: LogCategory.ui);
Logger.debug('API response received', category: LogCategory.api, data: {'status': 200, 'data': responseData});

2. Info Logging

// For general information
Logger.info('User successfully logged in', category: LogCategory.auth);
Logger.info('Navigation to home screen', category: LogCategory.navigation);

3. Warning Logging

// For potential issues
Logger.warning('API response time exceeded 5 seconds', category: LogCategory.api);
Logger.warning('Low memory detected', category: LogCategory.general);

4. Error Logging

// For errors and exceptions
try {
  // Some operation
} catch (e, stackTrace) {
  Logger.error('Failed to process OCR image', 
    category: LogCategory.ocr, 
    error: e, 
    stackTrace: stackTrace);
}

// For API errors
Logger.error('Login failed', 
  category: LogCategory.auth, 
  data: {'error_code': 401, 'message': 'Invalid credentials'});

5. Success Logging

// For successful operations
Logger.success('OCR processing completed successfully', category: LogCategory.ocr);
Logger.success('Data saved to database', category: LogCategory.database);

Log Categories

Use appropriate categories for better log organization:

```
LogCategory.splash
```
- Splash screen related logs
```
LogCategory.navigation
```
- Navigation and routing logs
```
LogCategory.api
```
- API calls and responses
```
LogCategory.database
```
- Database operations
```
LogCategory.ui
```
- UI interactions and state changes
```
LogCategory.auth
```
- Authentication and authorization
```
LogCategory.ocr
```
- OCR processing and image analysis
```
LogCategory.general
```
- General purpose logs

Code Examples

BLoC Event Handling

// ❌ Wrong - using print
Future<FutureOr<void>> _onLoginEvent(
  LoginEvent event,
  Emitter<LoginState> emit,
) async {
  print('Login event received'); // ❌ Don't use print
  // ... logic
}

// ✅ Correct - using Logger
Future<FutureOr<void>> _onLoginEvent(
  LoginEvent event,
  Emitter<LoginState> emit,
) async {
  Logger.info('Login event received', category: LogCategory.auth);
  // ... logic
}

Error Handling

// ❌ Wrong - using print for errors
try {
  await apiCall();
} catch (e) {
  print('Error: $e'); // ❌ Don't use print for errors
}

// ✅ Correct - using Logger
try {
  await apiCall();
} catch (e, stackTrace) {
  Logger.error('API call failed', 
    category: LogCategory.api, 
    error: e, 
    stackTrace: stackTrace);
}

UI State Changes

// ❌ Wrong - using debugPrint
void _onButtonPressed() {
  debugPrint('Button pressed'); // ❌ Don't use debugPrint
  setState(() {
    // state change
  });
}

// ✅ Correct - using Logger
void _onButtonPressed() {
  Logger.debug('Button pressed', category: LogCategory.ui);
  setState(() {
    // state change
  });
}

API Response Logging

// ❌ Wrong - using print
Future<ApiResponse> fetchData() async {
  print('Fetching data from API'); // ❌ Don't use print
  final response = await http.get(uri);
  print('Response: ${response.body}'); // ❌ Don't use print
  return ApiResponse.fromJson(jsonDecode(response.body));
}

// ✅ Correct - using Logger
Future<ApiResponse> fetchData() async {
  Logger.info('Fetching data from API', category: LogCategory.api);
  final response = await http.get(uri);
  Logger.debug('API response received', 
    category: LogCategory.api, 
    data: {'status_code': response.statusCode, 'body_length': response.body.length});
  return ApiResponse.fromJson(jsonDecode(response.body));
}

Best Practices

1. Consistent Category Usage

Always use the most specific category
Group related logs under the same category
Use
```
LogCategory.general
```
only when no other category fits

2. Meaningful Messages

// ❌ Poor message
Logger.debug('test', category: LogCategory.general);

// ✅ Good message
Logger.debug('User profile loaded successfully', category: LogCategory.ui);

3. Structured Data

// ✅ Include relevant data for debugging
Logger.debug('OCR processing started', 
  category: LogCategory.ocr, 
  data: {
    'image_size': '${image.width}x${image.height}',
    'processing_time': '${DateTime.now().millisecondsSinceEpoch}'
  });

4. Error Context

// ✅ Always include error and stack trace for exceptions
try {
  // risky operation
} catch (e, stackTrace) {
  Logger.error('Operation failed', 
    category: LogCategory.general, 
    error: e, 
    stackTrace: stackTrace,
    data: {'operation': 'data_processing', 'user_id': userId});
}

5. Performance Logging

// ✅ Log performance metrics
final stopwatch = Stopwatch()..start();
// ... operation
stopwatch.stop();
Logger.info('Operation completed', 
  category: LogCategory.general, 
  data: {'duration_ms': stopwatch.elapsedMilliseconds});

Migration Guidelines

When refactoring existing code:

Find all print/debugPrint statements
Determine the appropriate log level (debug, info, warning, error, success)
Choose the right category based on context
Add structured data if relevant
Include error handling for try-catch blocks

Development vs Production

Development: Use all log levels liberally for debugging
Production: Consider removing or reducing debug logs
Error logs: Always keep in production for monitoring
Info logs: Keep important business logic logs

Log Output Format

The logger provides structured output with:

Timestamp
App name
Category emoji and name
Level emoji and name
Message
Additional data (if provided)
Color coding for different levels

Example output:

[2024-01-15T10:30:45.123Z] Pupilica AI 🚀 SPLASH ℹ️ INFO: Splash screen initialized
[2024-01-15T10:30:45.456Z] Pupilica AI 🌐 API 🐛 DEBUG: API request sent | Data: {url: /api/login, method: POST}

This structured approach makes debugging much more efficient and provides better insights into application behavior.

Logger Usage Rules for Flutter App

Related Skills

Repo rules

.cursorrules

This is an Elixir library that recompiles Elixir code in its AST form.