Merge pull request #247306 from v-jbasden/v-jbasden-javascript-sdk-updates-11

Incorporating feedback on App Insights JavaScript SDK docs (part 2)

Author: denrea

articles/azure-monitor/app/javascript-feature-extensions.md

@@ -173,6 +173,8 @@ When you define the `data-parentid` or `data-*-parentid` attribute, the plug-in
 
 If you declare `parentDataTag` and define the `data-parentid` or `data-*-parentid` attribute, precedence is given to `data-parentid` or `data-*-parentid`.
 
+If the "Click Event rows with no parentId value" telemetry warning appears, see [Fix the "Click Event rows with no parentId value" warning](/troubleshoot/azure/azure-monitor/app-insights/javascript-sdk-troubleshooting#fix-the-click-event-rows-with-no-parentid-value-warning).
+
 For examples showing which value is fetched as the `parentId` for different configurations, see [Examples of `parentid` key](#examples-of-parentid-key).
 
 > [!CAUTION]
@@ -250,6 +252,8 @@ To reduce the bytes you pass, pass in the number value instead of the full text
 
 #### Sample usage with behaviorValidator
 
+Here's a sample of what a behavior map validator might look like. Yours could look different, depending on your organization's taxonomy and the events you collect.
+
 ```js
 var clickPlugin = Microsoft.ApplicationInsights.ClickAnalyticsPlugin;
 var clickPluginInstance = new clickPlugin();
@@ -446,6 +450,8 @@ The following examples show which value is fetched as the `parentId` for differe
 
 ### Example 1
 
+In example 1, the `parentDataTag` isn't declared and `data-parentid` or `data-*-parentid` isn't defined in any element.
+
 ```javascript
 export const clickPluginConfigWithUseDefaultContentNameOrId = {
     dataTags : {
@@ -465,10 +471,12 @@ export const clickPluginConfigWithUseDefaultContentNameOrId = {
      </div>
 ```
 
-For example 1, for clicked element `<Button>`, the value of `parentId` is `“not_specified”`, because `parentDataTag` is not declared and the `data-parentid` or `data-*-parentid` is not defined in any element.
+For clicked element `<Button>`, the value of `parentId` is `“not_specified”`, because `parentDataTag` is not declared and the `data-parentid` or `data-*-parentid` is not defined in any element.
 
 ### Example 2
 
+In example 2, `parentDataTag` is declared and `data-parentid` is defined.
+
 ```javascript
 export const clickPluginConfigWithParentDataTag = {
     dataTags : {
@@ -488,9 +496,11 @@ export const clickPluginConfigWithParentDataTag = {
    </div>
 ```
 
-For example 2, for clicked element `<Button>`, the value of `parentId` is `parentid2`. Even though `parentDataTag` is declared, the `data-parentid` definition takes precedence. If the `data-parentid` attribute was defined within the div element with `className=”test2”`, the value for `parentId` would still be `parentid2`.
+For clicked element `<Button>`, the value of `parentId` is `parentid2`. Even though `parentDataTag` is declared, the `data-parentid` definition takes precedence. If the `data-parentid` attribute was defined within the div element with `className=”test2”`, the value for `parentId` would still be `parentid2`.
 
-### Example 3 
+### Example 3
+
+In example 3, `parentDataTag` is declared and the `data-parentid` or `data-*-parentid` attribute isn’t defined.
 
 ```javascript
 export const clickPluginConfigWithParentDataTag = {
@@ -512,7 +522,7 @@ export const clickPluginConfigWithParentDataTag = {
   </div>
 </div>
 ```
-For example 3, for clicked element `<Button>`, because `parentDataTag` is declared and the `data-parentid` or `data-*-parentid` attribute isn’t defined, the value of `parentId` is `test6parent`. It's `test6parent` because when `parentDataTag` is declared, the plug-in fetches the value of the `id` or `data-*-id` attribute from the parent HTML element that is closest to the clicked element. Because `data-group="buttongroup1"` is defined, the plug-in finds the `parentId` more efficiently.
+For clicked element `<Button>`, because `parentDataTag` is declared and the `data-parentid` or `data-*-parentid` attribute isn’t defined, the value of `parentId` is `test6parent`. It's `test6parent` because when `parentDataTag` is declared, the plug-in fetches the value of the `id` or `data-*-id` attribute from the parent HTML element that is closest to the clicked element. Because `data-group="buttongroup1"` is defined, the plug-in finds the `parentId` more efficiently.
 
 If you remove the `data-group="buttongroup1"` attribute, the value of `parentId` is still `test6parent`, because `parentDataTag` is still declared.
 

articles/azure-monitor/app/javascript-sdk-configuration.md

@@ -22,6 +22,8 @@ The Azure Application Insights JavaScript SDK provides configuration for trackin
 
 These configuration fields are optional and default to false unless otherwise stated.
 
+For instructions on how to add SDK configuration, see [Add SDK configuration](./javascript-sdk.md#optional-add-sdk-configuration).
+
 | Name | Type | Default |
 |------|------|---------|
 | accountId<br><br>An optional account ID, if your app groups users into accounts. No spaces, commas, semicolons, equals, or vertical bars | string | null |
@@ -91,7 +93,7 @@ These configuration fields are optional and default to false unless otherwise st
 
 Starting from version 2.6.0, the Azure Application Insights JavaScript SDK provides instance-based cookie management that can be disabled and re-enabled after initialization.
 
-If you disabled cookies during initialization using the `disableCookiesUsage` or `cookieCfg.enabled` configurations, you can re-enable them using the `setEnabled` function of the ICookieMgr object.
+If you disabled cookies during initialization using the `disableCookiesUsage` or `cookieCfg.enabled` configurations, you can re-enable them using the `setEnabled` function of the [ICookieMgr object](https://microsoft.github.io/ApplicationInsights-JS/webSdk/applicationinsights-core-js/interfaces/ICookieMgr.html).
 
 The instance-based cookie management replaces the previous CoreUtils global functions of `disableCookies()`, `setCookie()`, `getCookie()`, and `deleteCookie()`.
 
@@ -121,9 +123,85 @@ Source map support helps you debug minified JavaScript code with the ability to
 > [!div class="checklist"]
 > - Compatible with all current integrations on the **Exception Details** panel
 > - Supports all current and future JavaScript SDKs, including Node.JS, without the need for an SDK upgrade
+
+### Link to Blob Storage account
+
+Application Insights supports the uploading of source maps to your Azure Storage account blob container. You can use source maps to unminify call stacks found on the **End-to-end transaction details** page. You can also use source maps to unminify any exception sent by the [JavaScript SDK][ApplicationInsights-JS] or the [Node.js SDK][ApplicationInsights-Node.js].
+
+![Screenshot that shows selecting the option to unminify a call stack by linking with a storage account.](./media/javascript-sdk-configuration/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].
+1. [Create a blob container][create blob container] inside your storage account. Set **Public access level** to **Private** to ensure that your source maps aren't publicly accessible.
+
+    > [!div class="mx-imgBorder"]
+    >![Screenshot that shows setting the container access level to Private.](./media/javascript-sdk-configuration/container-access-level.png)
+
+#### Push your source maps to your blob container
+
+Integrate your continuous deployment pipeline with your storage account by configuring it to automatically upload your source maps to the configured blob container.
+
+You can upload source maps to your Azure Blob Storage container with the same folder structure they were compiled and deployed with. A common use case is to prefix a deployment folder with its version, for example, `1.2.3/static/js/main.js`. When you unminify via an Azure blob container called `sourcemaps`, the pipeline tries to fetch a source map located at `sourcemaps/1.2.3/static/js/main.js.map`.
+
+##### Upload source maps via Azure Pipelines (recommended)
+
+If you're 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"]
+> ![Screenshot that shows adding an Azure file copy task to your pipeline to upload your source maps to Azure Blob Storage.](./media/javascript-sdk-configuration/azure-file-copy.png)
+
+#### Configure your Application Insights resource with a source map storage account
+
+You have two options for configuring your Application Insights resource with a source map storage account.
+
+##### End-to-end transaction details tab
+
+From the **End-to-end transaction details** tab, select **Unminify**. Configure your resource if it's unconfigured.
+
+1. In the Azure portal, view the details of an exception that's minified.
+1. Select **Unminify**.
+1. If your resource isn't configured, configure it.
+
+##### Properties tab
+
+To configure or change the storage account or blob container that's linked to your Application Insights resource:
+
+1. Go to the **Properties** tab of your Application Insights resource.
+1. Select **Change source map Blob Container**.
+1. Select a different blob container as your source map container.
+1. Select **Apply**.
+
+> [!div class="mx-imgBorder"]
+> ![Screenshot that shows reconfiguring your selected Azure blob container on the Properties pane.](./media/javascript-sdk-configuration/reconfigure.png)
+
+#### Troubleshooting
+
+This section offers troubleshooting tips for common issues related to the uploading of source maps to your Azure Storage account blob container.
+
+##### Required Azure role-based access control settings on your blob container
+
+Any user on the portal who uses this feature must be assigned at least as a [Storage Blob Data Reader][storage blob data reader] to your blob container. Assign this role to anyone who might use the source maps through this feature.
+
+> [!NOTE]
+> Depending on how the container was created, this role might 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.
+1. Verify that the source map file is named after the JavaScript file it maps to and uses the suffix `.map`.
+   
+   For example, `/static/js/main.4e2ca5fa.chunk.js` searches for the blob named `main.4e2ca5fa.chunk.js.map`.
+1. Check your browser's console to see if any errors were logged. Include this information in any support ticket.
+
+### View the unminified callstack
 
 To view the unminified callstack, select an Exception Telemetry item in the Azure portal, find the source maps that match the call stack, and drag and drop the source maps onto the call stack in the Azure portal. The source map must have the same name as the source file of a stack frame, but with a `map` extension.
 
+If you experience issues that involve source map support for JavaScript applications, see [Troubleshoot source map support for JavaScript applications](/troubleshoot/azure/azure-monitor/app-insights/javascript-sdk-troubleshooting#troubleshoot-source-map-support-for-javascript-applications).
+
 :::image type="content" source="media/javascript-sdk-configuration/javascript-sdk-advanced-unminify.gif" alt-text="Animation demonstrating unminify feature.":::
 
 ## Tree shaking
@@ -149,6 +227,8 @@ The static classes were changed to const objects that reference the new exported
 
 ### Tree shaking deprecated functions and replacements
 
+This section only applies to you if you're using the deprecated functions and you want to optimize package size. We recommend using the replacement functions to reduce size and support all the versions of Internet Explorer.
+
 | Existing | Replacement |
 |----------|-------------|
 | **CoreUtils** | **@microsoft/applicationinsights-core-js** |
@@ -249,4 +329,13 @@ See the dedicated [troubleshooting article](/troubleshoot/azure/azure-monitor/ap
 
 * [Track usage](usage-overview.md)
 * [Custom events and metrics](api-custom-events-metrics.md)
-* [Build-measure-learn](usage-overview.md)
+* [Build-measure-learn](usage-overview.md)
+* [Azure file copy task](/azure/devops/pipelines/tasks/deploy/azure-file-copy)
+
+<!-- Remote URLs -->
+[create storage account]: ../../storage/common/storage-account-create.md?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json&tabs=azure-portal
+[create blob container]: ../../storage/blobs/storage-quickstart-blobs-portal.md
+[storage blob data reader]: ../../role-based-access-control/built-in-roles.md#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/javascript-sdk.md

@@ -12,11 +12,17 @@ ms.reviewer: mmcc
 
 The Microsoft Azure Monitor Application Insights JavaScript SDK collects usage data which allows you to monitor and analyze the performance of JavaScript web applications. This is commonly referred to as Real User Monitoring or RUM.
 
+The Application Insights JavaScript SDK has a base SDK and several plugins for additional capabilities.
+
+:::image type="content" source="media/javascript-sdk/conceptual-diagram-javascript-sdk.png" alt-text="Conceptual diagram that shows the Application Insights JavaScript SDK, its plugins/extensions, and their relationship to each other." lightbox="media/javascript-sdk/conceptual-diagram-javascript-sdk.png":::
+
 We collect page views by default. But if you want to also collect clicks by default, consider adding the [Click Analytics Auto-Collection plug-in](./javascript-feature-extensions.md): 
 
 - If you're adding a [framework extension](./javascript-framework-extensions.md), which you can [add](#optional-add-advanced-sdk-configuration) after you follow the steps to get started below, you'll have the option to add Click Analytics when you add the framework extension. 
 - If you're not adding a framework extension, [add the Click Analytics plug-in](./javascript-feature-extensions.md) after you follow the steps to get started.
 
+We provide the [Debug plugin](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-debugplugin-js/README.md) and [Performance plugin](https://github.com/microsoft/ApplicationInsights-JS/blob/main/extensions/applicationinsights-perfmarkmeasure-js/README.md) for debugging/testing. In rare cases, it's possible to build your own extension by adding a [custom plugin](https://github.com/microsoft/ApplicationInsights-JS/blob/e4be62c0aa9318b540157118b729bb0c4d8b6c6e/API-reference.md#custom-extension).
+
 ## Prerequisites
 
 - Azure subscription: [Create an Azure subscription for free](https://azure.microsoft.com/free/)
@@ -142,7 +148,7 @@ If you want to use the extra features provided by plugins for specific framework
    - **Page View** for Azure Monitor Application Insights Real User Monitoring
    - **Custom Event** for the Click Analytics Auto-Collection plug-in.
 
-   It might take a few minutes for data to show up in the portal.
+   It might take a few minutes for data to show up in the portal. If the only data you see showing up is a load failure exception, see [Troubleshoot SDK load failure for JavaScript web apps](/troubleshoot/azure/azure-monitor/app-insights/javascript-sdk-troubleshooting#troubleshoot-sdk-load-failure-for-javascript-web-apps).
 
    :::image type="content" source="media/javascript-sdk/confirm-data-flowing.png" alt-text="Screenshot of the Application Insights Transaction search pane in the Azure portal with the Page View option selected. The page views are highlighted." lightbox="media/javascript-sdk/confirm-data-flowing.png":::