From de0062a868bfaa01086e1e7eb7f8b6a7e78d16e8 Mon Sep 17 00:00:00 2001 From: Abhay Sood Date: Thu, 6 Feb 2025 11:40:23 +0530 Subject: [PATCH] docs(android): improve getting started guide - add troubleshooting section - add details about sampling closes #1723 --- docs/android/README.md | 69 ++++++++++++++++++++++++++- docs/android/configuration-options.md | 28 ++++------- 2 files changed, 76 insertions(+), 21 deletions(-) diff --git a/docs/android/README.md b/docs/android/README.md index 506042c60..6268dcab1 100644 --- a/docs/android/README.md +++ b/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 diff --git a/docs/android/configuration-options.md b/docs/android/configuration-options.md index d66ce8667..f3e5c7cee 100644 --- a/docs/android/configuration-options.md +++ b/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.