Andromind Logger

A comprehensive, thread-safe logging library for Android applications that provides flexible, extensible logging capabilities with multiple output destinations and context support.

Features

• Multiple Log Levels: VERBOSE, DEBUG, INFO, WARN, ERROR, and ASSERT levels
• Thread Safety: All operations are thread-safe and support concurrent access
• Multiple Writers: Support for simultaneous output to multiple destinations
• Context Support: Thread-local context for adding metadata to log messages
• Automatic Resource Management: Proper handling of writer lifecycles
• Extensible: Easy to add custom log writers for different output destinations
• Error Handling: Comprehensive error handling and recovery mechanisms
• Performance Optimized: Minimal overhead and efficient resource usage

Installation

Gradle

Add the following to your app's build.gradle:

dependencies {
    implementation 'io.github.andromind:logger:1.0.0-alpha'
}

Maven

<dependency>
    <groupId>io.github.andromind</groupId>
    <artifactId>logger</artifactId>
    <version>1.0.0-alpha</version>
</dependency>

Basic Usage

Initialization

Initialize the logger at application startup:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Logger.init(); // Initializes with default LogcatWriter
    }
}

Simple Logging

// Log messages at different levels
Logger.v("TAG", "Verbose message");
Logger.d("TAG", "Debug message");
Logger.i("TAG", "Info message");
Logger.w("TAG", "Warning message");
Logger.e("TAG", "Error message");
Logger.wtf("TAG", "Assert message");

// Log exceptions
try {
    // Some code that might throw
} catch (Exception e) {
    Logger.e("TAG", "Operation failed", e);
}

Using Context

// Add context data
Logger.putContext("userId", "12345");
Logger.putContext("sessionId", "abc-xyz");

// Log with context (context will be automatically included)
Logger.i("TAG", "User action performed");
// Output: "2025-01-02 10:30:45 I/TAG [main] {userId=12345, sessionId=abc-xyz}: User action performed"

// Clear specific context
Logger.removeContext("sessionId");

// Clear all context
Logger.clearContext();

Advanced Usage

Custom Log Writers

Create custom writers by implementing the LogWriter interface:

public class CustomWriter implements LogWriter {
    @Override
    public void write(@NonNull String message) {
        // Custom writing logic
    }

    @Override
    public void close() {
        // Cleanup resources
    }
}

// Add the custom writer
Logger.addWriter(new CustomWriter());

File Logging

File logFile = new File(getExternalFilesDir(null), "app.log");
Logger.addWriter(new FileLogWriter(logFile));

Network Logging

String serverUrl = "https://logging.yourserver.com/logs";
Logger.addWriter(new ServerLogWriter(serverUrl));

Setting Log Level

// Set minimum log level
Logger.setLogLevel(Logger.INFO);  // Ignore VERBOSE and DEBUG messages

Shutdown

// Properly shutdown the logger
@Override
public void onDestroy() {
    Logger.shutdown();
    super.onDestroy();
}

Built-in Writers

LogcatWriter

Writes logs to Android's Logcat system. This is the default writer.

FileLogWriter

Writes logs to a specified file with proper file handling and rotation support.

ServerLogWriter

Sends logs to a remote server using HTTP POST requests with automatic retry and error handling.

Best Practices

1. Initialize Early:

   • Initialize the logger in your Application class
   • Configure all writers during initialization

2. Use Appropriate Log Levels:

   • VERBOSE: Detailed development logs
   • DEBUG: Debugging information
   • INFO: General information
   • WARN: Warnings and potential issues
   • ERROR: Errors and exceptions
   • ASSERT: Critical issues

3. Context Usage:

   • Use context for important metadata
   • Clear context when no longer needed
   • Keep context data concise

4. Resource Management:

   • Always call Logger.shutdown() when the app is terminating
   • Properly handle writer lifecycles
   • Use flush() when immediate writing is required

5. Error Handling:

   • Always include stack traces with exceptions
   • Use meaningful tags for easy filtering
   • Include relevant context in error messages

Thread Safety

The library is thread-safe and handles concurrent access properly:

• Multiple threads can log simultaneously
• Context is thread-local and isolated
• Writer management is synchronized
• Resource cleanup is atomic

Performance Considerations

• Context operations are thread-local and have minimal overhead
• Writers are managed in a CopyOnWriteArrayList for concurrent access
• Message formatting is optimized for minimal object creation
• Failed writers are automatically removed to prevent bottlenecks

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please:

1. Check the documentation
2. Search existing issues
3. Create a new issue if needed

Version History

• 1.0.0-alpha (2025-01-02)
  • Initial release
  • Core logging functionality
  • Multiple writer support
  • Context support
  • Thread safety improvements

Credits

Developed by the Andromind Development Team.