Merge pull request #2651 from splunk/adasplunk-O11YDOCS-6514

[O11YDOCS-6514] Browser, iOS, Android symbolication: CLI, Webpack, UI doc updates [May 28 release]

Author: adasplunk

_includes/requirements/ios.rst

@@ -1,6 +1,6 @@
 Splunk RUM for Mobile supports the following versions:
 
 * iOS 15 and higher
-* iPadOS 13 and higher
+* iPadOS 15 and higher
 
 Splunk RUM supports Apple Silicon.

gdi/get-data-in/rum/android/add-mapping-file.rst

@@ -0,0 +1,249 @@
+.. _add-mapping-file:
+
+*********************************************************************
+Add a mapping file
+*********************************************************************
+
+
+.. meta::
+    :description: Your uploaded mapping file enables Splunk RUM to convert stack traces back into a human-readable form.
+
+
+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. 
+
+
+.. note::
+    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 :ref:`upload source maps on demand<mobile-connect-source-files>`.
+
+    Splunk RUM stores your mapping files permanently. You cannot delete them from Splunk RUM at this time. 
+
+
+Prerequisites
+=====================================================================
+
+* To support de-obfuscation of your application's stack traces, ensure that your ``proguard-rule.pro`` has the following two lines enabled:
+
+   .. code-block::
+
+      -keepattributes LineNumberTable,SourceFile
+      -renamesourcefileattribute SourceFile
+
+* Upgrade the following Splunk components:
+
+  * :new-page:`splunk-otel-android<https://central.sonatype.com/artifact/com.splunk/splunk-otel-android>`: v1.10.0
+
+* :ref:`Install the splunk-rum CLI<rum-gdi-install-cli>`.
+
+
+Uploads for production builds
+=====================================================================
+
+#. Upload your application's mapping file and specify its ``applicationID`` and ``versionCode`` properties. 
+
+   You can do this in either of these ways:
+
+   * Run the ``upload`` command with the ``--app-id`` and ``--version-code`` parameters: 
+
+     .. note::
+        If you didn't set the ``SPLUNK_REALM`` and ``SPLUNK_ACCESS_TOKEN`` environment variables, you must also add the ``--realm <value>`` and ``--token <your-splunk-org-access-token>`` parameters to this command.
+
+     .. code-block:: shell
+
+        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 packaged ``AndroidManifest.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: 
+
+      .. note::
+        If you didn't set the ``SPLUNK_REALM`` and ``SPLUNK_ACCESS_TOKEN`` environment variables, you must also add the ``--realm <value>`` and ``--token <your-splunk-org-access-token>`` parameters to this command.
+
+     .. code-block:: shell
+
+        splunk-rum android upload-with-manifest \
+        --manifest <path-to-merged-manifest> \
+        --path <path-to-mapping-file> \
+        [optional-parameters]
+       
+       
+       
+#. (Optional) Verify that your upload succeeded:
+
+    .. code-block:: shell
+
+        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 the ``AndroidManifest.xml`` file in your source directory before building the application binary. This identifier must be named ``splunk.build_id``. To add this identifier, follow the steps below:
+
+
+#. Add this snippet to the ``<application>`` block of the ``AndroidManifest.xml`` file in your source directory:
+
+   .. code-block:: xml
+
+      <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``: 
+
+     .. code-block:: 
+
+        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``: 
+
+     .. code-block:: 
+
+        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``, and ``splunk.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 added ``splunk.build_id`` to your Gradle build script (in step 1). Get the build ID from the Gradle build output or from the merged manifest:
+
+     .. note::
+        If you didn't set the ``SPLUNK_REALM`` and ``SPLUNK_ACCESS_TOKEN`` environment variables, you must also add the ``--realm <value>`` and ``--token <your-splunk-org-access-token>`` parameters to this command.
+
+      .. code-block:: shell
+
+        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 packaged ``AndroidManifest.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: 
+
+      .. note::
+        If you didn't set the ``SPLUNK_REALM`` and ``SPLUNK_ACCESS_TOKEN`` environment variables, you must also add the ``--realm <value>`` and ``--token <your-splunk-org-access-token>`` parameters to this command.
+
+      .. code-block:: shell
+
+        splunk-rum android upload-with-manifest \
+        --manifest <path-to-merged-manifest> \
+        --path <path-to-mappping-file> \
+        [optional-parameters]
+
+
+#. (Optional) Verify that your upload succeeded:
+
+   .. code-block:: shell
+
+      splunk-rum android list --app-id=<applicationID>
+ 
+ 
+
+Syntax
+=====================================================================
+
+.. code-block:: shell
+
+    splunk-rum android [command] [parameters]
+
+
+
+Command descriptions
+=====================================================================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20, 80
+
+   * - :strong:`Command`
+     - :strong:`Description`
+
+   * - ``upload --path <path> --app-id <value> --version-code <int> [optional-parameters]`` 
+     -  Upload the mapping file ``mapping.txt`` with the application ID and version code that you specify.
+
+        Parameters:
+
+        * ``--path <path>`` Required. Path to the ``mapping.txt`` file. 
+ 
+        * ``--app-id <applicationID>`` Required. The ``applicationId`` property in your application's ``build.gradle`` file. 
+
+        * ``--version-code <int>`` Required. The ``versionCode`` property of your application. 
+ 
+        * ``--splunk-build-id <value>`` Optional. Splunk build ID for the upload.
+
+        * ``--realm <value>`` Optional. Realm for your organization. For example, ``us0``. You can omit this parameter and set the environment variable ``SPLUNK_REALM`` instead.
+ 
+        * ``--token <your-splunk-org-access-token>``  Optional. API access token. You can omit this parameter and set the environment variable ``SPLUNK_ACCESS_TOKEN`` instead.
+
+        * ``--dry-run=[true|false]`` Perform a trial run with no changes made. Default: ``false``.
+
+        * ``--debug`` Enable debug logs.
+
+        * ``-h, --help`` Display help for this command.
+     
+
+   * - ``upload-with-manifest --manifest <path> --path <path> [optional-parameters]``  
+     -  Upload the Android ``mapping.txt`` file with required metadata extracted from the ``AndroidManifest.xml`` file.
+
+        Parameters:
+        
+        * ``--manifest <path>`` Required. Path to the merged or the packaged ``AndroidManifest.xml`` file that is generated when the application is built.
+
+        * ``--path <path>`` Required. Path to the ``mapping.txt`` file.
+
+        * ``--realm <value>`` Optional. Realm for your organization. For example, ``us0``.  You can omit this parameter and set the environment variable ``SPLUNK_REALM`` instead.
+ 
+        * ``--token <your-splunk-org-access-token>`` Optional. API access token. You can omit this parameter and set the environment variable ``SPLUNK_ACCESS_TOKEN`` instead.
+
+        * ``--dry-run=[true|false]`` Preview the file that will be uploaded and the parameters that will be extracted from ``AndroidManifest.xml``.
+ 
+        * ``--debug`` Enable debug logs.
+
+        * ``-h, --help`` Display help for command. 
+
+
+   * - ``list --app-id <value> [optional-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:
+        
+        * ``--app-id <applicationID>`` Required. The ``applicationId`` property in your app's ``build.gradle`` file.
+
+        * ``--realm <value>`` Optional. Realm for your organization. For example, ``us0``. You can omit this parameter and set the environment variable ``SPLUNK_REALM`` instead.
+
+        * ``--token <your-splunk-org-access-token>`` Optional. API access token. You can omit this parameter and set the environment variable ``SPLUNK_ACCESS_TOKEN`` instead.
+
+        * ``--dry-run=[true|false]`` Perform a trial run with no changes made. Default: ``false``.
+ 
+        * ``--debug`` Enable debug logs.
+ 
+        * ``-h, --help`` Display help for this subcommand.
+
+

gdi/get-data-in/rum/android/get-android-data-in.rst

@@ -14,6 +14,7 @@ Instrument Android applications for Splunk RUM
    Configure the instrumentation <configure-rum-android-instrumentation>
    Manually instrument applications <manual-rum-android-instrumentation>
    Android RUM data model <rum-android-data-model>
+   Add a mapping file <add-mapping-file>
    Troubleshooting <troubleshooting>
 
 Instrument your Android applications to get Real User Monitoring (RUM) data into Splunk Observability Cloud. With Splunk RUM for Mobile, you can gain insight about the performance and health of your mobile apps.

gdi/get-data-in/rum/android/rum-android-data-model.rst

@@ -228,9 +228,16 @@ The Android RUM agent adds the following crash reporting attributes to spans tha
    * - ``component``
      - String
      - Always ``crash``.
-   * - ``status``
+   * - ``service.application_id``
+     - String
+     - Application ID of the app: Refer to definition of ``applicationId`` in the :new-page:`Android Studio developer documentation <https://developer.android.com/build/configure-app-module#set-application-id>`.
+   * - ``service.version_code``
      - String
-     - Always ``Error``.
+     - Version code of the application: Refer to definition of ``versionCode`` in the :new-page:`Android Studio developer documentation <https://developer.android.com/studio/publish/versioning#versioningsettings>`.
+   * - ``splunk.build_id``
+     - String
+     - This is an optional attribute. This is added when minification is enabled for pre-production builds where version code is not updated across app builds, in which case this attribute is used to uniquely identify each build.
+
 
 Network monitoring
 ----------------------------------------------------

gdi/get-data-in/rum/browser/get-browser-data-in.rst

@@ -16,6 +16,7 @@ Instrument browser-based web applications for Splunk RUM
    Migrate manual instrumentation <migrate-manual-instrumentation>
    Data collected <rum-browser-data-model>
    Instrumentation-specific data <browser-rum-instrumentations>
+   Set up JavaScript source mapping <set-up-javascript-source-mapping>
    Errors collected <browser-rum-errors>
    API reference <browser-rum-api-reference>
    Troubleshooting <troubleshooting>

gdi/get-data-in/rum/browser/rum-browser-data-model.rst

@@ -229,6 +229,17 @@ The browser agent sends the IP addresses of all beacon connections to Splunk Obs
 
 .. note:: Splunk Observability Cloud calculates only geographical metadata from the IPs, and drops IP addresses within 6 hours.
 
+
+Additions to the RUM browser model by splunk-rum
+========================================================
+If you're using the ``splunk-rum`` CLI or the Webpack build plugin to upload your source map, those tools will add a new attribute named ``error.sourceMapIds`` to your RUM browser data model. This attribute contains a mapping of file URL and ``sourceMapId`` pairs, where:
+
+* You must have already injected the ``sourceMapId`` attribute into your source map (using the ``splunk-rum`` CLI or the Webpack build plugin). See :ref:`set-up-javascript-source-mapping`. 
+* Only files mentioned in the error's ``error.stack``  appear in ``error.sourceMapIds``.
+
+This attribute is only in your RUM browser data model if you're using the ``splunk-rum`` CLI or the Webpack build plugin.
+
+
 Instrumentation-specific data
 ==============================================