# logback-android [](https://github.com/tony19/logback-android/releases/) <a href="https://android-arsenal.com/api?level=21"><img alt="API" src="https://img.shields.io/badge/API-21%2B-brightgreen.svg?style=flat"/></a> [](https://github.com/tony19/logback-android/actions/workflows/build.yml) [](https://github.com/tony19/logback-android/actions/workflows/codeql.yml)
## Overview
`logback-android` is a lite version of [`logback`](http://logback.qos.ch) 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](https://github.com/tony19/logback-android/wiki) for documentation.
*For `logback-android@1.x`, see the [`1.x` branch](https://github.com/tony19/logback-android/tree/1.x).*
## 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](http://developer.android.com/sdk/index.html).
2. In `app/build.gradle`, add the following dependencies:
```groovy
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](https://github.com/tony19/logback-android/issues/151#issuecomment-466276739), **or** use this config instead:
```groovy
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:
```xml
<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:
```java
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
```
5. ...and modify `onOptionsItemSelected()` to log "hello world":
```java
@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](https://github.com/tony19/logback-android/wiki#special-properties-for-xml-config) the code requires
access to an Android [Context](https://developer.android.com/reference/android/content/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](https://developer.android.com/guide/app-compatibility/restrictions-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:
```java
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.
```java
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](https://developer.android.com/reference/android/content/Context#getApplicationContext()).
## Download
_Gradle_ **release**
```groovy
dependencies {
implementation 'org.slf4j:slf4j-api:2.0.7'
implementation 'com.github.tony19:logback-android:3.0.0'
}
```
_Gradle_ **snapshot (unstable)**
```groovy
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:
```sh
./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:
```properties
# 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:
```sh
./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/.