Retrieve source maps securely in production in Microsoft Edge DevTools

Retrieve source maps securely in production in Microsoft Edge DevTools


The following 3 steps are prerequisites, but in practice, they will only need to be performed once per project by manipulating the build process in some form. You can also refer to our documentation for more information.

Step 1: Indexing source maps

Noted above, the SHA-256 hash is the value used as the index by which the source maps are searched. The source map, however, doesn’t have a built-in notion of what this hash is.

The easiest way to on-board the source map index is to add a property to your source map — x_microsoft_symbol_client_key. This should contain a lowercase hexadecimal representation of the SHA-256 hash of your script. This should happen as late in the build process as possible, because modifications to the JavaScript files will necessarily change the hash

Thus, if you have a script file “index.js” with a hash of abc10204bcd21215cde32326def43437abc10204bcd21215cde32326def43437, the “index.js.map” file should have the field added to it:

{
  // …
  "x_microsoft_symbol_client_key": 
    "abc10204bcd21215cde32326def43437abc10204bcd21215cde32326def43437"
}

Step 2: Making source maps available on Symbol Server

After adding the index keys to the source maps, we have what we need to publish them for access.

Publishing with Azure DevOps Pipelines

Azure DevOps Pipelines provides a convenient way to on-board your source maps to the Azure Artifacts Symbol Server. If you’re already using Azure DevOps Pipelines to build your web application, it should be as trivial as adding a new task into the pipeline and telling it to publish JS Source Maps (the default is PDBs).

If you are using this task, you should add this after you have added the x_microsoft_symbol_client_key field to your Source Map payload.

Alternative: Manually Publishing with Microsoft Azure Artifacts Symbol Server

Discussing the specifics around Azure Artifacts is a bit out of scope for the purpose of this document. It’s sufficient to say that it’s effectively a secure file storage service, and Edge DevTools knows how to talk to it. You can learn more about this service specifically at Symbol files – Azure Artifacts.

If you are unable to use the pipeline task or Symbol.exe tool for some reason, the Azure Artifacts Service  has a REST-based API that can be used. The “debug entry client key” used by the Symsrv protocol is generally of the format <source map file name>/<hash>/<source map file name>.

Step 3: Connecting Microsoft Edge to Azure DevOps

This is reasonably straightforward and requires a Personal Access Token, or PAT. To do so, open your Azure DevOps website and search for the User Settings menu, typically adjacent to your user profile picture. Open the menu and click Personal access tokens.

Azure DevOps "User Settings" menu with the "Personal access tokens" item highlighted

From here, name the token and give it an expiration date as appropriate. Click Show all scopes near the bottom of the dialog window, and near the end of the list of scopes select Read in the Symbols scope. Finally click Create to create a PAT.

Then, in Edge DevTools, go into the Settings (F1), click the Symbol Server tab, enter the name of your Azure DevOps organization (if you interact with Azure DevOps at, for instance, contoso.visualstudio.com, then the organization is “contoso”) and paste your PAT into the appropriate box. Close the Settings panel and click the Reload DevTools button.

Symbol Server settings in Edge DevTools with the Azure DevOps organization and personal access token fields displayed

Now, when debugging an official build of your website, for which debugging symbols have been published, your original development source files will be used in DevTools. They will be downloaded securely from the Azure Artifacts symbol server by DevTools and displayed in the Sources and Console tools when debugging code.

Source maps haven’t evolved much since 2011, but we’re engaging with the community to try to improve them. In Microsoft Edge 99, we introduced the ability to retrieve them for in-production debugging, and in Edge 100, we now also include metadata about your active scripts as part of exporting Performance traces. This will allow you to get the right source maps loaded to view a performance profile with the code that ran at the time it was captured.

In the future, we also would like to make it possible for Edge DevTools extensions to resolve source maps from stores other than Azure DevOps. There isn’t any define date for this yet, and we would love to hear your feedback about it first. Please feel free to drop us a comment on this feedback GitHub issue.

We are also planning to improve caching for Source Maps. We’ve heard feedback that downloading source maps can take a long time and we’re experimenting with bypassing the HTTP cache altogether in favor of a keyed index. We don’t have a timeline for this yet either.

Finally, we’re also actively engaging with the TC39 Tools Working Group and interested members of the JavaScript community to determine how to enhance Source Maps with additional information. This should help improve the kinds of experiences you’re able to get while debugging, whether it’s live or in crash analysis. Please join in on the discussion if this is interesting to you.

– Rob Paveza, Principal Software Engineer, Microsoft Edge



Source link

Leave a Reply

Your email address will not be published.