Related pages:

If you have obfuscated your code and want to monitor crashes, you will be required to upload the ProGuard or DexGuard mapping files. AppDynamics requires the mapping file for the application to produce human-readable stack traces for crash snapshots. For details on the importance of snapshots, see Get Human-Readable Crash Snapshots. 

DexGuard is built on ProGuard, so the Controller UI and some of the REST API for uploading mapping files will refer to ProGuard for both ProGuard and DexGuard files. 

This page describes the requirements, the available methods, and instructions to manually upload the mapping files.

We recommend you set up automatic uploading of the ProGuard or DexGuard mapping files using Gradle and your build.gradle file. 

Requirements

If you update your application, you are required to upload the new version of the mapping file.

To manually upload the mapping files, you are required to associate the mapping file with the correct version of the application by providing the following:

  • Android package name for the application

  • Version code for that application (specified in either the AndroidManifest.xml file or the build.gradle file)

Upload Methods

You can then either upload the mapping file using the Upload Missing ProGuard Mappings dialog in the Controller UI or use a special REST API. Perform the upload separately for each ProGuard mapping file that you are providing. You can also check your uploads with a separate REST API.

See the following sections for instructions:

Upload ProGuard Mappings in the Controller UI

  1. From the left-hand panel, click Configuration.
  2. Click ProGuard Mapping & NDK Symbol Files.
  3. From the Upload Missing ProGuard Mapping dialog:
    1. Enter the version code (a number) for the package. This is the versionCode property specified in either the  AndroidManifest.xml file or the build.gradle file of the application for which this mapping file was generated.
    2. Click Choose File.
      The uploader expects a file with the .txt extension. The file is named mapping.txt.
    3. In the file browser, locate and select the mapping file and click Open.
    4. Click Upload.

Upload ProGuard Mappings with the REST API

The API uses HTTP basic authentication. The username is your AppDynamics EUM account name and the password is your EUM license key.

Send the mapping file

Send the mapping file as a text file in the body of the PUT request to the following URL: 

https://api.eum-appdynamics.com/v2/account/<MyAccountName>/<androidPackageName>/<versionCode>/proguard-mapping
https://fra-api.eum-appdynamics.com/v2/account/<MyAccountName>/<androidPackageName>/<versionCode>/proguard-mapping
BASH 
https://syd-api.eum-appdynamics.com/v2/account/<MyAccountName>/<androidPackageName>/<versionCode>/proguard-mapping
BASH

See Cisco AppDynamics SaaS Domains and IP Ranges for more EUM server locations. 

These parameters are required:

  • MyAccountName: the URL-encoded version of your account name.
  • androidPackagename: the name of the Android package for which this mapping file was generated.
  • versionCode: the string representation of the "versionCode" property specified in either the AndroidManifest.xml file or the build.gradle file of the application for which this mapping file was generated. 

The request body contains the mapping file. You are required to add a Content-Type header, -H Content-Type:text/plain, and your account name and license key/password to the call. 

Sample Request and Response Using the REST API

This is a sample request and response using the REST API. 

Upload Request

The following example uses curl to send a ProGuard mapping file. You would use a similar command to send a DexGuard mapping file. The account name is "Example account" and the license key/password is "Example-License-Key-4e8ec2ae6cfe". The plus signs replace spaces in the account name when the account name is URL-encoded. The package name of the Android application is "com.example.networklogger". The mapping file corresponds to the version with versionCode. 

curl -v -H Content-Type:text/plain --upload-file mapping.txt --user Example+account:Example-License-Key-4e8ec2ae6cfe https://api.eum-appdynamics.com/v2/account/Example+account/com.example.networklogger/1/proguard-mapping
BASH 
curl -v -H Content-Type:text/plain --upload-file mapping.txt --user Example+account:Example-License-Key-4e8ec2ae6cfe https://fra-api.eum-appdynamics.com/v2/account/Example+account/com.example.networklogger/1/proguard-mapping
BASH 
curl -v -H Content-Type:text/plain --upload-file mapping.txt --user Example+account:Example-License-Key-4e8ec2ae6cfe https://syd-api.eum-appdynamics.com/v2/account/Example+account/com.example.networklogger/1/proguard-mapping
BASH

Upload Response 

The successful output of the example request looks like this: 

