The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
# Android Quick Start
Integrate Traceway into your native Android application with the [`com.tracewayapp:traceway`](https://central.sonatype.com/artifact/com.tracewayapp/traceway) library from Maven Central.
## Installation
Add the dependency to your app module's `build.gradle.kts`:
```kotlin
dependencies {
implementation("com.tracewayapp:traceway:1.0.1")
}
```
Maven Central is enabled by default in modern Android projects, so no extra `repositories { ... }` entry is required.
## Setup
Initialize the SDK from your `Application.onCreate()`. This wraps the whole process. Every uncaught exception, on every thread, is captured automatically:
```kotlin
import android.app.Application
import com.tracewayapp.traceway.Traceway
import com.tracewayapp.traceway.TracewayOptions
class MyApp : Application() {
override fun onCreate() {
super.onCreate()
Traceway.init(
application = this,
connectionString = "your-token@https://traceway.example.com/api/report",
options = TracewayOptions(version = "1.0.0"),
)
}
}
```
Register the application class in `AndroidManifest.xml`, or `onCreate()` never runs and the SDK is never initialized:
```xml
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
<application android:name=".MyApp" ...>
...
</application>
</manifest>
```
You do not need to add a permission. The library's own manifest declares `INTERNET` and `ACCESS_NETWORK_STATE`, and the Android manifest merger folds both into your app. Re-declaring `INTERNET` yourself is harmless if your app already has it.
## Capture Errors Manually
```kotlin
import com.tracewayapp.traceway.Traceway
// Capture a caught exception
try {
riskyOperation()
} catch (e: Throwable) {
Traceway.captureException(e)
}
// Capture a message
Traceway.captureMessage("User completed onboarding")
// Force send pending events
Traceway.flush()
```
## With Options
`TracewayOptions` accepts the following parameters. Field names mirror the Flutter SDK so configuration can be ported directly.
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `sampleRate` | `Double` | `1.0` | Event sampling rate (0.0 to 1.0) |
| `debug` | `Boolean` | `false` | Print debug info to logcat |
| `version` | `String` | `""` | App version string |
| `proguardUuid` | `String?` | `null` | R8/ProGuard build UUID for deobfuscating release crashes; set to `BuildConfig.TRACEWAY_PROGUARD_UUID` from the [symbols plugin](/symbolicator/android) |
| `debounceMs` | `Long` | `1500` | Milliseconds before sending batched events |
| `retryDelayMs` | `Long` | `10000` | Retry delay in ms on failed uploads |
| `maxPendingExceptions` | `Int` | `5` | Max exceptions held in memory before oldest is dropped |
| `persistToDisk` | `Boolean` | `true` | Persist pending exceptions to disk so they survive app restarts |
| `maxLocalFiles` | `Int` | `5` | Max exception files stored on disk |
| `localFileMaxAgeHours` | `Int` | `12` | Hours after which unsynced local files are deleted |
| `captureLogs` | `Boolean` | `true` | Mirror every `println` / `System.out` / `System.err` line into the rolling log buffer |
| `captureNetwork` | `Boolean` | `true` | Record network events sent through `TracewayOkHttpInterceptor` |
| `captureNavigation` | `Boolean` | `true` | Record activity push / pop transitions |
| `eventsWindowMs` | `Long` | `10000` | Rolling window kept in the log/action buffers (ms) |
| `eventsMaxCount` | `Int` | `200` | Hard cap applied independently to logs and actions |
| `screenCapture` | `Boolean` | `false` | **No effect on Android**, accepted for API parity |
| `capturePixelRatio` | `Double` | `0.75` | **No effect on Android** |
| `maxBufferFrames` | `Int` | `150` | **No effect on Android** |
| `fps` | `Int` | `15` | **No effect on Android** |
```kotlin
Traceway.init(
application = this,
connectionString = "your-token@https://traceway.example.com/api/report",
options = TracewayOptions(
sampleRate = 0.5,
debug = true,
version = "2.1.0",
debounceMs = 2000,
),
)
```
> **No screen recording.** Unlike the Flutter SDK, the Android library does not record video. The `screenCapture`, `capturePixelRatio`, `maxBufferFrames`, and `fps` options are accepted for API parity but have no effect.
## Logs & Actions
Every captured exception ships with the last ~10 seconds of session context, attached to a `sessionRecordings` entry on the wire, the same shape the Flutter SDK uses (minus the video chunks). Two independent rolling buffers, **logs** and **actions**, are kept in memory, each capped at 200 entries by default.
### Logs
Every `println` and any other write to `System.out` / `System.err` is mirrored into the log buffer. Console output behaves normally; it just gets a copy.
Calls that go straight to `android.util.Log` bypass `System.out` and are **not** captured automatically. To pick up Logcat lines, install a Timber tree (or any other logger) that calls `TracewayClient.instance?.recordLog(message, level)`. Timber is not pulled in by the SDK, so add it yourself with `implementation("com.jakewharton.timber:timber:5.0.1")`:
```kotlin
import android.util.Log
import com.tracewayapp.traceway.TracewayClient
import timber.log.Timber
Timber.plant(object : Timber.Tree() {
override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
val level = when (priority) {
Log.VERBOSE, Log.DEBUG -> "debug"
Log.WARN -> "warn"
Log.ERROR, Log.ASSERT -> "error"
else -> "info"
}
TracewayClient.instance?.recordLog(message, level = level)
}
})
```
### Actions
Three kinds of actions are collected:
- **Network**: every HTTP request routed through an OkHttp client with `TracewayOkHttpInterceptor` installed (method, URL, status, duration, request/response byte counts). Catches Retrofit, Coil, Glide-via-OkHttp, and your own usage:
```kotlin
import com.tracewayapp.traceway.network.TracewayOkHttpInterceptor
import okhttp3.OkHttpClient
val client = OkHttpClient.Builder()
.addInterceptor(TracewayOkHttpInterceptor())
.build()
```
The SDK's only declared dependency is `kotlin-stdlib`, so the interceptor compiles against your app's own OkHttp (`implementation("com.squareup.okhttp3:okhttp:4.12.0")`).
For HTTP clients that aren't OkHttp, record events manually:
```kotlin
import com.tracewayapp.traceway.TracewayClient
import com.tracewayapp.traceway.events.NetworkEvent
TracewayClient.instance?.recordNetworkEvent(
NetworkEvent(method = "GET", url = "https://...", durationMs = 42L, statusCode = 200)
)
```
- **Navigation**: activity `push` / `pop` transitions, recorded automatically once `Traceway.init(...)` runs (the SDK registers an `Application.ActivityLifecycleCallbacks` for you). No wiring needed on your side.
- **Custom**: anything your app records explicitly:
```kotlin
Traceway.recordAction(
category = "cart",
name = "add_item",
data = mapOf("sku" to "SKU-123", "qty" to 2),
)
```
### Wire shape
Logs and actions are sent to the backend inside the same `sessionRecordings` entry that the Flutter SDK uses for video. They're stored under separate `logs` and `actions` arrays. Each recording carries `startedAt` and `endedAt` ISO 8601 timestamps so the backend can align events on a timeline (`offsetIntoVideoMs = event.timestamp − recording.startedAt`):
```json
{
"sessionRecordings": [
{
"exceptionId": "...",
"startedAt": "2026-04-28T14:30:53.011Z",
"endedAt": "2026-04-28T14:31:02.314Z",
"logs": [
{"type": "log", "timestamp": "2026-04-28T14:30:54.508Z", "level": "info", "message": "user tapped pay"}
],
"actions": [
{"type": "navigation", "action": "push", "from": "/", "to": "/cart", "timestamp": "2026-04-28T14:30:53.011Z"},
{"type": "network", "method": "GET", "url": "...", "statusCode": 200, "durationMs": 86, "timestamp": "2026-04-28T14:30:54.422Z"},
{"type": "custom", "category": "cart", "name": "add_item", "data": {"sku": "SKU-1"}, "timestamp": "2026-04-28T14:30:54.605Z"}
]
}
]
}
```
`startedAt` and `endedAt` come from the timestamp range of the buffered events. A session recording entry is created for every captured exception that has any timeline data.
### Disabling channels
Each channel can be turned off individually via `TracewayOptions`:
```kotlin
Traceway.init(
application = this,
connectionString = "your-token@https://traceway.example.com/api/report",
options = TracewayOptions(
captureLogs = false, // println / System.out / System.err
captureNetwork = false, // OkHttp interceptor events
captureNavigation = false, // Activity push / pop
),
)
```
## What Gets Captured Automatically
`Traceway.init(...)` sets up capture for the following sources with no additional configuration:
- **Uncaught Java/Kotlin exceptions** on every thread, via `Thread.setDefaultUncaughtExceptionHandler`
- **View click handler throws**: uncaught exceptions inside `View.OnClickListener`, `AlertDialog` button handlers, and similar UI callbacks
- **Background thread throws**: anything that escapes a `Thread`'s `run()` body
- **Main `Handler.post` throws**: async exceptions on the main looper, caught by the default uncaught-exception handler
- **Activity lifecycle transitions**: `push` / `pop` recorded as navigation actions
## Deobfuscate Release Crashes
Release builds run R8, so crash traces arrive with renamed classes and rewritten line numbers. To get readable traces, apply the [`com.tracewayapp.symbols`](/symbolicator/android) Gradle plugin. It injects a per-build UUID into `BuildConfig.TRACEWAY_PROGUARD_UUID` and uploads the build's `mapping.txt` to your Traceway instance. Pass the injected UUID to the SDK so each report can be matched to its mapping:
```kotlin
Traceway.init(
application = this,
connectionString = "your-token@https://traceway.example.com/api/report",
options = TracewayOptions(
version = "1.0.0",
proguardUuid = BuildConfig.TRACEWAY_PROGUARD_UUID,
),
)
```
`TRACEWAY_PROGUARD_UUID` is the only field the plugin adds to `BuildConfig`. To keep the connection string out of source too, declare your own field with `buildConfigField("String", "TRACEWAY_DSN", "\"$tracewayDsn\"")` and read it back as `BuildConfig.TRACEWAY_DSN`.
See the [Android symbolicator docs](/symbolicator/android) for the full plugin configuration, the upload token, and the manual upload path.
## Test Your Integration
Make your activity show a button that throws, so you can verify everything is wired up:
```kotlin
import android.app.Activity
import android.os.Bundle
import android.widget.Button
class MainActivity : Activity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(Button(this).apply {
text = "Send Test Error"
setOnClickListener {
throw RuntimeException("Test error from Traceway")
}
})
}
}
```
Tap the button and check your Traceway dashboard to verify the error appears with its full stack trace.
## Platform Support
| Platform | Error Tracking | Screen Recording |
|----------|----------------|------------------|
| Android (API 21+) | Yes | No |
For Flutter apps that need cross-platform error tracking (and screen recording on iOS / Android / macOS), use the [Flutter SDK](/client/flutter) instead. It ships the same wire format, so a single Traceway backend handles both.