Merge pull request #106590 from lgayhardt/appinsightsjssourcemap0320

App Insights Source Map for JS

Author: GitHubber17

articles/azure-monitor/app/javascript.md

@@ -60,17 +60,17 @@ var sdkInstance="appInsightsSDK";window[sdkInstance]="appInsights";var aiName=wi
 By default the Application Insights JavaScript SDK autocollects a number of telemetry items that are helpful in determining the health of your application and the underlying user experience. These include:
 
 - **Uncaught exceptions** in your app, including information on
-	- Stack trace
-	- Exception details and message accompanying the error
-	- Line & column number of error
-	- URL where error was raised
+    - Stack trace
+    - Exception details and message accompanying the error
+    - Line & column number of error
+    - URL where error was raised
 - **Network Dependency Requests** made by your app **XHR** and **Fetch** (fetch collection is disabled by default) requests, include information on
-	- Url of dependency source
-	- Command & Method used to request the dependency
-	- Duration of the request
-	- Result code and success status of the request
-	- ID (if any) of user making the request
-	- Correlation context (if any) where request is made
+    - Url of dependency source
+    - Command & Method used to request the dependency
+    - Duration of the request
+    - Result code and success status of the request
+    - ID (if any) of user making the request
+    - Correlation context (if any) where request is made
 - **User information** (for example, Location, network, IP)
 - **Device information** (for example, Browser, OS, version, language, resolution, model)
 - **Session information**
