Skip to content

Upload SourceMap via Script

If your RUM application uses the Public DataWay access method, the application runtime data is reported directly to the public DataWay. The corresponding SourceMap files can be uploaded via the OpenAPI interface of the corresponding site using a script.

In other words:

  • When reporting RUM data, the datawayUrl and clientToken from the application access page are used.
  • When uploading SourceMap files, the site's OpenAPI address and OPEN_API_KEY are used.

This document describes how to upload SourceMap via script in the public DataWay scenario.

Prerequisites

  1. Ensure the current application has completed public DataWay initialization according to the corresponding platform's access documentation.
  2. Obtain the OpenAPI address corresponding to the current site.
  3. Obtain the OPEN_API_KEY corresponding to the current site.
    • After entering the Guance workspace, click Manage > API Key Management > Create Key.
    • After successful creation, obtain the Key from the API Key details page and use it as DF_API_KEY in the script.
    • If environments or versions are not distinguished, you can pass only app_id. However, the matching scope will be broader. For more precise troubleshooting, it is recommended to also pass env and version.
  4. Obtain the app_id, env, and version of the target RUM application.
    • app_id is the unique identifier of the current RUM application.
    • env and version must match the corresponding fields in the SDK initialization or the actual error data.
  5. Package the sourcemap.zip file in advance according to the requirements in SourceMap Configuration.
  6. If using the Shell version, ensure bash, curl, jq, split, mktemp, and wc are installed in the environment.
  7. If using the Python version, ensure python3 is installed in the environment.

Upload via Script

Uploading via script is done through OpenAPI and is suitable for automated uploads in public DataWay access scenarios.

Script Description

Script repository address: sourcemap-upload-scripts.

Two upload scripts are currently provided:

  • Shell version: upload-sourcemap.sh
  • Python version: upload_sourcemap.py

Both scripts are used to upload already packaged sourcemap.zip files. They are not responsible for generating or compressing SourceMap.

Before executing the example commands, please obtain the corresponding script from the repository mentioned above and place it in the current command execution directory, or specify the actual path of the script in the command.

Parameter Description

Required Parameters

  • --endpoint: The OpenAPI address corresponding to the site.
  • --api-key: The OPEN_API_KEY corresponding to the site. It will be written into the DF-API-KEY request header.
  • --app-id: The app_id of the RUM application.
  • --file: The path to the sourcemap.zip file to be uploaded. The file size must not exceed 500 MB.

Optional Parameters

  • --version: The application version number.
  • --env: The application environment identifier, e.g., daily, gray, prod.
  • --need-cover: Whether to overwrite files with the same name. Options are true or false. Default is false.
  • --chunk-size-mb: The size for chunked upload, in MB. Default is 10. Maximum is 10.
  • --merge-path: Custom merge interface path. Use only when the current site's merge interface path differs from the script's default.
  • --cancel-path: Custom cancel upload interface path. Use only when the current site's cancel interface path differs from the script's default.

Usage

sh ./upload-sourcemap.sh \
  --endpoint https://openapi.truewatch.com \
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

python3 ./upload_sourcemap.py \
  --endpoint https://openapi.truewatch.com\
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

Expected Output

Upon successful execution, you will see logs similar to:

  • Init succeeded, uploadId=...
  • Uploading part x/y
  • Merge succeeded via /api/v1/rum_sourcemap/part_merge
  • Upload complete

Using Environment Variables

You can also pass the same parameters via environment variables:

export DF_OPENAPI_ENDPOINT="https://openapi.truewatch.com"
export DF_API_KEY="your-api-key"
export DF_APP_ID="app_id_from_studio"
export DF_VERSION="1.0.2"
export DF_ENV="daily"
export DF_SOURCEMAP_FILE="./sourcemap.zip"
export DF_NEED_COVER="true"

The correspondence between environment variables and command-line parameters is as follows:

  • DF_OPENAPI_ENDPOINT corresponds to --endpoint
  • DF_API_KEY corresponds to --api-key
  • DF_APP_ID corresponds to --app-id
  • DF_VERSION corresponds to --version
  • DF_ENV corresponds to --env
  • DF_SOURCEMAP_FILE corresponds to --file
  • DF_NEED_COVER corresponds to --need-cover

Then execute:

sh ./upload-sourcemap.sh

Or:

python3 ./upload_sourcemap.py

Notes

  1. Script upload is suitable for public DataWay access scenarios.
  2. The upload script uses the OpenAPI + DF-API-KEY authentication method, not datawayUrl + clientToken.
  3. The directory structure after extracting sourcemap.zip must match the file paths in the error stack.
  4. The uploaded file must be in .zip format, and its size must not exceed 500 MB.
  5. If only one of version or env is filled, the upload target may not be precise enough. It is recommended to fill in both.
  6. The maximum size for a single chunk in chunked upload is 10 MB.
  7. If the upload process fails after initialization, the script will automatically attempt to cancel this chunked upload task.
  8. The Python version uses only the Python standard library and does not require additional pip dependencies.

FAQ

uploadId is empty

Usually indicates that a SourceMap with the same name already exists on the server, and overwriting is not enabled.

Retry with the following parameter added:

--need-cover true

Missing required command

Indicates that the Shell version is missing a required command. Please install the corresponding tool and retry.

Merge endpoint ... returned HTTP 404

Usually indicates that the current site uses a different merge interface path.

Contact the site administrator to confirm the interface path, then respecify it:

--merge-path <your-path>

Upload Successful but Error Stack Not Parsed

Please check the following first:

  1. Whether app_id, version, and env match the actual error data.
  2. Whether the directory structure after extracting sourcemap.zip matches the resource paths in error_stack.
  3. Whether the current application is indeed the target application requiring SourceMap upload.