Skip to content

Commit

Permalink
Add documentation for SDK Load Failure error details (#1265)
Browse files Browse the repository at this point in the history 
[BUG] Argument order for stopTrackPage method #1253
  • Loading branch information
@MSNev
MSNev committed May 12, 2020
1 parent 5cb9e44 commit 00ad742
Show file tree
Hide file tree
Showing 5 changed files with 308 additions and 11 deletions.
51 changes: 40 additions & 11 deletions README.md
View file
Expand Up @@ -71,15 +71,43 @@ cfg: { // Application Insights Configuration
</script>
```

The snippet supports reporting sdk script load failures as exceptions to the portal, this type of error would cause your application/website to either not report any telemetry or in some extreme cases become unstable due to excessive queuing of events which are never sent.
> :bulb: **Note**
>
> For readability and to reduce possible JavaScript errors, all of the possible configuration options are listed on a new line in snippet code above, if you don't want to change the value of a commented line it can be removed.
#### Reporting Script load exceptions

This version of the snippet detects and reports an exception when loading the SDK from the CDN fails, this exception is reported to the Azure Monitor portal (under the failures &gt; exceptions &gt; browser), and provides visibility into failures of this type so that you are aware your application is not reporting telemetry (or other exceptions) as expected. This signal is an important measurement in understanding that you have lost telemetry because the SDK did not load or initialize, this provides clarity that you are missing the following telemetry:
- Under-reporting of how users are using (or trying to use) your site;
- Missing telemetry on how your end users are using your site;
- Missing JavaScript errors that could potentially be blocking your end users from successfully using your site.

For details on this exception see [SDK Load Failure](docs/SdkLoadFailure.md) page.

Reporting of this failure as an exception to the portal does not use the configuration option ```disableExceptionTracking``` from the application insights configuration and therefore if this failure occurs it will always be reported by the snippet, even when the window.onerror support is disabled.

Reporting of SDK load exceptions is specifically NOT supported on IE 8 (or less). This assists with reducing the minified size of the snippet by assuming that most environments are not exclusively IE 8 or less. If you have this requirement and you wish to receive these exceptions, you will need to either include a fetch poly fill or create you own snippet version that uses ```XDomainRequest``` instead of ```XMLHttpRequest```, it is recommended that you use the [provided snippet source code](https://github.com/microsoft/ApplicationInsights-JS/blob/master/AISKU/snippet/snippet.js) as a starting point.

> :bulb: **Note**
>
> If you are using a previous version of the snippet, it is highly recommended that you update to the latest version so that you will receive these previously unreported issues.
#### Snippet configuration options

All configuration options have now been move towards the end of the script to help avoid accidentally introducing JavaScript errors that would not just cause the SDK to fail to load, but also it would disable the reporting of the failure.

Each configuration option is shown above on a new line, if you don't wish to override the default value of an item listed as [optional] you can remove that line to minimize the resulting size of your returned page.

The available configuration options are

It also supports some additional snippet specific configuration.
- src (string) [required] - The URL of the SDK version to load
- name (string) [optional] - The global SDK instance name to use, defaults to appInsights
- ld (number in ms) [optional] - Defines the load delay to wait before attempting to load the SDK. Default value is 0ms and any negative value will just add a script tag to the page head and will block the page load event.
- useXhr (boolean) [optional] - This setting is specifically for the reporting of SDK load failures. Reporting will first use fetch() if available and then fallback to XHR, setting this value to true just bypasses the fetch check. Use of this value would only be required if you know your app/site is being used in an environment where fetch would fail to send the failure events.
- crossOrigin (string) [optional] - By including this setting the script tag used to download the SDK will include the crossOrigin attribute with this string value. When not defined (the default) no crossOrigin attribute is added. Recommended values are not defined (the default); ""; or "anonymous" (For all valid values see https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin)
- cfg (object) - This is the Application Insights configuration that is used to initialize your sdk.
| Name | Type | Description
|------|------|----------------
| src | string **[required]** | The full URL for where to load the SDK from. This value is used for the "src" attribute of a dynamically added &lt;script /&gt; tag. You can use the public CDN location or your own privately hosted one.
| name | string *[optional]* | The global name for the initialized SDK, defaults to appInsights. So ```window.appInsights``` will be a reference to the initialized instance. Note: if you provide a name value or a previous instance appears to be assigned (via the global name appInsightsSDK) then this name value will also be defined in the global namespace as ```window.appInsightsSDK=<name value>```, this is required by the SDK initialization code to ensure it's initializing and updating the correct snippet skeleton and proxy methods.
| ld | number in ms *[optional]* | Defines the load delay to wait before attempting to load the SDK. Default value is 0ms and any negative value will immediately add a script tag to the &lt;head&gt; region of the page, which will then block the page load event until to script is loaded (or fails).
| useXhr | boolean *[optional]* | This setting is used only for reporting SDK load failures. Reporting will first attempt to use fetch() if available and then fallback to XHR, setting this value to true just bypasses the fetch check. Use of this value is only be required if your application is being used in an environment where fetch would fail to send the failure events.
| crossOrigin | string *[optional]* | By including this setting, the script tag added to download the SDK will include the crossOrigin attribute with this string value. When not defined (the default) no crossOrigin attribute is added. Recommended values are not defined (the default); ""; or "anonymous" (For all valid values see [HTML attribute: crossorigin](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) documentation)
| cfg | object **[required]** | THe configuration passed to the Application Insights SDK during initialization.

### Connection String Setup

Expand Down Expand Up @@ -126,9 +154,9 @@ appInsights.trackTrace({message: 'some trace'});
appInsights.trackMetric({name: 'some metric', average: 42});
appInsights.trackDependencyData({absoluteUrl: 'some url', responseCode: 200, method: 'GET', id: 'some id'});
appInsights.startTrackPage("pageName");
appInsights.stopTrackPage("pageName", {customProp1: "some value"});
appInsights.stopTrackPage("pageName", null, {customProp1: "some value"});
appInsights.startTrackEvent("event");
appInsights.stopTrackEvent("event", {customProp1: "some value"});
appInsights.stopTrackEvent("event", null, {customProp1: "some value"});
appInsights.flush();
```

Expand Down Expand Up @@ -379,7 +407,8 @@ While the script downloads from the CDN, all tracking of your page is queued. On

> Summary:
>
> - **~28 KB** gzipped
> - ![current npm version](https://badge.fury.io/js/%40microsoft%2Fapplicationinsights-web.svg)
> - ![gzip compressed size](https://img.badgesize.io/https://js.monitor.azure.com/scripts/b/ai.2.min.js.svg?compression=gzip)
> - **15 ms** overall initialization time
> - **Zero** tracking missed during life cycle of page
Expand Down
131 changes: 131 additions & 0 deletions docs/SdkLoadFailure.md
View file
@@ -0,0 +1,131 @@
# SDK Load Failure: Failed to load Application Insights SDK script (see stack for details)

This exception is created and reported by the snippet (v3 or later) when it detects that the SDK script failed to download or initialize. Simplistically, your end users client (browser) was unable to download the Application Insights SDK, or initialize from the identified hosting page and therefore no telemetry or events will be reported.

<p><img src="./media/sdk-load-failure-overview.png" alt="Azure portal browser failure overview" style="border: lightgray 2px solid" /></p>

> :bulb: **Note**
>
> This exception is supported on all major browsers that support the fetch() API or XMLHttpRequest, this therefore explicitly excludes IE 8 and below, so you will not get this type of exception reported from those browsers (unless your environment includes a fetch polyfill).
## What does this exception mean?

There are many possible reasons for this exception to be reported, we will cover some of the known issues as well the details to diagnose the root cause of the problem.

<p><img src="./media/sdk-load-failure-exception.png" alt="browser exception detail" style="border: lightgray 2px solid" /></p>

The stack details include the basic information with the URLs being used by the end user and is formatted as below

> SDK LOAD Failure: Failed to load Application Insights SDK script (See stack for details)<br />
> Snippet failed to load [__&lt;CDN&nbsp;Endpoint&gt;__] -- Telemetry is disabled<br />
> Help Link: __&lt;Help&nbsp;Link&gt;__<br />
> Host: __&lt;Host&nbsp;URL&gt;__<br />
> Endpoint: __&lt;Endpoint&nbsp;URL&gt;__<br />
| Name | Description
|----------------------|------------
| &lt;CDN&nbsp;Endpoint&gt; | The URL that was used (and failed) to download the SDK
| &lt;Help&nbsp;Link&gt; | A help link URL that links to this page
| &lt;Host&nbsp;URL&gt; | The complete URL of the page that the end user was using
| &lt;Endpoint&nbsp;URL&gt; | The URL that was used to report the exception, this value may be helpful in identifying whether the hosting page was accessed from the public internet or a private cloud.

## Why did this exception occur?

There are many possible reasons for this exception to be reported, and the most common ones are described below with links to corresponding troubleshooting steps.

> :bulb: **Note**
>
> Several of the Troubleshooting steps assume that your application has direct control of the Snippet &lt;script /&gt; tag and it's configuration that are returned as part of the hosting HTML page. If you don't then those identified steps will not apply for your scenario.
## The Application Insights JS CDN has been blocked

While typically NOT the cause for this exception, we recommend you rule it out first since there are limited options for you or your end users and may require immediate external assistance.

### Troubleshooting

- [Check if the CDN has been blocked](SdkLoadFailureSteps.md#cdn-blocked)
- [Change the URL used to download the SDK](SdkLoadFailureSteps.md#change-the-cdn-endpoint)
- [Host the SDK on you own CDN](SdkLoadFailureSteps.md#host-sdk)
- [Use NPM packages to embed the Application Insights SDK](SdkLoadFailureSteps.md#use-npm).

## Intermittent network connectivity failure

This is the most common reason for seeing this exception, though it may seem largely out of the developer's control. It's especially common in a mobile roaming scenario where the user looses network connectivity intermittently.

To minimize this issue, we have implemented Cache-Control headers on all of the CDN files so that once the end users browser has downloaded the current version of the SDK it will not need to downloaded again and the browser will reuse the previously obtained copy (see [How caching works](https://docs.microsoft.com/azure/cdn/cdn-how-caching-works)). If the caching check fails or there has been a new release, then your end users browser will need and download the updated version, so you may see a background level of _"noise"_ in the check failure scenario or a temporary spike when a new release occurs and is made generally available (deployed to the CDN).

If this exception is persistent and is occurring across many of your users (diagnosed by a rapid and sustained level of this exception being reported) along with a reduction in normal client telemetry, then intermittent network connectivity issues is _not-likely_ to be the true cause of the problem and you should continue diagnosing with the other known possible issues below.

### Troubleshooting

- [Intermittent Network failure](SdkLoadFailureSteps.md#intermittent-network-failure)
- [Use NPM packages to embed the Application Insights SDK](SdkLoadFailureSteps.md#use-npm).

> :bulb: **Note**
>
> Due to the caching headers on the CDN files and depending on how often and when your users access your site, not all of them will attempt to download the newer version at the same point in time, so reports may be staggered.
## Application Insights JS CDN is blocked (by End User - blocked by browser; installed blocker; Personal firewall)

Check if your end users have installed: -
- a browser plug-in (typically some form of Ad/Malware/Popup blocker);
- blocked (or not allowed) the Application Insights CDN endpoints in their browser or proxy;
- or configured a firewall rule that is causing the CDN domain for the SDK to be blocked (or the DNS entry to not be resolved).

If they have configured any of these options, you will need to work with them (or provide documentation) to allow the CDN endpoints.

It is also possible that the plug-in they have installed is using the [public blocklisting](SdkLoadFailureSteps.md#cdn-blocked), which is why that option is listed first, if you get here then it's most likely some other manually configured solution or it's using a private domain blocklisting.

### Troubleshooting

- [Check if CDN has been blocked](SdkLoadFailureSteps.md#cdn-blocked)
- [Change the URL used to download the SDK](SdkLoadFailureSteps.md#change-the-cdn-endpoint)
- [Add exceptions for CDN endpoints](SdkLoadFailureSteps.md#add-exceptions-for-cdn-endpoints)
- [Host the SDK on you own CDN](SdkLoadFailureSteps.md#host-sdk)
- [Use NPM packages to embed the Application Insights SDK](SdkLoadFailureSteps.md#use-npm).

> :bulb: **Note**
>
> For this exception to be reported, they would not be blocking the reporting endpoint (otherwise you would not see the exception).
## Application Insights CDN is blocked (by Corporate firewall)

If your end users are on a corporate network, then they are most likely behind some form of firewall solution and it's likely that their IT department has implemented some form of internet filtering system. In this case, you will need to work with them to allow the necessary rules for your end users.

### Troubleshooting

- [Check if CDN has been blocked](SdkLoadFailureSteps.md#cdn-blocked)
- [Change the URL used to download the SDK](SdkLoadFailureSteps.md#change-the-cdn-endpoint)
- [Add exceptions for CDN endpoints for corporations](SdkLoadFailureSteps.md#corporate-exceptions-for-cdn-endpoints)
- [Host the SDK on you own CDN](SdkLoadFailureSteps.md#host-sdk)
- [Use NPM packages to embed the Application Insights SDK](SdkLoadFailureSteps.md#use-npm).

> :bulb: **Note**
>
> For this exception to be reported, they would not be blocking the reporting endpoint (otherwise you would not see the exception).
## Application Insights CDN outage

You can confirm this scenario by attempting to access the CDN endpoint directly from the browser (for example, https://az416426.vo.msecnd.net/scripts/b/ai.2.min.js) from a different location to that of your end users (probably from your own development machine - assuming that your organization has not blocked this domain).

### Troubleshooting

- [Create a support ticket](https://azure.microsoft.com/support/create-ticket/) with details of the outage and the CDN endpoint that is experiencing the issue.
- [Change the URL used to download the SDK](SdkLoadFailureSteps.md#change-the-cdn-endpoint)

### SDK failed to initialize after loading the script

There are several possible reasons that may cause the script to fail during initialization, when this occurs the SDK &lt;script /&gt; was successfully downloaded from the cdn but it fails during initialization. This issue can be because of one or more missing dependencies; invalid or some form of JavaScript exception.

The first thing to check is whether the SDK was successfully downloaded, if the script was NOT downloaded then this scenario is __not__ the failing scenario.

Quick check: Using a browser that supports Developer tools (F12), validate on the network tab that the script defined in the ```src``` snippet configuration was downloaded with a response code of 200 (success) or a 304 (not changed). You could also use a tool like fiddler to review the network traffic.

### Troubleshooting

- [SDK Failed to initialize](SdkLoadFailureSteps.md#sdk-failed-to-initialize)

## <a name="next"></a> Next steps
* [Get additional help by filing an issue on GitHub](https://github.com/Microsoft/ApplicationInsights-JS/issues)
* [Back to Snippet setup](../README.md#reporting-script-load-failures)

0 comments on commit 00ad742

Please sign in to comment.