@@ -91,6 +91,7 @@ appInsights.trackTrace({message: 'This message will use a telemetry initializer'
 appInsights.addTelemetryInitializer(() => false); // Nothing is sent after this is executed
 appInsights.trackTrace({message: 'this message will not be sent'}); // Not sent
 ```
+
 ## Configuration
 Most configuration fields are named such that they can be defaulted to false. All fields are optional except for `instrumentationKey`.
 
@@ -151,7 +152,7 @@ Currently, we offer a separate [React plugin](#react-extensions) which you can i
 
 ## Explore browser/client-side data
 
-Browser/client-side data can be viewed by going to **Metrics** and adding individual metrics you are interested in: 
+Browser/client-side data can be viewed by going to **Metrics** and adding individual metrics you are interested in:
 
 ![](./media/javascript/page-view-load-time.png)
 
@@ -161,15 +162,15 @@ Select **Browser** and then choose **Failures** or **Performance**.
 
 ![](./media/javascript/browser.png)
 
-### Performance 
+### Performance
 
 ![](./media/javascript/performance-operations.png)
 
 ### Dependencies
 
 ![](./media/javascript/performance-dependencies.png)
 
-### Analytics 
+### Analytics
 
 To query your telemetry collected by the JavaScript SDK, select the **View in Logs (Analytics)** button. By adding a `where` statement of `client_Type == "Browser"`, you will only see data from the JavaScript SDK and any server-side telemetry collected by other SDKs will be excluded.
 
@@ -190,7 +191,14 @@ dataset
 
 ### Source Map Support
 
-The minified callstack of your exception telemetry can be unminified in the Azure portal. All existing integrations on the Exception Details panel will work with the newly unminified callstack. Drag and drop source map unminifying supports all existing and future JS SDKs (+Node.JS), so you do not need to upgrade your SDK version. To view your unminified callstack,
+The minified callstack of your exception telemetry can be unminified in the Azure portal. All existing integrations on the Exception Details panel will work with the newly unminified callstack.
+
+#### Link to Blob storage account
+
+You can link your Application Insights resource to your own Azure Blob Storage container to automatically unminify call stacks. To get started, see [automatic source map support](./source-map-support.md).
+
+### Drag and drop
+
 1. Select an Exception Telemetry item in the Azure portal to view its "End-to-end transaction details"
 2. Identify which source maps correspond to this call stack. The source map must match a stack frame's source file, but suffixed with `.map`
 3. Drag and drop the source maps onto the call stack in the Azure portal
@@ -208,7 +216,7 @@ This version comes with the bare minimum number of features and functionalities
 
 For runnable examples, see [Application Insights JavaScript SDK Samples](https://github.com/topics/applicationinsights-js-demo)
 
-## Upgrading from the old Version of Application Insights
+## Upgrading from the old version of Application Insights
 
 Breaking changes in the SDK V2 version:
 - To allow for better API signatures, some of the API calls, such as trackPageView and trackException, have been updated. Running in Internet Explorer 8 and earlier versions of the browser is not supported.

articles/azure-monitor/app/media/source-map-support/azure-file-copy.png

@@ -0,0 +1,88 @@
+---
+title: Source map support for JavaScript applications - Azure Monitor Application Insights
+description: Learn how to upload source maps to your own storage account Blob container using Application Insights.
+ms.topic: conceptual
+author: markwolff
+ms.author: marwolff
+ms.date: 03/04/2020
+
+---
+
+# Source map support for JavaScript applications
+
+Application Insights supports the uploading of source maps to your own Storage Account Blob Container.
+Source maps can be used to unminify call stacks found on the end to end transaction details page. Any exception sent by the [JavaScript SDK][ApplicationInsights-JS] or the [Node.js SDK][ApplicationInsights-Node.js] can be unminified with source maps.
+
+![Unminify a Call Stack by linking with a Storage Account](./media/source-map-support/details-unminify.gif)
+
+## Create a new storage account and Blob container
+
+If you already have an existing storage account or blob container, you can skip this step.
+
+1. [Create a new storage account][create storage account]
+2. [Create a blob container][create blob container] inside your storage account. Be sure to set the "Public access level" to `Private`, to ensure that your source maps are not publicly accessible.
+
+> [!div class="mx-imgBorder"]
+>![Your container access level must be set to Private](./media/source-map-support/container-access-level.png)
+
+## Push your source maps to your Blob container
+
+You should integrate your continuous deployment pipeline with your storage account by configuring it to automatically upload your source maps to the configured Blob container. You should not upload your source maps to a subfolder in the Blob container; currently the source map will only be fetched from the root folder.
+
+### Upload source maps via Azure Pipelines (recommended)
+
+If you are using Azure Pipelines to continuously build and deploy your application, add an [Azure File Copy][azure file copy] task to your pipeline to automatically upload your source maps.
+
+> [!div class="mx-imgBorder"]
+> ![Add an Azure File Copy task to your Pipeline to upload your source maps to Azure Blob Storage](./media/source-map-support/azure-file-copy.png)
+
+## Configure your Application Insights resource with a Source Map storage account
+
+### From the end-to-end transaction details page
+
+From the end-to-end transaction details tab, you can click on *Unminify* and it will display a prompt to configure if your resource is unconfigured.
+
+1. In the Portal, view the details of an exception that is minified.
+2. Click on *Unminify*
+3. If your resource has not been configured, a message will appear, prompting you to configure.
+
+### From the properties page
+
+If you would like to configure or change the storage account or Blob container that is linked to your Application Insights Resource, you can do it by viewing the Application Insights resource's *Properties* tab.
+
+1. Navigate to the *Properties* tab of your Application Insights resource.
+2. Click on *Change source map blob container*.
+3. Select a different Blob container as your source maps container.
+4. Click `Apply`.
+
+> [!div class="mx-imgBorder"]
+> ![Reconfigure your selected Azure Blob Container by navigating to the Properties Blade](./media/source-map-support/reconfigure.png)
+
+## Troubleshooting
+
+### Required role-based access control (RBAC) settings on your Blob container
+
+Any user on the Portal using this feature must be at least assigned as a [Storage Blob Data Reader][storage blob data reader] to your Blob container. You must assign this role to anyone else that will be using the source maps through this feature.
+
+> [!NOTE]
+> Depending on how the container was created, this may not have been automatically assigned to you or your team.
+
+### Source map not found
+
+1. Verify that the corresponding source map is uploaded to the correct blob container
+2. Verify that the source map file is named after the JavaScript file it maps to, suffixed with `.map`.
+    - For example, `/static/js/main.4e2ca5fa.chunk.js` will search for the blob named `main.4e2ca5fa.chunk.js.map`
+3. Check your browser's console to see if any errors are being logged. Include this in any support ticket.
+
+## Next Steps
+
+* [Azure File Copy task](https://docs.microsoft.com/azure/devops/pipelines/tasks/deploy/azure-file-copy?view=azure-devops)
+
+
+<!-- Remote URLs -->
+[create storage account]: https://docs.microsoft.com/azure/storage/common/storage-account-create?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal
+[create blob container]: https://docs.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-portal
+[storage blob data reader]: https://docs.microsoft.com/azure/role-based-access-control/built-in-roles#storage-blob-data-reader
+[ApplicationInsights-JS]: "https://github.com/microsoft/applicationinsights-js"
+[ApplicationInsights-Node.js]: "https://github.com/microsoft/applicationinsights-node.js"
+[azure file copy]: "https://aka.ms/azurefilecopyreadme"

articles/azure-monitor/app/media/source-map-support/container-access-level.png

@@ -213,6 +213,8 @@
         items:
         - name: Client-side JavaScript
           href: app/javascript.md
+        - name: Source map for JavaScript
+          href: app/source-map-support.md
       - name: Application Insights API summary
         displayname: SDK, API, custom events, custom metrics, trackevent,trackmetric, getmetric, trackrequest, trackexception, tracktrace, trackdependency
         href: app/api-custom-events-metrics.md