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.

To see an example of how to deploy the Mobile RUM Android SDK, navigate to our GitHub repository here.

Prerequisites

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

Shell

./sdkmanager --list

Install & Instrument Your Android Application

Step 1: Install Middleware Android SDK

Java

implementation 'io.middleware.android:sdk:+'

Step 2: Add Application Instrumentation Config

To modify your configuration methods, navigate to the Configuration Methods section

Java

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

  @Override
  public void onCreate() {
      super.onCreate();

    Middleware.builder()
        .setTarget(targetUrl)
        .setServiceName("sample-android-app-1")
        .setProjectName("Mobile-SDK-Android")
        .setRumAccessToken(rumAccessToken)
        .setSlowRenderingDetectionPollInterval(Duration.ofMillis(1000))
        .setDeploymentEnvironment("PROD")
        .build(this);
  }
}

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.

Method	Description
`setRumAccessToken(String)`	Authorizes client to send telemetry to Middleware
`setTarget(String)`	Sets target URL to recieve telemetry
`setService(String)`	Sets service name of your application
`setDeploymentEnvironment(String)`	Sets environment attribute on spans generated by instrumentation. Example: `PROD`, `DEV`
`disableCrashReporting()`	Disables crash reporting which is enabled by default
`disableAnrDetection()`	Disables Application Not Responding (ANR) detection which is enabled by default
`disableNetworkMonitor()`	Disables network change detection which is enabled by default
`disableSlowRenderingDetection()`	Disables slow or frozen frame render detection which is enabled by default
`setSlowRenderingDetectionPollInterval(Duration)`	Sets default polling for slow or frozen render detection. Default detection interval is 1000 milliseconds

Step 3: HTTP Instrumentation Config [Optional]

Integrate with OkHTTP3 to monitor HTTP events across user devices.

OkHTTP3

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:

Java

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

Java

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

Step 2: Start Custom Event Workflow

Start custom events and workflows using startWorkflow

Java

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

Step 3: End Custom Event Workflow

End custom events and workflows using end

Java

loginWorkflow.end();

Error Reporting

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

Java

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

Java

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.

This feature is only available for Android Version 8.0 (Android Oreo) or higher

Java

  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)
  @Override
  protected void onPause() {
      super.onPause();
      recorder.stopRecording();
  }

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:

Java

.disableSessionRecording()

Privacy

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

User passwords are automatically masked by default. Other sensitive information like credit card data and API keys must be masked manually.

Java

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:

Name	Type	Description
`project.name` , `app`	String	Defines the project name, used as `projectName(String)`
`service.name`	String	Defines the service name, used as `serviceName(String)`
`session.id`	String	Random session identifier generated by Middleware SDK
`rum.sdk.version`	String	Middleware SDK version

Resource Attributes

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

Name	Type	Description
`deployment.environment`	String	Name of deployment environment. Example: `DEV`, `PROD`
`device.model.identifier`	String	Device model identifier. Example: `Moto-G30`
`device.model.name`	String	Name of device. Example: `ONEPLUS A600`
`device.manufacturer`	String	Name of device manufacturer. Example: `OnePlus`
`os.name`	String	Name of operating system. Sets to `Android`
`os.description`	String	Operating System description. Example: `Android Version 11 (Build RKQ1.201217.002 API level 30)`
`os.type`	String	Operating System type. Sets to `Linux`
`os.version`	String	Operating System version. Example: Android version `11`

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:

Name	Type	Description
`thread.id`	Integer	ID of the current managed thread, as opposed to the operating system thread ID
`thread.name`	String	Name of the thread
`exception.message`	String	Message of the exception
`exception.type`	String	Type of exception
`exception.stacktrace`	String	Stack trace for the exception
`exception.escaped`	String	Sets `true`, denoting the uncaught exception, such as a crash occurring
`component`	String	Sets `crash`
`event.type`	String	Sets `error`

Network Monitoring

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

Name	Type	Description
`network.status`	String	Network status set to `lost` or `available`
`network.connection.type`	String	Connection type set to `wifi`, `cell`, `unavailable`, or `unknown`
`network.carrier.name`	String	Name of network carrier used

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:

Name	Type	Description
`exception.stacktrace`	String	Stack trace for the exception
`component`	String	Sets `error`
`event.type`	String	Sets `error`

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:

Name	Type	Description
`count`	Integer	Number of slow or frozen frames on a 1 second interval. Change the interval duration by passing a positive integer (in milliseconds) to the `slowRenderingDetectionPollInterval(Duration)` setting

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:

Name	Type	Description
`http.method`	String	`GET`, `POST`, `HEAD`
`http.url`	String	`https://foo.bar/address?q=value#hash`
`http.flavor`	String	`1.0`
`http.status_code`	Integer	`200`, `404`, `418`
`http.response_content_length`	Integer	`3495`(bytes)
`http.user_agent`	String	`CERN-LineMode/2.15 libwww/2.17b3`
`net.transport`	String	`IP.TCP`
`net.peer.name`	String	`example.com`
`net.peer.port`	Integer	`80`, `8080`, `443`
`component`	String	Sets `http`

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:

Name	Type	Description
`component`	String	Sets `ui`
`activityName`, `activity.name`	String	Name of the activity class. Example: `MainActivity`

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.

Name	Type	Description
`component`	String	Sets `ui`
`fragmentName`	String	Name of the fragment class Example: `MainFragment`

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:

Name	Type	Description
`component`	String	Sets `appstart`
`start.type`	String	Type of start. Value `cold`, `warm`, or `hot`

Need assistance or want to learn more about Middleware? Contact us at support[at]middleware.io.

Middleware Docs

Mobile RUM - Android SDK

Prerequisites

Install & Instrument Your Android Application

Step 1: Install Middleware Android SDK

Step 2: Add Application Instrumentation Config

Step 2a: Configuration Methods [Optional]

Step 3: HTTP Instrumentation Config [Optional]

Custom Configurations

Set Global Attributes

Events

Step 1: Setup Your Custom Event

Step 2: Start Custom Event Workflow

Step 3: End Custom Event Workflow

Error Reporting

Logs

Session Replay

Session Recording

Privacy

Default Attributes

Resource Attributes

Instrumentation Attributes

Middleware Docs

​Prerequisites

​Install & Instrument Your Android Application

​Step 1: Install Middleware Android SDK

​Step 2: Add Application Instrumentation Config

​Step 2a: Configuration Methods [Optional]

​Step 3: HTTP Instrumentation Config [Optional]

​Custom Configurations

​Set Global Attributes

​Events

​Step 1: Setup Your Custom Event

​Step 2: Start Custom Event Workflow

​Step 3: End Custom Event Workflow

​Error Reporting

​Logs

​Session Replay

​Session Recording

​Privacy

​Default Attributes

​Resource Attributes

​Instrumentation Attributes

Prerequisites

Install & Instrument Your Android Application

Step 1: Install Middleware Android SDK

Step 2: Add Application Instrumentation Config

Step 2a: Configuration Methods [Optional]

Step 3: HTTP Instrumentation Config [Optional]

Custom Configurations

Set Global Attributes

Events

Step 1: Setup Your Custom Event

Step 2: Start Custom Event Workflow

Step 3: End Custom Event Workflow

Error Reporting

Logs

Session Replay

Session Recording

Privacy

Default Attributes

Resource Attributes

Instrumentation Attributes