Using website monitoring on Instana comes with many benefits. One feature we have is JS Stack Translation. 

What is JavaScript stack trace translation?

It provides clear and readable stack traces from within Instana. Untranslated stack trace lines aren't readable so we cannot take any action on it. Developers usually work with many files that are bundled in a minified format for performance reasons. An example of a nontranslated trace looks like this:

at http://shop-demo-app.instana.io/static/js/main.b1510333.chunk.js:1:1559

From that line we cannot get any context, but when translated it is shown like this:

at ProductDetails.js 26:11

Which a developer can read and take action.

Source maps

The translation works by using source maps. They enable us to translate from references, files, names to their source code counterparts. These source map files contain essential information about how the compiled code maps to the original code. Here's an example of a source map:

Translating source maps

Now that we know what source maps are, we need to know how Instana uses them to translate:

First the agent on the server reports errors to Instana. Instana after receiving those errors attempts downloading the file to identify the source map responsible for it. After the HTTP response is parsed it looks for the reference to a corresponding source map. When it sees what source map is referenced Instana downloads that source map by using a HTTP GET request or searches the uploaded source map files by the user. When the download is successful it translates.

Example of downloading the source map from the Instana documentation looks like this:

curl -H 'Accept: */*' \

# Use a fake user-agent to bypass simple bot blockers

  -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.100 Safari/537.36' \

  {{url of JavaScript or source map files}}

Uploading source maps

Uploading source maps goes through a curl command which uses when REST APIs. An example of that command looks like this:

curl -L -X PUT \

    'https://$UNIT-$TENANT.instana.io/api/website-monitoring/config/$WEBSITE_ID/sourcemap-upload/$UPLOAD_CONFIG_ID/form' \

    -H 'authorization: apiToken $API_TOKEN' \

    -F 'url="$JAVASCRIPT_URL"' \

    -F 'sourceMap=@"$LOCAL_MAPFILE_LOCATION"'

Saving source maps

After we uploaded it we want to save it. In our case we need specific source maps so we save them on Instana. Instana on openshift in its core namespace has a pod js-stack-trace-translator. That pod saves our source maps. In its config.yaml there is „External storage“. As we cannot edit that secret because Instana operator will overwrite it we change the Instana core object to apply our changes. In the storageConfigs section we have the following choices.

 eumSourceMaps:

      pvcConfig:

        accessModes:

          - ReadWriteMany

        resources:

          requests:

            storage: 10Gi

        storageClassName: „your storage class“

       gcloudConfig:

        bucket: „bucket to be used“

        prefix: „prefix if used“

        storageClass: „your storage class“

      s3Config:

        bucket: „bucket to be used“

        endpoint: „endpoint of your s3“

        prefix: „prefix if used“

        region: „region of your bucket“

        storageClass: „your storage class“

Pod's js-stack-trace-translator config.yaml only shows the s3Config but as we can see you can configure gcloud and pvc. We use pvcConfig as it is the easiest option and openshift administrators can easily configure it. It has to support ReadWriteMany option, for resources you don’t need much because one map is less than 10MiB and you just a storage class that you use. After saving it the js-stack-trace-translator will be restarted from instana-operator and now you can save your source maps.

Conclusion

Using website monitoring on Instana helps us view the whole flow. Instana's js-stack-translator simplifies with understanding unreadable traces. Uploading source maps to our Instana server configures it for our environment.