AB#180415: Change heading levels in Application Insights JavaScript SDK troubleshooting article (#4849)

DennisLee-DennisLee · przlplx · web-flow · commit df21d8e77a54 · 2023-08-31T13:42:35.000-07:00
* Demoted the Symptoms and Cause X sections. A few other edits.

* A few minor changes.

* Update javascript-sdk-troubleshooting.md

---------

Co-authored-by: Jerry Sitser &lt;36421998+przlplx@users.noreply.github.com&gt;
diff --git a/support/azure/azure-monitor/app-insights/javascript-sdk-troubleshooting.md b/support/azure/azure-monitor/app-insights/javascript-sdk-troubleshooting.md
@@ -1,7 +1,7 @@
 ---
 title: Troubleshoot issues that involve the App Insights JavaScript SDK
 description: Learn how to troubleshoot SDK load failure for JavaScript web applications, Azure Application Insights for web pages, and source map support for JavaScript apps.
-ms.date: 06/07/2023
+ms.date: 08/31/2023
 editor: v-jsitser
 ms.service: azure-monitor
 ms.subservice: application-insights
@@ -12,7 +12,7 @@ ms.reviewer: mmcc, toddfous, aaronmax, v-leedennis
 
 # Application Insights JavaScript SDK troubleshooting
 
