Manually instrument Android applications π
You can manually instrument Android applications for Splunk RUM using the Android RUM agent to collect additional telemetry, sanitize Personal Identifiable Information (PII), add global attributes, and more.
Filter spans π
You can modify or drop spans using the filterSpans()
method. For example, you can drop or redact spans that contain personally identifiable information (PII).
The following example shows how to remove a span:
SplunkRum.builder()
.filterSpans(spanFilter ->
spanFilter
.removeSpanAttribute(stringKey("http.user_agent")))
The following example shows how to redact the value of an attribute to remove sensitive data:
SplunkRum.builder()
.filterSpans(spanFilter ->
spanFilter
.replaceSpanAttribute(StandardAttributes.HTTP_URL,
value -> Pattern.compile.. _"(user|pass:\\w+")
.matcher(value)
.replaceAll("$1=<redacted>")))
Manage global attributes π
Global attributes are key-value pairs added to all reported data. Global attributes are useful for reporting app or user-specific values as tags.
The following example shows how to define the app version and a key-value pair as global attributes:
SplunkRum.builder()
.setGlobalAttributes(
Attributes.builder()
.put("key", "value")
.put(StandardAttributes.APP_VERSION, BuildConfig.VERSION_NAME)
.build())
To update a set of global attributes after the RUM library is initialized, use the following SplunkRum
methods:
setGlobalAttribute(AttributeKey)
to set or update a single attribute.updateGlobalAttributes(Consumer<AttributesBuilder> attributesUpdater)
to update attributes in bulk.
Add user metadata using global attributes π
By default, the Android RUM agent doesnβt automatically link traces to users of your site. However, you might need to collect user metadata to filter or debug traces.
You can identify users by adding global attributes from the OpenTelemetry specification, such as enduser.id
and enduser.role
, to your spans.
The following examples show how to add identification metadata as global attributes when initializing the agent or after initializing it, depending on whether user data is accessible at initialization:
Add identification metadata during initialization π
SplunkRum.builder()
.setGlobalAttributes(
Attributes.builder()
// Adds existing userId
.put("enduser.id", "user-id-123456")
.build())
Add identification metadata after initialization π
splunkRum.setGlobalAttribute("enduser.id", "123456L");
splunkRum.setGlobalAttribute("enduser.type", "loggedInUser");
splunkRum.setGlobalAttribute("enduser.role", "premium");
Report custom events and workflows π
You can report custom events and workflows happening in your Android application using the addRumEvent
and startWorkflow
APIs.
The following example shows how to report when a user closes a help dialog:
public Dialog onCreateDialog(Bundle savedInstanceState) {
LayoutInflater inflater = LayoutInflater.from(activity);
View alertView = inflater.inflate(R.layout.sample_mail_dialog, null);
AlertDialog.Builder builder = new AlertDialog.Builder(activity);
builder.setView(alertView)
.setNegativeButton(R.string.cancel, (dialog, id) ->
// Record a simple "zero duration" span with the provided name and attributes
SplunkRum.getInstance().addRumEvent("User Rejected Help", HELPER_ATTRIBUTES));
return builder.create();
}
The following example shows how to start a workflow for which metrics are recorded by Splunk RUM. To record the workflow you must end the OpenTelemetry span instance:
binding.buttonWork.setOnClickListener(v -> {
Span hardWorker =
SplunkRum.getInstance().startWorkflow("Main thread working hard");
try {
Random random = new Random();
long startTime = System.currentTimeMillis();
while (true) {
random.nextDouble();
if (System.currentTimeMillis() - startTime > 20_000) {
break;
}
}
} finally {
hardWorker.end();
}
});
Customize screen names π
By default, the Android RUM agent uses the simple class name of each Fragment
and Activity
type as the value of the screen.name
attribute. To customize the screen name, use the @RumScreenName
annotation.
For example, the following activity appears with the screen.name
attribute set to the value Buttercup
:
@RumScreenName("Buttercup")
public class MainActivity extends Activity {
...
}
Configure error reporting π
You can report handled errors, exceptions, and messages using the addRumException(Throwable)
method. Exceptions appear as errors in the Splunk RUM UI, and error metrics are recorded.
The following example shows how to report the Unimplemented Feature: Settings
error in a sample application:
public boolean onOptionsItemSelected(MenuItem item) {
int id = item.getItemId();
if (id == R.id.action_settings) {
SplunkRum.getInstance()
.addRumException(
new UnsupportedOperationException("Unimplemented Feature: Settings"),
SETTINGS_FEATURE_ATTRIBUTES);
return true;
}
return super.onOptionsItemSelected(item);
}
Add server trace context from Splunk APM π
The Android RUM agent collects server trace context using back-end data provided by APM instrumentation through the Server-Timing
header. In some cases, you might want to generate the header manually.
To create the Server-Timing
header manually, provide a Server-Timing
header with the name traceparent
, where the desc
field holds the version, the trace ID, the parent ID, and the trace flag.
Consider the following HTTP header:
Server-Timing: traceparent;desc="00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
The example resolves to a context containing the following data:
version=00 trace-id=4bf92f3577b34da6a3ce929d0e0e4736
parent-id=00f067aa0ba902b7 trace-flags=01
When generating a value for the traceparent
header, make sure that it matches the following regular expression:
00-([0-9a-f]{32})-([0-9a-f]{16})-01
Server timing headers with values that donβt match the pattern are automatically discarded. For more information, see the Server-Timing
and traceparent
documentation on the W3C website.
Next steps π
To add custom attributes, adapt the instrumentation to your environment and application, customize sampling, and more, see Configure the Splunk Android RUM instrumentation.
To check that your data is in your Splunk RUM for Mobile instance, see Check that your data is coming in.
To troubleshoot, see Troubleshoot Android instrumentation for Splunk Observability Cloud.