logback-android

Overview

logback-android is a lite version of logback that runs on Android. This library provides a highly configurable logging framework for Android apps, supporting multiple log destinations simultaneously:

• files
• SQLite databases
• logcat
• sockets
• syslog
• email

See Wiki for documentation.

For logback-android@1.x, see the 1.x branch.

JDK-specific builds

logback-android is published as JDK-specific artifacts instead of a single lowest-common-denominator build:

Artifact	Bytecode	minSdk
com.github.tony19:logback-android	Java 11	26 (Android 8.0)
com.github.tony19:logback-android-jdk8	Java 8	21 (Android 5.0)

Use logback-android unless your app must support devices older than Android 8.0, in which case use logback-android-jdk8.

Quick Start

1. Create a new "Basic Activity" app in Android Studio.

2. In app/build.gradle, add the following dependencies:

   dependencies {
     implementation 'org.slf4j:slf4j-api:2.0.7'
     implementation 'com.github.tony19:logback-android:3.0.0'
   }
   

   If using logback-android in unit tests, either use Robolectric, or use this config instead:

   dependencies {
     implementation 'org.slf4j:slf4j-api:2.0.7'
     implementation 'com.github.tony19:logback-android:3.0.0'
     testImplementation 'ch.qos.logback:logback-classic:1.2.11'
   }
   
   configurations.testImplementation {
     exclude module: 'logback-android'
   }
   

3. Create app/src/main/assets/logback.xml containing:

   <configuration
     xmlns="https://tony19.github.io/logback-android/xml"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="https://tony19.github.io/logback-android/xml https://cdn.jsdelivr.net/gh/tony19/logback-android/logback.xsd"
   >
     <appender name="logcat" class="ch.qos.logback.classic.android.LogcatAppender">
       <tagEncoder>
         <pattern>%logger{12}</pattern>
       </tagEncoder>
       <encoder>
         <pattern>[%-20thread] %msg</pattern>
       </encoder>
     </appender>
   
     <root level="DEBUG">
       <appender-ref ref="logcat" />
     </root>
   </configuration>
   

4. In MainActivity.java, add the following imports:

   import org.slf4j.Logger;
   import org.slf4j.LoggerFactory;
   

5. ...and modify onOptionsItemSelected() to log "hello world":

   @Override
   public boolean onOptionsItemSelected(MenuItem item) {
       Logger log = LoggerFactory.getLogger(MainActivity.class);
       log.info("hello world");
       // ...
   }
   

6. Build and start the app.

7. Open logcat for your device (via the Android Monitor tab in Android Studio).

8. Click the app menu, and select the menu-option. You should see "hello world" in logcat.

Providing Android context externally

In order to support various special properties the code requires access to an Android Context instance. By default, the framework uses a workaround based on reflection that seems to work for the time being. However, in view of Google's restrictions on non-SDK interfaces this code might not work anymore. Therefore, the framework provides a special API that enables the application to provide an Android context instance that will be used instead of the workaround. Note: the context instance must be provided before it is needed by the framework, so the best place for it would be in the application's onCreate callback:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // Assuming no logging occurs before this
        AndroidContextUtil.setApplicationContext(this);
    }
}

If an earlier initialization is required, then one might consider overriding attachBaseContext, although at this stage the context instance might not be fully initialized. This might be good enough though if by the time the context is used by the framework it becomes fully initialized.

public class MyApplication extends Application {

    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        AndroidContextUtil.setApplicationContext(base);
    }
}

Note: despite the fact that the method is called setApplicationContext - the user may use any ContextWrapper component (Application, Activity, Service) - the framework will actually use the "pure" application context.

Download

Gradle release

dependencies {
  implementation 'org.slf4j:slf4j-api:2.0.7'
  implementation 'com.github.tony19:logback-android:3.0.0'
}

Gradle snapshot (unstable)

repositories {
  maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
}

dependencies {
  implementation 'org.slf4j:slf4j-api:2.0.7'
  implementation 'com.github.tony19:logback-android:3.0.1-SNAPSHOT'
}

Build

Use these commands to create the AAR:

git clone git://github.com/tony19/logback-android.git
cd logback-android
scripts/makejar.sh

The file is output to:

./build/logback-android-3.0.0-debug.aar

Release

1. Make sure local.properties contains the following keys, required to sign artifacts and upload to Maven Central:

   # output from `gpg --export-secret-keys <PUBKEY_LAST8> | base64`
   signing.key=
   # PUBKEY_LAST8 from `gpg --list-keys` (last 8 digits of pub key)
   signing.keyId=
   # password for key (can be empty if key has no password)
   signing.password=
   # path to secring.gpg file from `gpg --keyring secring.gpg --export-secret-keys > ~/.gnupg/secring.gpg`
   signing.secretKeyRingFile=/Users/tony/.gnupg/secring.gpg
   # OSS sonatype username at https://issues.sonatype.org
   ossrhUsername=
   # OSS sonatype password at https://issues.sonatype.org
   ossrhPassword=
   # profile ID from https://oss.sonatype.org/#stagingProfiles (select profile, and copy profile ID from hash in address bar)
   sonatypeStagingProfileId=b2413418ab44f
   

2. Set the release version in gradle.properties (drop the -SNAPSHOT suffix).

3. Build, sign, and upload to a Sonatype staging repository:

   ./gradlew publishToSonatype closeAndReleaseSonatypeStagingRepository
   

4. Tag the release and bump gradle.properties back to the next -SNAPSHOT version.

5. Confirm the artifacts were uploaded in https://repo1.maven.org/maven2/com/github/tony19/logback-android/3.0.0/.