Android Log Collection (Kotlin) - Logs Monitoring

The Atatus mobile SDK lets you send logs from your native Android and Android TV applications directly to Atatus. Logs are sent over HTTP, batched on the device, and can be enriched with attributes and tags and correlated with your RUM sessions.

Prerequisites

The Atatus SDK is initialized in your application. See Android (Kotlin) setup for the initialization steps.
A RUM application created in Atatus, which gives you a License Key.

Note: The SDK requires a License Key. Do not use your account API key in a mobile application, because it would be exposed in the application's byte code.

Setup

1. Add the Logs Dependency

Add the Atatus logs library to your application module's build.gradle:

copy

dependencies {
    implementation("com.atatus.android:atatus-android-logs:1.+")
}

2. Initialize the SDK

Initialize the SDK in your Application class, as described in Android (Kotlin) setup:

copy

import android.app.Application
import com.atatus.android.Atatus
import com.atatus.android.core.configuration.Configuration
import com.atatus.android.privacy.TrackingConsent

class SampleApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        val configuration = Configuration.Builder(
            licenseKey = "<LICENSE_KEY>",
            env = "<ENV_NAME>",
            variant = "<APP_VARIANT_NAME>"
        )
            .build()

        Atatus.initialize(this, configuration, TrackingConsent.GRANTED)
    }
}

You can verify the SDK is ready before sending logs:

copy

if (Atatus.isInitialized()) {
    // Your code here
}

3. Enable the Logs Feature

After the SDK is initialized, enable the Logs feature:

copy

import com.atatus.android.log.Logs
import com.atatus.android.log.LogsConfiguration

val logsConfiguration = LogsConfiguration.Builder().build()
Logs.enable(logsConfiguration)

4. Create a Logger

Create a Logger instance to send logs. Configure it with the options that fit your needs:

copy

import com.atatus.android.log.Logger

val logger = Logger.Builder()
    .setNetworkInfoEnabled(true)
    .setLogcatLogsEnabled(true)
    .setBundleWithRumEnabled(true)
    .setRemoteSampleRate(100f)
    .setName("<LOGGER_NAME>")
    .build()

Logger.Builder options:

Option	Description
`setNetworkInfoEnabled(true)`	Adds network connectivity attributes (carrier, connection type) to each log.
`setLogcatLogsEnabled(true)`	Also writes logs to Logcat, so they appear in your local console.
`setBundleWithRumEnabled(true)`	Links logs to the current RUM context so you can pivot between logs and sessions.
`setRemoteSampleRate(100f)`	Percentage of logs sent to Atatus, from `0f` to `100f`. Defaults to `100f`.
`setName("<LOGGER_NAME>")`	Sets the logger name attribute.
`setService("<SERVICE_NAME>")`	Sets the service name attribute.

5. Send Log Messages

Use the logger to send messages at the level you need:

copy

logger.d("A debug message.")
logger.i("Some relevant information.")
logger.w("An important warning.")
logger.e("An error was met!")
logger.wtf("What a terrible failure!")

Attach a Throwable to capture an exception with its stack trace:

copy

try {
    doSomething()
} catch (e: IOException) {
    logger.e("Error while doing something", e)
}

Attach custom attributes to a single log entry:

copy

logger.i("onPageStarted", attributes = mapOf("http.url" to url))

6. Add Global Attributes and Tags

Attributes are key-value pairs attached to your logs. Add an attribute to a single logger, or to all loggers through the Logs feature:

copy

// Added to every log sent by this logger
logger.addAttribute("version_name", BuildConfig.VERSION_NAME)

// Added to every log sent by all loggers
Logs.addAttribute("version_code", BuildConfig.VERSION_CODE)

Tags help you filter and group your logs in Atatus:

copy

logger.addTag("build_type", BuildConfig.BUILD_TYPE)
logger.addTag("device", "android")

Remove attributes and tags when you no longer need them:

copy

logger.removeAttribute("version_name")
Logs.removeAttribute("version_code")
logger.removeTagsWithKey("build_type")

7. Sending Data When the Device Is Offline

Logs are batched locally and sent to Atatus when network availability and battery levels permit. Even if your users open the application while offline, no data is lost. Batches are uploaded once connectivity is restored, and old data automatically expires to keep disk usage bounded.

Next Steps

Set up RUM for Android (Kotlin) to track views, actions, and errors.
Collect logs from your cross-platform apps with Flutter Log Collection.
Explore your logs in Logs Monitoring.