docs(android): improve getting started guide

- add troubleshooting section
- add details about sampling

closes #1723

docs/android/README.md

@@ -4,10 +4,13 @@
 * [Self host compatibility](#self-host-compatibility)
 * [Quick reference](#quick-reference)
 * [Getting started](#getting-started)
+  * [Troubleshooting](#troubleshooting)
+  * [Sampling](#sampling)
 * [Custom events](#custom-events)
   * [Handled exceptions](#handled-exceptions)
   * [Screen view](#screen-view)
 * [Features](#features)
+* [What is a session?](#session)
 * [Performance Impact](#performance-impact)
   * [Benchmarks](#benchmarks)
   * [Profiling](#profiling)
@@ -188,7 +191,13 @@ Add the following to your app's Application class `onCreate` method.
 > initialize the SDK as soon as possible in Application `onCreate` method.
 
 ```kotlin
-Measure.init(context)
+Measure.init(context, MeasureConfig(
+        // Enable logging for debugging
+        enableLogging = true,
+        // Set to 1 to track all sessions, useful for debug builds.
+        samplingRateForErrorFreeSessions = 1f, 
+    )
+)
 ```
 
 If you wish to configure the SDK during initialization with a custom config use the overloaded function:
@@ -237,6 +246,64 @@ Reopen the app and launch the dashboard, you should see the crash report in the
 
 🎉 Congratulations, you have successfully integrated Measure into your app!
 
+
+### Troubleshooting
+
+If you see no data in the dashboard after setup, note that data syncs either every 30s or when the app goes to background. Here's how to investigate:
+
+#### Enable Debug Logs
+During initialization:
+
+```kotlin
+MeasureConfig(enableLogging = true)
+```
+
+All SDK logs use the tag `Measure`.
+
+#### Common Issues
+* **Missing Configuration**
+If logs show the following, then review [Step 1: Add API Key & URL](#1-add-the-api-key--api-url).
+```
+sh.measure.android.API_URL is missing in the manifest
+sh.measure.android.API_KEY is missing in the manifest
+```
+
+* **Server Connection**
+If logs show Failed to send batch or Request failed with unknown error:
+* Verify API_URL in the AndroidManigest is correct
+* Check server status
+* Test server connectivity from device
+
+
+#### Missing configuration in AndroidManifest
+If you find logs like `sh.measure.android.API_URL is missing in the manifest, skipping initialization` or `sh.measure.android.API_KEY is missing in the manifest, skipping initialization`, review [Step 1 in getting started section](#1-add-the-api-key--api-url).
+
+
+#### Failure to connect to server
+If you can find logs like `Failed to send batch` or `Request failed with unknown error`, etc. This typically means that the server is not
+reachable. You should verify the `API_URL` and check whether the server is responding.
+
+# Sampling
+
+## Session Sampling
+
+Set [samplingRateForErrorFreeSessions](configuration-options.md#samplingrateforerrorfreesessions) to control event collection from sessions without errors. By default, the SDK sends all events from crashed sessions to the server, while collecting no events from error-free sessions.
+
+* 0.0 — No events from error-free sessions (default)
+* 0.1 — 10% of error-free sessions
+* 1.0 — All sessions
+
+Session sampling helps optimize data collection for crash and error analysis.
+
+## Trace Sampling 
+
+[traceSamplingRate](configuration-options.md#tracesamplingrate) controls performance trace collection independently of session sampling. While session sampling determines which session-level events are sent, trace sampling specifically controls performance monitoring data.
+
+This separation ensures:
+- Performance traces are collected based on their own sampling rate.
+- Critical performance data is captured regardless of session errors.
+- Session data remains focused on crash analysis and debugging.
+
 # Custom events
 
 Custom events provide more context on top of automatically collected events. They provide the context

docs/android/configuration-options.md

@@ -36,7 +36,7 @@ Measure.init(
 * [**httpHeadersBlocklist**](#httpHeadersBlocklist)
 * [**trackHttpBody**](#trackHttpBody)
 * [**trackActivityIntentData**](#trackActivityIntentData)
-* [**sessionSamplingRate**](#sessionSamplingRate)
+* [**samplingRateForErrorFreeSessions**](#samplingRateForErrorFreeSessions)
 * [**enableLogging**](#enableLogging)
 * [**eventTrackingLevel**](#eventTrackingLevel)
 * [**traceSamplingRate**](#traceSamplingRate)
@@ -170,18 +170,16 @@ checking what data was passed as part of the bundle, it might also contain sensi
 
 Disabled by default.
 
-## `sessionSamplingRate`
-
-Measure SDK by default collects events for crashed sessions only. However, in case you want to collect
-events at a sampled rate for non-crashed sessions, use `sessionSamplingRate.
+## `samplingRateForErrorFreeSessions`
 
-Defaults to 0.0, meaning no events for non-crashed sessions are exported by default.
+Controls sampling rate for non-crashed sessions. Defaults to 0. 
 
-The sampling rate is a value between 0 and 1. For example, a value of `0.1` will export only 10%
-of the non-crashed sessions, a value of `0` will disable exporting of non-crashed sessions.
+A value between 0.0 and 1.0 can be set:
+* 0.0 (default): Only collect crashed sessions
+* 0.1: Collect 10% of non-crashed sessions
+* 1.0: Collect all sessions
 
-Note that events for crashed sessions are always exported. And certain events like `cold_launch`, `warm_launch`,
-`hot_launch`, `lifecycle_activity`, `lifecycle_fragment` are always exported regardless of the sampling rate.
+Note that all crashed sessions are collected regardless of this setting.
 
 ## `traceSamplingRate`
 
@@ -196,16 +194,6 @@ of the traces, a value of `0` will disable exporting of traces completely.
 Allows enabling/disabling internal logging of Measure SDK. This is useful to debug issues with the SDK
 itself. By default, logging is disabled.
 
-## `samplingRateForErrorFreeSessions`
-
-By default, sessions with errors (crashes and ANRs) are reported. Sessions without
-errors can also be reported with a sampling rate.
-
-Defaults to 0.0, meaning no error-free sessions are reported by default.
-
-The sampling rate is a value between 0 and 1. For example, a value of `0.1` will report only 10%
-of the error-free sessions, a value of `0` will disable reporting of error-free sessions.
-
 ## `autoStart`
 
 Controls whether to start tracking immediately or delay starting the SDK.