The tyGraph Pages Engine Health Check allows customers to verify that the engine is installed correctly and collecting telemetry. Support may ask you to use the health check to troubleshoot issues collecting telemetry. The health check validates connectivity for the current user viewing the web part. If you suspect multiple users or locations may have issues, you should try the health check with those users and locations.
TABLE OF CONTENTS
- Enable the Health Check
- Exploring the Health Check
Enable the Health Check
You can enable Health Check from the tyGraph Pages Site Analytics web part. If you have not installed and configured the web part, follow these instructions. After you have configured the web part as described in the instructions with an Application Id and API key, edit the web part and check the box Show tyGraph Pages Engine health check under the Debugging section.
Note: the Health Check is available in tyGraph Pages Web Part version 22.214.171.124 (20210413.1) and later (currently in preview). Some features are not available unless tyGraph Pages Engine version 126.96.36.199 (20210413.0) is installed.
Exploring the Health Check
The Health Check validates that the tyGraph Pages Engine can connect to the tyGraph API as well as capture telemetry.
API Connection Test
The API Connection Test will validate that the tyGraph Pages Engine can connect to the tyGraph API to get the instrumentation key and license information. Each user will make a call to this endpoint once per day but the data is cached locally and is valid for thirty days if the API cannot be reached. For a browser to successfully log telemetry, this call must be successful at least once. A successful API Connection Test will look like the screen below.
The API Connection Test shows both the values retrieved directly rom the API as well as when the last values were cached in your browser. The meaning of the values are as defined below:
- tenantId - your Azure Active Directory tenant id
- instrumentaitonKey - your Application Insights instrumentation key.
- expirationDate - license expiration date
- isActive - true if your subscription is active
- modifiedDate - date values were retrieved from the API
- obfuscate - obfuscation settings (none, partial, or all) - controls whether user names and E-mail addresses are obfuscated for requirements such as GDPR
- obfuscateCountries - list of all countries whose users that should be obfuscated when obfuscate has a value of partial. User's countries are compared using the Usage Location associated with the user's Microsoft 365 license
If you need to update any of the values, please contact Support.
Troubleshooting errors with the API Connection Test
If you receive an error such as "failed to fetch" or a "CORS" error, this indicates a problem reaching our CDN or API. Our application tries to reach the CDN first and will fall back to our API if unsuccessful. Our API is hosted in Azure in the North Central US region. If your network infrastructure includes proxies, cloud firewall services, or restrictive firewall rules, you may need to consider whitelisting our API. You may also configure caching the result with your network infrastructure while recognizing the cache-control headers that are present. The current API URL will be displayed in the Configuration section of the Health Check.
To clear the information tyGraph Pages caches in the browser for the current user, click the Purge Cache button. This will remove items from the browser's local storage and IndexedDB.
Application Insights Test
This tests confirms the connection to the Azure Application Insights Service. The test will log a customEvent to Application Insights. The list below it will show you the last ten previous Health Check events that have been logged to Application Insights. A successful test will show you an entry for your session. Due to processing times with Application Insights, it may take up to five minutes for the latest events to show. You may click the refresh button on the test to query again and see the events.
The test will show you the timestamp, city, state / province, and country of the health check event as reported by Application Insights. To respect user privacy, Application Insights does not use the browsers geolocation API. Instead it associates your location with a geolocation IP database as described in this support article. If you are not seeing the location you expect, consider contacting the provider of the database MaxMind. You can validate your location data from this page.
Troubleshooting the API Connection Test
After five minutes, if you are not seeing any results from the test, verify your Application Insights Id and API key that you have configured in the web part. Not that the Application Insights Id is not the same as the Instrumentation key. You can validate authentication is working correctly if you see any of the reports such as Page Views rendering charts below the Health Check.
If you receive an error such as "failed to fetch" or a "CORS" error, this indicates a problem reaching the Application Insights API. If your network infrastructure includes proxies, cloud firewall services, or restrictive firewall rules, you may need to consider whitelisting our API. Refer to Microsoft's article on which IP addresses they recommend to whitelist. You only need to consider the IP addresses listed in the Telemetry section of the article.
This section gives you a snapshot of the configuration used and various statistics about the tyGraph Pages Engine. You can use this section to verify your versions, installation status and API URLs.
Depending on your configuration and versions, you may not have all properties listed above. The properties are defined as follows:
- tyGraph Pages engine installed - true if the tyGraph Pages Engine application customizer is installed
- License valid - true if a license can be retrieved from the API, the subscription is valid and has not expired
- Web Part Version - version of the tyGraph Pages web parts
- Engine Version - version of the tyGraph Pages engine (requires 20210413.0 or later)
- Microsoft Graph Usage Location - for partial obfuscation, the usage location as defined in your Microsoft 365 license
- Last Ping Date - last successful ping to tyGraph telemetry
- License API URL - URL for the License API
- Application Insights API URL - URL for Application Insights
The tyGraph Pages Engine Health Check allows you to troubleshoot issues when capturing telemetry. The results of this page are unique to the user / browser executing it. Other users may get different results when attempting the connection tests. If you are seeing connection failures, we recommend contacting your network infrastructure team to discuss potential causes and review the network requirements for tyGraph Pages.. Please contact Support if you have any other questions.