The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
Android added to docs/fe/be
ddux37e1b519ce13
diff --git a/backend/app/controllers/auth.controller.go b/backend/app/controllers/auth.controller.goindex d60b43e7..54325c4d 100644--- a/backend/app/controllers/auth.controller.go+++ b/backend/app/controllers/auth.controller.go@@ -154,7 +154,7 @@ func (a authController) Register(c *gin.Context) {if !validFrameworks[request.Framework] {traceway.CaptureMessage("Invalid framework received during registration: " + request.Framework)- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter"})+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter, android"})return}diff --git a/backend/app/controllers/oauth.controller.go b/backend/app/controllers/oauth.controller.goindex 77a05b1b..58d472f1 100644--- a/backend/app/controllers/oauth.controller.go+++ b/backend/app/controllers/oauth.controller.go@@ -163,7 +163,7 @@ func (a oauthController) FinishSetup(c *gin.Context) {}if !validFrameworks[request.Framework] {- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter"})+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter, android"})return}diff --git a/backend/app/controllers/project.controller.go b/backend/app/controllers/project.controller.goindex 7f4f132d..b2a357af 100644--- a/backend/app/controllers/project.controller.go+++ b/backend/app/controllers/project.controller.go@@ -41,6 +41,7 @@ var validFrameworks = map[string]bool{"symfony": true,// Mobile frameworks"flutter": true,+ "android": true,}// Project name validation regex: allows alphanumeric, spaces, hyphens, and underscores@@ -88,7 +89,7 @@ func (p projectController) CreateProject(c *gin.Context) {if !validFrameworks[request.Framework] {traceway.CaptureMessage("Invalid framework received: " + request.Framework)- c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter"})+ c.JSON(http.StatusBadRequest, gin.H{"error": "Framework must be one of: gin, fiber, chi, fasthttp, stdlib, custom, react, svelte, vuejs, jquery, hono, cloudflare, opentelemetry, symfony, flutter, android"})return}diff --git a/docs/components/FrameworkPicker.jsx b/docs/components/FrameworkPicker.jsxindex c483c685..1ba9c96a 100644--- a/docs/components/FrameworkPicker.jsx+++ b/docs/components/FrameworkPicker.jsx@@ -168,6 +168,14 @@ const FRAMEWORKS = [href: "/client/flutter",badge: "new",},+ {+ value: "android",+ label: "Android",+ description: "Native Android (Kotlin/Java) apps with automatic exception capture, logs, HTTP, and navigation breadcrumbs.",+ icon: "/android.png",+ href: "/client/android",+ badge: "new",+ },];export default function FrameworkPicker() {diff --git a/docs/components/SdkContext.jsx b/docs/components/SdkContext.jsxindex d7ffa3c5..bcd02cf9 100644--- a/docs/components/SdkContext.jsx+++ b/docs/components/SdkContext.jsx@@ -22,6 +22,7 @@ export const SDK_OPTIONS = [{ value: 'js-nextjs', label: 'Next.js (OTel)' },{ value: 'php-symfony', label: 'Symfony' },{ value: 'flutter', label: 'Flutter' },+ { value: 'android', label: 'Android' },]const STORAGE_KEY = 'traceway-docs-sdk'@@ -46,6 +47,7 @@ const PATH_SDK_MAP = {'nextjs': 'js-nextjs','symfony': 'php-symfony','flutter': 'flutter',+ 'android': 'android',}const SdkContext = createContext({diff --git a/docs/components/SdkSelector.jsx b/docs/components/SdkSelector.jsxindex a8c9afe8..c941afeb 100644--- a/docs/components/SdkSelector.jsx+++ b/docs/components/SdkSelector.jsx@@ -23,6 +23,7 @@ const SDK_QUICK_START = {'cloudflare': '/client/cloudflare','php-symfony': '/client/symfony','flutter': '/client/flutter',+ 'android': '/client/android',}export default function SdkSelector() {diff --git a/docs/pages/client/_meta.json b/docs/pages/client/_meta.jsonindex a984ecb9..2ff65b49 100644--- a/docs/pages/client/_meta.json+++ b/docs/pages/client/_meta.json@@ -24,5 +24,6 @@"otel": "OpenTelemetry","cloudflare": "Cloudflare Workers","symfony": "Symfony",- "flutter": "Flutter"+ "flutter": "Flutter",+ "android": "Android"}diff --git a/docs/pages/client/android/_meta.json b/docs/pages/client/android/_meta.jsonnew file mode 100644index 00000000..8393d864--- /dev/null+++ b/docs/pages/client/android/_meta.json@@ -0,0 +1,3 @@+{+ "index": "Quick Start"+}diff --git a/docs/pages/client/android/index.mdx b/docs/pages/client/android/index.mdxnew file mode 100644index 00000000..4ee05e2f--- /dev/null+++ b/docs/pages/client/android/index.mdx@@ -0,0 +1,234 @@+# 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.0")+}+```++Maven Central is enabled by default in modern Android projects — 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` and add the `INTERNET` permission so reports can leave the device:++```xml+<manifest xmlns:android="http://schemas.android.com/apk/res/android">+ <uses-permission android:name="android.permission.INTERNET" />+ <application android:name=".MyApp" ...>+ ...+ </application>+</manifest>+```++## 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 |+| `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)`:++```kotlin+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?) {+ TracewayClient.instance?.recordLog(message, level = priority.toLogLevel())+ }+})+```++### 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+ val client = OkHttpClient.Builder()+ .addInterceptor(TracewayOkHttpInterceptor())+ .build()+ ```++ For HTTP clients that aren't OkHttp, record events manually:++ ```kotlin+ 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++## Test Your Integration++Add a button that throws an exception to verify everything is wired up:++```kotlin+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?sdk=flutter) instead — it ships the same wire format so a single Traceway backend handles both.diff --git a/docs/public/android.png b/docs/public/android.pngnew file mode 100644index 00000000..b5f0b5daBinary files /dev/null and b/docs/public/android.png differdiff --git a/docs/theme.config.jsx b/docs/theme.config.jsxindex 155f097d..013e4424 100644--- a/docs/theme.config.jsx+++ b/docs/theme.config.jsx@@ -24,6 +24,7 @@ const SDK_VISIBILITY = {nextjs: "js-nextjs",symfony: "php-symfony",flutter: "flutter",+ android: "android",};export default {diff --git a/frontend/src/lib/components/framework-combobox.svelte b/frontend/src/lib/components/framework-combobox.svelteindex bc4df051..bff0fbb5 100644--- a/frontend/src/lib/components/framework-combobox.svelte+++ b/frontend/src/lib/components/framework-combobox.svelte@@ -36,6 +36,7 @@{ value: 'cloudflare', label: 'Cloudflare', description: 'Cloudflare Workers (OTLP Traces)', group: 'Backend' },{ value: 'opentelemetry', label: 'OpenTelemetry', description: 'Vendor-neutral observability', group: 'Backend' },{ value: 'flutter', label: 'Flutter', description: 'Mobile UI framework', group: 'Mobile' },+ { value: 'android', label: 'Android', description: 'Native Android (Kotlin/Java)', group: 'Mobile' },] as const;const selectedFrameworkLabel = $derived(getFrameworkLabel(value));diff --git a/frontend/src/lib/components/framework-icon.svelte b/frontend/src/lib/components/framework-icon.svelteindex c95dad54..676fd461 100644--- a/frontend/src/lib/components/framework-icon.svelte+++ b/frontend/src/lib/components/framework-icon.svelte@@ -58,6 +58,8 @@<img src="/symfony.png" alt="Symfony" class={className} />{:else if framework === 'flutter'}<img src="/flutter.png" alt="Flutter" class={className} style="object-fit: contain;" />+{:else if framework === 'android'}+ <img src="/android.png" alt="Android" class={className} style="object-fit: contain;" />{:else}<img src="/custom.png" alt="Custom" class={className} />{/if}diff --git a/frontend/src/lib/state/projects.svelte.ts b/frontend/src/lib/state/projects.svelte.tsindex 3e8ff997..6bf30a83 100644--- a/frontend/src/lib/state/projects.svelte.ts+++ b/frontend/src/lib/state/projects.svelte.ts@@ -1,9 +1,9 @@import { api } from '$lib/api';import { authState } from './auth.svelte';-export type Framework = 'gin' | 'fiber' | 'chi' | 'fasthttp' | 'stdlib' | 'custom' | 'react' | 'svelte' | 'vuejs' | 'nextjs' | 'nestjs' | 'express' | 'remix' | 'jquery' | 'hono' | 'cloudflare' | 'opentelemetry' | 'symfony' | 'flutter';+export type Framework = 'gin' | 'fiber' | 'chi' | 'fasthttp' | 'stdlib' | 'custom' | 'react' | 'svelte' | 'vuejs' | 'nextjs' | 'nestjs' | 'express' | 'remix' | 'jquery' | 'hono' | 'cloudflare' | 'opentelemetry' | 'symfony' | 'flutter' | 'android';-export const FRONTEND_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'jquery', 'flutter'];+export const FRONTEND_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'jquery', 'flutter', 'android'];export const JS_FRAMEWORKS: Framework[] = ['react', 'svelte', 'vuejs', 'nextjs', 'nestjs', 'express', 'remix', 'jquery'];export const FRAMEWORK_LABELS: Record<Framework, string> = {@@ -26,9 +26,10 @@ export const FRAMEWORK_LABELS: Record<Framework, string> = {opentelemetry: 'OpenTelemetry',symfony: 'Symfony',flutter: 'Flutter',+ android: 'Android',};-export const MOBILE_FRAMEWORKS: Framework[] = ['flutter'];+export const MOBILE_FRAMEWORKS: Framework[] = ['flutter', 'android'];export function getFrameworkLabel(fw: Framework): string {return FRAMEWORK_LABELS[fw] ?? fw;diff --git a/frontend/src/lib/utils/framework-code.ts b/frontend/src/lib/utils/framework-code.tsindex 53fee1b1..6956b345 100644--- a/frontend/src/lib/utils/framework-code.ts+++ b/frontend/src/lib/utils/framework-code.ts@@ -40,6 +40,8 @@ export function getInstallCommand(framework: Framework): string {return '';case 'flutter':return 'flutter pub add traceway';+ case 'android':+ return 'implementation("com.tracewayapp:traceway:1.0.0")';case 'custom':default:return base;@@ -301,6 +303,22 @@ void main() {);}`;+ case 'android':+ return `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 = "${connectionString}",+ options = TracewayOptions(version = "1.0.0"),+ )+ }+}`;+case 'custom':default:return `package main@@ -340,6 +358,10 @@ class TestControllerif (framework === 'flutter') {return `// Trigger a test errorthrow StateError('Test error from Traceway integration');`;+ }+ if (framework === 'android') {+ return `// Trigger a test error+throw RuntimeException("Test error from Traceway integration")`;}if (framework && isJsFramework(framework)) {return `// Trigger a test error@@ -361,6 +383,15 @@ TracewayClient.instance?.captureException(Exception('Test error'),StackTrace.current,);`;+ }+ if (framework === 'android') {+ return `import com.tracewayapp.traceway.Traceway++try {+ riskyOperation()+} catch (e: Throwable) {+ Traceway.captureException(e)+}`;}if (framework && isJsFramework(framework)) {switch (framework) {@@ -430,6 +461,7 @@ export function getFrameworkLabel(framework: Framework): string {opentelemetry: 'OpenTelemetry',symfony: 'Symfony',flutter: 'Flutter',+ android: 'Android',};return labels[framework] || framework;}@@ -440,5 +472,6 @@ export function getCodeLanguage(framework: Framework): 'go' | 'javascript' | 'baif (framework === 'hono') return 'javascript';if (framework === 'cloudflare') return 'javascript';if (framework === 'flutter') return 'javascript'; // closest to Dart syntax highlighting+ if (framework === 'android') return 'javascript'; // closest to Kotlin syntax highlightingreturn isJsFramework(framework) ? 'javascript' : 'go';}diff --git a/frontend/static/android.png b/frontend/static/android.pngnew file mode 100644index 00000000..b5f0b5daBinary files /dev/null and b/frontend/static/android.png differ