Add a mapping file 🔗
When you set the minifyEnabled
property to true in your Android application source code, your build process minifies, optimizes, and obfuscates the code and generates a single mapping file, mapping.txt
. This mapping file contains the information Splunk RUM needs to convert stack traces containing obfuscated classes and filenames back into a human readable form. This conversion is called deobfuscation in Android.
In order to associate a specific mapping file with a specific application build, Splunk RUM compares the applicationId
and versionCode
properties of the application to the parameters that you specify for the mapping file upload. You specify these parameters either as --app-id
and --version-code
in the splunk-rum android upload
command or by including your application’s merged or packaged manifest (AndroidManifest.xml
), which includes these properties by default, in the splunk-rum android upload-with-manifest
command.
注釈
Splunk recommends that you follow the steps on this page to upload your mapping files to Splunk RUM before you distribute corresponding binaries. To ensure that the mapping files you upload to Splunk RUM match the binaries you deploy to production, the best practice is to integrate the splunk-rum
commands below into your CI pipeline so that whenever you re-build your Android application, you automatically re-upload its mapping file. Alternatively, you can upload source maps on demand.
Splunk RUM stores your mapping files permanently. You cannot delete them from Splunk RUM at this time.
前提条件 🔗
To support de-obfuscation of your application’s stack traces, ensure that your
proguard-rule.pro
has the following two lines enabled:-keepattributes LineNumberTable,SourceFile -renamesourcefileattribute SourceFile
Upgrade the following Splunk components:
splunk-otel-android: v1.10.0
Uploads for production builds 🔗
Upload your application’s mapping file and specify its
applicationID
andversionCode
properties.You can do this in either of these ways:
Run the
upload
command with the--app-id
and--version-code
parameters:注釈
If you didn’t set the
SPLUNK_REALM
andSPLUNK_ACCESS_TOKEN
environment variables, you must also add the--realm <value>
and--token <your-splunk-org-access-token>
parameters to this command.splunk-rum android upload \ --app-id=<applicationID> --version-code=<versionCode> \ --path=<path-to-mapping-file> \ [optional-parameters]
Run the
upload-with-manifest
command with the path to the application’s merged or packagedAndroidManifest.xml
file, along with path to the mapping file. Be sure to include the correct manifest, which is the one that’s created when your application is built, and is located in the build output directory:注釈
If you didn’t set the
SPLUNK_REALM
andSPLUNK_ACCESS_TOKEN
environment variables, you must also add the--realm <value>
and--token <your-splunk-org-access-token>
parameters to this command.splunk-rum android upload-with-manifest \ --manifest <path-to-merged-manifest> \ --path <path-to-mapping-file> \ [optional-parameters]
(Optional) Verify that your upload succeeded:
splunk-rum android list --app-id=<applicationID>
Uploads for pre-production builds 🔗
If you’re instrumenting pre-production builds where
versionCode
isn’t updated for each build, add a unique identifier as metadata to theAndroidManifest.xml
file in your source directory before building the application binary. This identifier must be namedsplunk.build_id
. To add this identifier, follow the steps below:
Add this snippet to the
<application>
block of theAndroidManifest.xml
file in your source directory:<meta-data android:name="splunk.build_id" android:value="${splunkBuildId}" />
Add the following code to the
android {}
block of the Gradle build script of your application. This code generates a new UUID for every application variant and adds it to the merged manifest file after the variant is assembled, where the Splunk RUM agent will retrieve it:If you use Kotlin add this to
build.gradle.kts
:applicationVariants.configureEach { val uniqueBuildId = UUID.randomUUID().toString() this.mergedFlavor.manifestPlaceholders["splunkBuildId"] = uniqueBuildId logger.lifecycle("Splunk: Variant $name assigned build ID: $uniqueBuildId") val capitalizedVariantName = name.replaceFirstChar { it.uppercase() } tasks.named("process${capitalizedVariantName}Manifest").configure { outputs.upToDateWhen { false } } }
If you use Groovy add this to
build.gradle
:applicationVariants.configureEach { variant -> def uniqueBuildId = UUID.randomUUID().toString() variant.mergedFlavor.manifestPlaceholders.put("splunkBuildId", uniqueBuildId) project.logger.lifecycle("Splunk: Variant ${variant.name} assigned build ID: ${uniqueBuildId}") def capitalizedVariantName = variant.name.capitalize() tasks.named("process${capitalizedVariantName}Manifest").configure { outputs.upToDateWhen { false } } }
Upload your application’s mapping file and specify its
applicationID
,versionCode
, andsplunk.build_id
properties. You can do this in either of these ways:Run the upload command with the
--app-id
,--version-code
, and--splunk-build-id
parameters. This option only works if you addedsplunk.build_id
to your Gradle build script (in step 1). Get the build ID from the Gradle build output or from the merged manifest:注釈
If you didn’t set the
SPLUNK_REALM
andSPLUNK_ACCESS_TOKEN
environment variables, you must also add the--realm <value>
and--token <your-splunk-org-access-token>
parameters to this command.splunk-rum android upload \ --app-id=<applicationID> --version-code=<versionCode> \ --splunk-build-id <value> \ --path=<path-to-mapping-file> \ [optional-parameters]
Run the
upload-with-manifest
command with the path to the application’s merged or packagedAndroidManifest.xml
file, along with path to the mapping file. Be sure to include the correct manifest, which is the one that’s created when your application is built, and is located in the build output directory:注釈
If you didn’t set the
SPLUNK_REALM
andSPLUNK_ACCESS_TOKEN
environment variables, you must also add the--realm <value>
and--token <your-splunk-org-access-token>
parameters to this command.splunk-rum android upload-with-manifest \ --manifest <path-to-merged-manifest> \ --path <path-to-mappping-file> \ [optional-parameters]
(Optional) Verify that your upload succeeded:
splunk-rum android list --app-id=<applicationID>
構文 🔗
splunk-rum android [command] [parameters]
Command descriptions 🔗
Command |
説明 |
---|---|
|
Upload the mapping file Parameters:
|
|
Upload the Android Parameters:
|
|
List the 100 most recently uploaded mapping files for the given application ID, sorted in reverse chronological order based on the upload timestamp. Parameters:
|