* About to connect() to api.eum-appdynamics.com port 443 (#0)
*   Trying ::1...
* connected
* Connected to api.eum-appdynamics.com  (::1) port 443 (#0)
* Server auth using Basic with user 'Example+account'
> PUT /v2/account/Example+account/com.example.networklogger/1/proguard-mapping HTTP/1.1
> Authorization: Basic SW50ZXJuYWwrdGVzdCthY2NvdW50OlRlc3RBY2N0LTFlMzktNDVkMy05MzAzLTRlOGVjMmFlNmNmZQ==
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8y zlib/1.2.5
> Host: api.eum-appdynamics.com
> Accept: */*
> Content-Length: 4
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Jetty(8.1.4.v20120524)
<
* Connection #0 to host api.eum-appdynamics.com left intact
* Closing connection #0
BASH 
* About to connect() to fra-api.eum-appdynamics.com port 443 (#0)
*   Trying ::1...
* connected
* Connected to fra-api.eum-appdynamics.com  (::1) port 443 (#0)
* Server auth using Basic with user 'Example+account'
> PUT /v2/account/Example+account/com.example.networklogger/1/proguard-mapping HTTP/1.1
> Authorization: Basic SW50ZXJuYWwrdGVzdCthY2NvdW50OlRlc3RBY2N0LTFlMzktNDVkMy05MzAzLTRlOGVjMmFlNmNmZQ==
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8y zlib/1.2.5
> Host: fra-api.eum-appdynamics.com
> Accept: */*
> Content-Length: 4
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Jetty(8.1.4.v20120524)
<
* Connection #0 to host fra-api.eum-appdynamics.com left intact
* Closing connection #0
BASH 
* About to connect() to syd-api.eum-appdynamics.com port 443 (#0)
*   Trying ::1...
* connected
* Connected to syd.eum-appdynamics.com  (::1) port 443 (#0)
* Server auth using Basic with user 'Example+account'
> PUT /v2/account/Example+account/com.example.networklogger/1/proguard-mapping HTTP/1.1
> Authorization: Basic SW50ZXJuYWwrdGVzdCthY2NvdW50OlRlc3RBY2N0LTFlMzktNDVkMy05MzAzLTRlOGVjMmFlNmNmZQ==
> User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8y zlib/1.2.5
> Host: syd-api.eum-appdynamics.com
> Accept: */*
> Content-Length: 4
> Expect: 100-continue
>
< HTTP/1.1 100 Continue
* We are completely uploaded and fine
< HTTP/1.1 200 OK
< Content-Length: 0
< Server: Jetty(8.1.4.v20120524)
<
* Connection #0 to host syd-api.eum-appdynamics.com left intact
* Closing connection #0
BASH




Check Uploaded Mapping Files Using the REST API 

You can check to make sure that your mapping files have successfully uploaded using two REST APIs.

  1. Get a list of the GUIDs for the last 50 mapping files you have uploaded.
  2. Check if a specific mapping file has been uploaded.

List of the Last 50 Mapping Files Uploaded

The proguardQuery method allows you to retrieve a list of GUIDs for up to the last 50 mapping files (ProGuard or DexGuard) that have been uploaded to your account, along with the time they were uploaded. The response is displayed as JSON, by upload time, with the most recent first.

  1. Set up your authentication as described in Upload with the API.

  2. Create a GET request of the form: 

    curl --user Example+account:Example-License-Key-4e8ec2ae6cfe https://<EUM_Cloud/EUM_Server_Host:port>/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard
    BASH

    - EUM_Cloud refers to SaaS-based EUM Cloud URLs. For a complete list, see Cisco AppDynamics SaaS Domains and IP Ranges. 

    - EUM_Server_Host refers to the URL pointing to your on-premises EUM Server.

    - EUM_Account_Name is your EUM account name.

    - GUID_To_Check is the GUID of the ProGuard file in which you are interested.

Sample Request  


curl --user Example+account:Example-License-Key-4e8ec2ae6cfe  https://api.eum-appdynamics.com:443/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard
BASH 
curl --user Example+account:Example-License-Key-4e8ec2ae6cfe  https://fra-api.eum-appdynamics.com:443/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard
BASH 
curl --user Example+account:Example-License-Key-4e8ec2ae6cfe  https://syd-api.eum-appdynamics.com:443/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard
BASH


Sample Response
{"proguardFiles": [
{"packageName":"my_package_name1", "version":"1", "uploadTime":"mm/dd/yyyy 16:09:23","GUID":"my_build_id1"}, 
{"packageName":"my_package_name2", "version":"1", "uploadTime":"mm/dd/yyyy 16:09:23","GUID":"my_build_id2"}
]}
JSON


Check for Specific Mapping File by GUID 

The checkForProguardFile method allows you to check if a specific ProGuard or DexGuard file by GUID has been uploaded. The upload time is returned in the response.

    1. Set up your authentication as described in Upload with the REST API.

    2. Create a GET request of the form:

      curl --user Example+account:Example-License-Key-4e8ec2ae6cfe https://<EUM_Cloud/EUM_Server_Host:port>/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard/guid/<GUID_To_Check>
      BASH

      - EUM_Cloud refers to SaaS-based EUM Cloud URLs. For a complete list, see Cisco AppDynamics SaaS Domains and IP Ranges. 

      - EUM_Server_Host refers to the URL pointing to your on-premises EUM Server.

      - EUM_Account_Name is your EUM account name.

      - GUID_To_Check is the GUID of the ProGuard file in which you are interested.

      Sample Request 

      curl --user Example+account:Example-License-Key-4e8ec2ae6cfe  https://api.eum-appdynamics.com:443/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard/guid/my_build_id1
      BASH 
      curl --user Example+account:Example-License-Key-4e8ec2ae6cfe  https://fra-api.eum-appdynamics.com:443/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard/guid/my_build_id1
      BASH 
      curl --user Example+account:Example-License-Key-4e8ec2ae6cfe  https://syd-api.eum-appdynamics.com:443/v2/account/<EUM_Account_Name>/crash-symbol-file-query/proguard/guid/my_build_id1
      BASH


      Sample Response 
      {"packageName":"mypackagename","version":"1","uploadTime":"mm/dd/yyyy 16:09:23","GUID":"my_build_id1"}
      JSON