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
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.
Exploring the Health Check
The Health Check validates that the tyGraph Pages Engine can connect to the tyGraph API as well as capture telemetry.
License CDN Connection Test
The License CDN Connection Test will validate that the tyGraph Pages Engine can connect to the tyGraph License CDN 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 CDN cannot be reached. For a browser to successfully log telemetry, this call must be successful at least once. A successful CDN Connection Test will look like the screen below.
The License CDN 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
- obfuscateUserFields - list of fields that you have opted to obfuscate
- disableTelemetry - true if you have opted out of tyGraph telemetry
- disableUserProfileCollection - true if you have opted not to collect user profile information
- excludeSiteUrls - site URLs that are not to have data collected
If you need to update any of the values, please contact Support.
Troubleshooting errors with the License CDN Connection Test
If you receive an error such as "failed to fetch" or a "CORS" error, this indicates a problem reaching our CDN. Please review the network requirements and contact your network team to ensure you have added all listed addresses to your allow lists. Cloud proxies that have not been configured for these known addresses are the leading cause in dropped telemetry. You may also configure caching the result with your network infrastructure while recognizing the cache-control headers that are present.
Purge Cache
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.
tyGraph API Connection Test (Preview)
Limited customers have access to tyGraph API. This test only applies to those customers. For those customers without access to tyGraph API, you will see the following error:
The tyGraph API connection test failed. This may be because you or your tenant has not been onboarded using tyGraph Portal. Review the error and contact support if you need help. - Token request previously failed
This is to be expected for tenants that have not been onboarded. It is not necessary to contact support if you see this message.
Configuration Values
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
- tyGraph Administrators - administrators at your tenant who can manage tyGraph API
- License CDN URL - URL for the License CDN
- Application Insights API URL - URL for Application Insights
- Detected Location - location that the Microsoft location provider detects for you
Summary
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.