Mobile RUM - Android SDK

The Mobile RUM SDK provides a customizable suite of tools to analyze and optimize the performance of Android applications. Isolate ANR and network changes, quickly detect application crashes, identify slow or frozen frames and more.

Prerequisites

Android SDK Version 21 or above. Check your Android SDK version with the following command:

./sdkmanager --list

Install & Instrument Your Android Application

Step 1: Install Middleware Android SDK

implementation 'io.middleware.android:sdk:+'
implementation "io.opentelemetry.instrumentation:opentelemetry-instrumentation-api"

Step 2: Add Application Instrumentation Config

import static io.middleware.android.sdk.utils.Constants.APP_VERSION;
import io.middleware.android.sdk.Middleware;
import io.opentelemetry.api.common.Attributes;

class MyApplication extends Application {
  private final String targetUrl = "<target-url>";
  private final String rumAccessToken = "your-account-token";

  @Override
  public void onCreate() {

Step 2a: Configuration Methods [Optional]

Understand the behavior of your RUM Android application with the following methods and set particular attributes related to telemetry ingestion, monitoring, and instrumentation.

Step 3: HTTP Instrumentation Config [Optional]

Integrate with OkHTTP3 to monitor HTTP events across user devices.

private Call.Factory buildOkHttpClient(Middleware middleware) {
  return middleware.createRumOkHttpCallFactory(new OkHttpClient());
}

Custom Configurations

Set Global Attributes

Global attributes serve as metadata or contextual information that can be attached to telemetry, traces, or logs collected by the instrumentation framework or SDK. They are key-value pairs that provide additional details about the application, device, user session, or environment.

Set the following Global Attributes to instrument your application:

Middleware.builder()
        .setGlobalAttributes(
            Attributes.builder()
                    .put("key", "value")
                    .put(StandardAttributes.APP_VERSION, BuildConfig.VERSION_NAME)
                    .build());

Events

Step 1: Setup Your Custom Event

Send custom events and workflows using addEvent

Middleware.getInstance().addEvent("You clicked on Button", BUTTON_ATTRIBUES);

Step 2: Start Custom Event Workflow

Start custom events and workflows using startWorkflow

Span loginWorkflow = Middleware.getInstance().startWorkflow("User Login Flow");

Step 3: End Custom Event Workflow

End custom events and workflows using end

loginWorkflow.end();

Error Reporting

Use addException(Throwable) to report exceptions, errors, and display messages on the Middleware dashboard

Middleware.getInstance().addException(new RuntimeException("Something went wrong!"), Attributes.empty())

Logs

Add custom logs to display on your Middleware dashboard such as debug, error, warning, and info

Middleware logInstance = Middleware.getInstance();
logInstance.d("TAG", "I am debug");
logInstance.e("TAG", "I am error");
logInstance.i("TAG", "I am info");
logInstance.w("TAG", "I am warning");

Session Replay

Control how you capture and replay your users' browsing experience. To start and stop session replay, override the onResume and onPause methods.

final MiddlewareRecorder recorder = Middleware.getInstance().getRecorder();

@RequiresApi(api = Build.VERSION_CODES.N)
@Override
protected void onResume() {
    super.onResume();
    recorder.startRecording(this);
}

@RequiresApi(api = Build.VERSION_CODES.N)

Session Recording

The maximum session recording duration is four hours. If users are inactive for more than 15 minutes at a time, session recordings will be stopped. If users exceed more than four hours in a single session or become active again after the 15-minute inactivity timeout, a new session will be automatically created.

Session recording is enabled by default. Disable this feature with the following function:

.disableSessionRecording()

Privacy

Blur sensitive information in session recordings by embedding the following method:

final Middleware instance = Middleware.getInstance();
final TextView someTextView = findViewById(R.id.some_text_view);
instance.addSanitizedElement(someTextView);

Default Attributes

The following Attributes are provided by the Android SDK by default:

Resource Attributes

The following Resource Attributes are applied to all spans by default:

Instrumentation Attributes

The following Instrumentation Attributes are additional properties the Android SDK provides:

Crash Reporting

Crash Reporting is enabled by default and adds the following Crash Reporting attributes to spans that represent uncaught exceptions:

Network Monitoring

Network Monitoring is enabled by default and produce spans with the name network.change and the following attributes:

Application Not Responding (ANR)

Application Not Responding (ANR) event detection creates spans whenever the primary application thread remains unresponsive for over 5 seconds. ANR is enabled by default.

ANR include the following attributes:

Slow Rendering Detection

Slow Rendering Detection produces spans whenever it identifies a slow or frozen frame render. Rendering is considered slow if its duration surpasses 16 milliseconds and frozen if it exceeds 700 milliseconds.

During each interval, slow rendering detection generates up to two spans: one named slowRenders for tallying slow frames, and another named frozenRenders for tallying frozen frames. Slow Render Detection is enabled by default.

Spans generated by Slow Rendering Detection include the following attribute:

HTTP Client Attributes

The Android RUM agent includes instrumentation for OkHttp. To activate this functionality, see Step 3 from the above installation here.

OKHttp includes the following attributes:

Activity Lifecycle Monitoring

By default, Activity lifecycle Monitoring is enabled. It generates spans whenever an activity undergoes a state change. The name of an activity lifecycle span can vary based on its state. Below is a list of all possible states:

Fragment Lifecycle Monitoring

Fragment lifecycle monitoring involves generating spans whenever an fragment undergoes a state change. The name of a fragment lifecycle span can vary based on its state::

• Created: Activity starts for the first time.

• Restarted:Activity restarts after being stopped.

• Resumed: Activity resumes after a pause.

• Paused: Activity is paused.

• Stopped: Activity stops.

• Destroyed: Activity is destroyed.

App Start Monitoring

The app start monitoring feature creates spans each time the app undergoes a cold, warm, or hot start.

• Cold Starts: Occurs when users open the app for the first time after booting their phone or terminating the app.

• Warm Starts: Occurs when some operations from a cold start are still in progress. Warm starts are quicker than cold starts but slower than hot starts.

• Hot Starts: Occurs when the system brings an app to the foreground. They are faster than cold starts as the app is already loaded.

App start monitoring generates spans named AppStart with associated attributes: