README.md

---

Getting Started   •   Getting Involved

FAQ   •   Security

---

Splunk Android RUM Instrumentation

Splunk RUM Product Documentation can be found here.

🚧 This project is currently in BETA. It is officially supported by Splunk. However, breaking changes MAY be introduced.

Features

• Crash reporting
• ANR detection
• Network change detection
• Full Android Activity and Fragment lifecycle monitoring
• Access to the OpenTelemetry APIs for manual instrumentation
• SplunkRum APIs for creating custom RUM events and reporting exceptions
• Access to an OkHttp3 Call.Factory implementation for monitoring http client requests
• APIs to redact any span from export, or change span attributes before export

Getting Started

Prerequisites

This library supports Android API levels 21 and above, with core library desugaring enabled.

WARNING: It is VERY IMPORTANT that you are have enabled core library desugaring in the build for your app. If you have not done this, and you are targetting API levels below 26, your app will crash on devices running API level < 26.

Getting the library

There are two options for bringing in this library as a dependency for your Android app:

Use as a gradle dependency from maven central:

Add Maven Central as a maven repository to the repositories section of your main build.gradle:

allprojects {
    repositories {
        google()
...
        mavenCentral()
    }
}

Then, add the latest release as a dependency in your application's build.gradle file.

dependencies {
...
    implementation ("com.splunk:splunk-otel-android:0.12.0")
...
}

Build the library locally:

First, clone this repository locally:

git clone https://github.com/signalfx/splunk-otel-android.git

Then build locally and publish to your local maven repository:

./gradlew publishToMavenLocal

Make sure you have mavenLocal() as a repository in your application's main build.gradle:

allprojects {
    repositories {
        google()
...
        mavenLocal()
    }
}

Then, add the locally built library as a dependency in your application's build.gradle:

dependencies {
...
    implementation ("com.splunk:splunk-otel-android:0.13.0-SNAPSHOT")
...
}

Configuration

In order to configure the Splunk RUM library, you will need to know three things:

• Your Splunk realm.
  • The realm can be found in your Splunk Observability UI in the Account Settings page.
• Your RUM access token.
  • You can find or create a RUM access token in the Splunk Observability UI, in your Organization Settings.
  • Important: this access token must have the RUM authorization scope to work.
• The name of your application.

Here is an example of a the very minimal configuration which uses these 3 values:

class MyApplication extends Application {
    private final String realm = "<realm>";
    private final String rumAccessToken = "<your_RUM_access_token>";
    private final Config config = SplunkRum.newConfigBuilder()
            .realm(realm)
            .rumAccessToken(rumAccessToken)
            .applicationName("My Android App")
            .build();
}

There are other options available on the Config.Builder instance, including enabling debug mode and enabling/disabling various instrumentation features.

Initialization

To initialize the Splunk RUM monitoring library, from your android.app.Application instance, simply call the static initializer in your Application.onCreate() implementation:

class MyApplication extends Application {
    //...

    @Override
    public void onCreate() {
        super.onCreate();
        SplunkRum.initialize(config, this);
    }
}

Examples of this process can be seen in the sample application included in this repository in the sample-app submodule.

Advanced Usage

Additional Config.Builder options.

There are a number of optional configuration options that can be specified via the Config.Builder when initializing your instance of the SplunkRum API:

(Note: full javadoc can be found at javadoc.io)

• deploymentEnvironment(String) : This option will set the Splunk environment attribute on the spans that are generated by the instrumentation.
• beaconEndpoint(String) : Rather than using the realm(String) configuration option, you can use this method to explicitly give the full URL of the RUM ingest endpoint.
• debugEnabled(boolean) : Enabling debug mode will turn on the opentelemetry logging span exporter, which can be useful when debugging instrumentation issues. Additional logging may also be turned on with this option.
• crashReportingEnabled(boolean) : This option can be used to turn off the crash reporting feature.
• networkMonitorEnabled(boolean) : This option can be used to turn off the network monitoring feature.
• anrDetectionEnabled(boolean) : This option can be used to turn off the ANR detection feature.
• globalAttributes(Attributes) : This option allows you to add a set of OpenTelemetry Attributes to be appended to every span generated by the library.
• filterSpans(Consumer<SpanFilterBuilder>) : This can be used to provide customizations of the spans that are emitted by the library. Examples include: removing spans altogether from export, removing span attributes, changing span attributes or changing the span name. See the javadoc on the SpanFilterBuilder class for more details.

APIs provided by the SplunkRum instance:

(Note: full javadoc can be found at javadoc.io)

• The SplunkRum instrumentation uses OpenTelemetry APIs and semantic conventions for span generation. If you have need of writing your own manual instrumentation, the SplunkRum instance gives you direct access to the instance of OpenTelemetry that is being used via the getOpenTelemetry() method. For details on writing manual instrumentation, please refer to the OpenTelemetry docs and examples.
• The SplunkRum instance exposes the RUM session ID, in case you wish to provide this to your users for troubleshooting purposes. This session ID is generated randomly and contains no PII whatsoever.
• If you wish to record some simple Events or Workflows, the SplunkRum instances provides APIs for that:
  • addRumEvent(String, Attributes) : record a simple "zero duration" span with the provided name and attributes.
  • startWorkflow(String) : Span : This method allows you to start a Splunk RUM "workflow" for which metrics will be recorded by the RUM backend. The returned OpenTelemetry Span instance must be ended for this workflow to be recorded.
• To record a custom Error or Exception, SplunkRum exposes an addRumException(Throwable) method, and one that also accepts a set of Attributes. These exceptions will appear as errors in the RUM UI, and error metrics will be recorded for them.
• If you need to update the set of "global attributes" that were initially configured, you can do that via one of two methods on the SplunkRum instance: setGlobalAttribute(AttributeKey) or updateGlobalAttributes(Consumer<AttributesBuilder> attributesUpdater). The former will add or update a single attribute, and the latter allows bulk updating of the attributes.
• To add OpenTelemetry instrumentation to your OkHttp3 client, SplunkRum provides an okhttp Call.Factory wrapper that can be applied to your client. See the createRumOkHttpCallFactory(OkHttpClient) for details.

Troubleshooting

• If you see runtime errors related to Java 8 interfaces and classes, make sure you have enabled coreLibraryDesugaring per the official Android documentation.
• Please report any bugs either here as a Github issue, or with official Splunk support channels.

Sample Application

This repository includes a sample application that can show off a few features of our mobile RUM product.

In order to build and run the sample application, you will need to configure a local.properties file in the root of the project. It will need to have two properties configured:

rum.realm=<realm>
rum.access.token=<a valid Splunk RUM access token for the realm>

License and versioning

The Splunk Android RUM Instrumentation is released under the terms of the Apache Software License version 2.0. See the license file for more details.