Source Maps

Source maps is an experimental feature not intended for production usage at the moment.

It is common practice to minify client-side JavaScript code for several reasons, e.g. performance gain. This can make debugging very difficult, as it is hard to read the minified files. Source mapping can help for debugging minfied JavaScript files, by mapping code from the minified files to the original source code.

APM Server provides a Source Map API which accepts source maps complying to the Source map revision 3 proposal.

Uploaded source maps are used to map stack trace information from recorded transaction and error documents to the original source code files for easier debugging.

How source maps are applied

When source maps have been uploaded and RUM support is enabled, source mapping is automatically applied to the stack trace frames of all errors and transactions recorded with the JavaScript Frontend Agent.

The server tries to find an uploaded source map for every stack trace frame of the record. The following information is used to find the previously uploaded source map entry:

  • the record’s is matched against the source map’s service_name
  • the record’s service.version is matched against the source map’s service_version
  • the stack trace frame’s abs_path is matched against the source map’s bundle_filepath

If multiple source maps with the same meta information are found, the source map with the latest upload timestamp is used.

In case a matching source map is found and the source map can be applied to the stack trace frame, the frame’s information is updated with the mapped information before the record is indexed. The following information is changed to reflect the original source code file, when source mapping is applied:

  • filename
  • function
  • line number
  • column number
  • abs path: is cleaned to be the shortest path name equivalent to the given path name

See how an example source map looks like in Elasticsearch.