-This article discusses how to troubleshoot various issues that involve the [Application Insights JavaScript SDK](https://github.com/Microsoft/ApplicationInsights-JS). The subjects in this article include SDK load failure for JavaScript web apps, App Insights for web pages, and source map support for JavaScript apps.
+This article discusses how to troubleshoot various issues that involve the [Application Insights JavaScript SDK](https://github.com/Microsoft/ApplicationInsights-JS). The subjects in this article include SDK load failure for JavaScript web apps and source map support for JavaScript apps.
 
 <!-- 
 Editor's Note: This link name above "SDK Load Failure" has a direct references by https://go.microsoft.com/fwlink/?linkid=2128109 which is embedded in the snippet and from the JavaScript Page. If you change this text you MUST also update these references.
@@ -22,15 +22,15 @@ Editor's Note: This link name above "SDK Load Failure" has a direct references b
 
 The following sections discuss the symptoms, causes, and solutions for a specific SDK load failure scenario for JavaScript web apps.
 
-## Symptoms
+### Symptoms
 
 In the \<head> element of the web page that you're monitoring, the [JavaScript snippet][snippet-based-setup] (version 3 or a later version) creates and reports the following exception when it detects that the SDK script didn't download or initialize:
 
 > SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)
 
 This message indicates that the user's client (browser) can't download the Application Insights SDK or initialize from the identified hosting page. Therefore, you don't see any telemetry or events.
 
-:::image type="content" source="./media/javascript-sdk-troubleshooting/overview.png" alt-text="Azure portal screenshot of the exception titled 'SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)'." lightbox="./media/javascript-sdk-troubleshooting/overview.png":::
+:::image type="content" source="./media/javascript-sdk-troubleshooting/overview.png" alt-text="Azure portal screenshot of the exception titled 'SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details).'" lightbox="./media/javascript-sdk-troubleshooting/overview.png":::
 
 > [!NOTE]
 > This exception is supported on all major browsers that support the `fetch()` API or `XMLHttpRequest`. These browser versions exclude Microsoft Internet Explorer 8 and earlier versions. Therefore, those browsers will not report this type of exception unless your environment includes a fetch polyfill.
@@ -63,15 +63,15 @@ The following sections discuss how to troubleshoot each potential root cause of
 > [!NOTE]  
 > Some of these steps assume that your application has direct control of the [Snippet \<script /> tag][snippet-based-setup] and its configuration that's returned as part of the hosting HTML page. If these conditions don't apply to your scenario, these steps also don't apply.
 
-## Cause 1: Intermittent network connectivity failure
+### Cause 1: Intermittent network connectivity failure
 
 If the user experiences intermittent network connectivity failures, there are fewer possible solutions than for other causes. However, this failure usually resolves itself quickly. For example, if the user refreshes the page to reload your site, the files eventually get downloaded and cached locally until the release of an updated version.
 
-### Solution 1a: Download an updated version of the SDK
+#### Solution 1a: Download an updated version of the SDK
 
 To minimize intermittent network connectivity failure, we implemented `Cache-Control` headers on all the CDN files. After the user's browser downloads the current version of the SDK, it doesn't have to download it again because it reuses the previously obtained copy. (See [how caching works](/azure/cdn/cdn-how-caching-works).) If the caching check fails or there's a new release available, the user's browser has to download the updated version. Therefore, you might see a background level of *"noise"* in the check failure scenario. Or, you might see a temporary spike when a new release occurs and becomes generally available (deployed to the CDN).
 
-### Solution 1b: Use npm packages to embed the SDK together with the application in a single bundle
+#### Solution 1b: Use npm packages to embed the SDK together with the application in a single bundle
 
 Is the SDK load failure exception persistent, and does it occur for many users together with a reduction in normal client telemetry? In this case, intermittent network connectivity issues probably aren't the true cause of the problem, and you should explore other possible causes.
 
@@ -82,21 +82,21 @@ In this situation, hosting the SDK on your own CDN is unlikely to provide or red
 
 You can try to [use npm packages to embed the Application Insights SDK](#solution-4b3-use-npm-packages-to-embed-the-application-insights-sdk) together with the monitored application in a single bundle. Although an intermittency failure might still occur in this scenario, a combined bundle does offer a real chance of fixing the problem.
 
-## Cause 2: Application Insights CDN outage
+### Cause 2: Application Insights CDN outage
 
 To verify that there's an Application Insights CDN outage, try to access the CDN endpoint directly from the browser from a different location than that of your users. For example, you can try accessing <https://js.monitor.azure.com/scripts/b/ai.2.min.js> from your own development computer. (This assumes that your organization hasn't blocked this domain.)
 
-### Solution 2: Create a support ticket
+#### Solution 2: Create a support ticket
 
 If you verify that an outage exists, you can [create a new support ticket][support-ticket].
 
-## Cause 3: SDK didn't initialize after loading the script
+### Cause 3: SDK didn't initialize after loading the script
 
 If the SDK doesn't initialize, the \<script /> is still successfully downloaded from the CDN, but it fails during initialization. This failure occurs because of missing or invalid dependencies, or because of some form of JavaScript exception.
 
-### Solution 3: Check for a successful SDK download or JavaScript exceptions, or enable browser debugging
+#### Solution 3: Check for a successful SDK download or JavaScript exceptions, or enable browser debugging
 
-#### Step 1: Check for a successful SDK download
+##### Step 1: Check for a successful SDK download
 
 Check whether the SDK downloaded successfully. If no script download occurred, this scenario isn't the cause of the SDK load failure exception. Use a browser that supports developer tools. Select F12 to view the developer tools, and then select the **Network** tab. Verify that the script that's defined in the [src snippet configuration][snippet-configuration-options] was downloaded. To do this, check for response code `200` (success) or `304` (not changed). To review the network traffic, you can also use a web debugging tool such as [Fiddler](https://www.telerik.com/fiddler).
 
@@ -109,7 +109,7 @@ If the SDK didn't download successfully, review the following table to understan
 
 If the SDK downloaded successfully, review the following sections to help fix the SDK initialization problem.
 
-#### Step 2: Check for JavaScript exceptions
+##### Step 2: Check for JavaScript exceptions
 
 Check for JavaScript exceptions. Use a browser that supports developer tools. Select F12 to view the developer tools, load the page, and then check whether any exceptions occurred. Does the SDK script (for example, in *ai.2.min.js*) causes exceptions? In this case, one of the following scenarios occurred:
 
@@ -140,7 +140,7 @@ If the exception disappears, a type mismatch or unexpected value is probably cau
 
 Was your configuration previously deployed and working, but is now reporting this exception? In this case, there might be an issue that affects a newly deployed version. Check whether the exception affects only a small set of your users or browsers. Either [file an issue on GitHub][github-issue] or [create a new support ticket][support-ticket].
 
-#### Step 3: Enable browser console debugging
+##### Step 3: Enable browser console debugging
 
 If no thrown exceptions occurred, you should enable console debugging by adding the [loggingLevelConsole setting][snippet-configuration-fields] to the configuration, as shown in the following snippet configuration example. This change sends all initialization errors and warnings to the browser's console. (To view the browser console, select F12 to open the developer tools, and then select the **Console** tab.) Any reported errors should be self-explanatory. If you need further assistance, [file an issue on GitHub][github-issue].
 
@@ -176,7 +176,7 @@ cfg:{
 
 If this action still doesn't provide any insights, you should [file an issue on GitHub][github-issue] by providing the details and an example site, if you use one. Include the browser version, operating system, and JavaScript framework details to help identify the issue.
 
-## Cause 4: Blockage of the Application Insights JavaScript CDN
+### Cause 4: Blockage of the Application Insights JavaScript CDN
 
 A CDN blockage is possible if an Application Insights JavaScript SDK CDN endpoint is reported or identified as unsafe. In this situation, the endpoint is publicly blocklisted, and consumers of these lists start to block all access.
 
@@ -194,7 +194,7 @@ If the CDN endpoint is identified as unsafe, [create a support ticket][support-t
 
 The following sections outline more specifically how a blockage can occur, and how to fix the blockage.
 
-### Cause 4a: User blockage (browser, installed blocker, or personal firewall)
+#### Cause 4a: User blockage (browser, installed blocker, or personal firewall)
 
 Check whether your users have taken any of the following configuration actions:
 
@@ -204,7 +204,7 @@ Check whether your users have taken any of the following configuration actions:
 
 - Configured a firewall rule that causes a blockage of the CDN domain for the SDK (or a failure to resolve the DNS entry)
 
-#### Solution 4a: Add blocklist exceptions for CDN endpoints
+##### Solution 4a: Add blocklist exceptions for CDN endpoints
 
 If your users took any of the listed configuration actions, work with them (or provide documentation) to allow the CDN endpoints.
 
@@ -214,22 +214,22 @@ Tell your users to allow the downloading of scripts from the Application Insight
 
 Here's an example of this situation that shows how to [configure Google Chrome to allow or block access to websites](https://support.google.com/chrome/a/answer/7532419?hl=en).
 
-### Cause 4b: Corporate firewall blockage
+#### Cause 4b: Corporate firewall blockage
 
 If your users are on a corporate network, the corporate firewall is likely the source of the CDN blockage. The corporate IT department has probably implemented some form of internet filtering system.
 
-#### Solution 4b1: Add exceptions for CDN endpoints for corporations
+##### Solution 4b1: Add exceptions for CDN endpoints for corporations
 
 > [!IMPORTANT]  
 > Do your users use a [private cloud](https://azure.microsoft.com/overview/what-is-a-private-cloud/), and do they not have access to the public internet? In this case, you have to either [use the Application Insights npm packages to embed the SDK](#solution-4b3-use-npm-packages-to-embed-the-application-insights-sdk), or [host the Application Insights SDK on your own CDN](#solution-4b2-host-the-sdk-on-your-own-cdn).
 
 Work with your company's IT department to allow the necessary rules for your users. This solution is similar to [adding exceptions for users](#solution-4a-add-blocklist-exceptions-for-cdn-endpoints). Have the IT department configure the Application Insights CDN endpoints for download by including (or removing) them in any domain blocklisting or allowlisting services.
 
-#### Solution 4b2: Host the SDK on your own CDN
+##### Solution 4b2: Host the SDK on your own CDN
 
 Instead of having users download the Application Insights SDK from the public CDN, you can host the Application Insights SDK on your own CDN endpoint. We recommend that you use a specific version (*ai.2.#.#.min.js*) of the SDK to make it easier to identify which version you're using. Also, update the SDK regularly to the current version (*ai.2.min.js*) so that you can use any bug fixes and new features that become available.
 
-#### Solution 4b3: Use npm packages to embed the Application Insights SDK
+##### Solution 4b3: Use npm packages to embed the Application Insights SDK
 
 Instead of using the [snippet][snippet-based-setup] and [adding public CDN endpoints](#solution-4a-add-blocklist-exceptions-for-cdn-endpoints), you can use the [npm packages](https://www.npmjs.com/package/applicationinsights) to include the SDK as part of your own JavaScript files. The SDK becomes just another package within your own scripts. For more information, see the [npm-based setup][npm-based-setup] section of the Application Insights JavaScript SDK GitHub page.
 
@@ -249,15 +249,15 @@ The following table explains certain issues that involve [source map support for
 
 ## Fix the "Click Event rows with no parentId value" warning
 
-When you use Azure application insights and [Click Analytics auto collection plug-in](/azure/azure-monitor/app/javascript-feature-extensions) in the application, the following telemetry warning may appear in the application insights workbook: "Click Event rows with no parentId value".
+When you use Application Insights and the [Click Analytics Auto-Collection plug-in](/azure/azure-monitor/app/javascript-feature-extensions) in the application, the following telemetry warning might appear in the application insights workbook: "Click Event rows with no parentId value."
 
 ### Cause
 
-This can occur if the `parentid` is not specified in the parent html element, which causes the event to be triggered on all of its parent elements.
+This issue can occur if the parent ID isn't specified in the parent HTML element. This condition causes the event to be triggered on all of its parent elements.
 
 ### Solution
 
-To fix this issue, add the `data-parentid` or `data-<customPrefix>-parentid` to the parent html element. Here is an example of the HTML code:
+To fix this issue, add the `data-parentid` or `data-<customPrefix>-parentid` attribute to the parent HTML element. Here's an example of the HTML code:
 
 ```html
 <div data-heart-id="demo Header" data-heart-parentid="demo.Header" data-heart-parent-group="demo.Header.Group">
