If you are new to troubleshooting Geocortex Essentials issues or do not troubleshoot issues often, it can be confusing where to start looking and what to look for. This guide contains some information and tips on how to how to gather relevant information to either resolve the issue or send to VertiGIS Support for a resolution.
Troubleshooting Geocortex Essentials and Viewer Loading Issues
When a Geocortex application encounters a problem a log entry is typically written. These log entries can be used to determine the root cause of the problem. Logs have different severity levels, from Debug to Info to Warn to Error to Fatal. The level of logging that Essentials performs is based on a setting in Essentials Manager. The setting for both System and Access logs can be set to the one of the severity levels listed above or set to “off”. The setting is accessed by clicking the “Application Settings” link in the top right-hand part of Essentials manager. If you are seeing no logs, not enough logs or too many log entries, this setting should be checked.
The log file locations and what they contain
C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\REST\App_Data\Logs\
REST logs come in two types, SYSTEM and ACCESS. The SYSTEM logs are what is usually referenced for Essentials and viewer issues. When a request to a REST endpoint is made and an error occurs a SYSTEM log is recorded. The logs may directly indicate what the issue is or they may need to be sent to a support analyst for further investigation.
The ACCESS logs are created by the underlying library used for logging and contain no information for the REST application. To determine who has accessed the REST application, refer to your web server access logs.
C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Manager\App_Data\Logs
As with REST logs above, Essentials Manager creates a SYSTEM log containing information specific to operations involving Essentials Manager. If an issue arises while using Essentials Manager, the Manager log is a good location to check for errors.
Geocortex Core logs
C:\Program Files\Latitude Geographics\Geocortex Core\Data\Logs
Geocortex Core contains shared code common to Geocortex applications used for functions like searching, document storage and clustering.
Core logs will show issues with Geocortex Core start up (BootStrapper.console), clustering problems (Documentstore.log or the clusterName.log) or with Core specific functions like Instant Search scanning and indexing (InstantSearch.Scanner or InstantSearch.Indexer). Sort the folder by modified date and check all recently changed log files.
Core Log Viewer
Geocortex Essentials ships with a log viewer. The viewer will combine entries from all relevant logs in chronological order allowing you to see obvious errors and the order in which they occur. The log viewer can be found here –
C:\Program Files\Latitude Geographics\Geocortex Core\Diagnostics\LogFileViewer\ Geocortex.Platform.LogFileViewer
On the HTML5 viewer you can view the viewer log by clicking and long holding in the banner area. This will display the viewer log which will show the version number of the viewer being used as well as INFO entries for successful modules being loaded. If you are launching the viewer on a mobile device with the GMAF app, the version of GMAF will also be available. If an issue is encountered related to the viewer there should be a WARNING or ERROR message with a summary of the issue. As with the REST logs, the logs may directly indicate what the issue is or they may need to be sent to Geocortex support for further investigation.
Browser Developer Console
Most browsers have built in developer tools, typically displayed using the F12 function key. The "Console" section of the developer tools will show errors that the browser has initiated. If an error is not found in Fiddler, it may be due to the browser stopping a request before it is sent. Mixed content is an example of a log entry that may appear here. A browser will typically not allow an http request to be made if the browser is being run via an https connection. The "Network" section is another useful section, this section will show a table of requests being made the responses received, much like Fiddler does. If you were troubleshooting a mixed content issue, the Network section would show which requests were using http and which ones were using https. The "Elements" or "DOM Explorer" section will show the html code used to display the page and the CSS code used to style the page. This section is useful for making and previewing CSS changes to alter the look and feel of a page. Making CSS changes is not recommended as it may impact other areas of the viewer that were not intended to be changed, but occasionally CSS changes are the only option.
Windows Event Viewer logs
These logs display info for an application when it crashes and is unable to record its own logs. This is not a common occurrence but the event viewer logs may need to be checked if you think an application crash is involved. Under the “Windows Logs” folder check the Application and System sections. A 500 series error for example is a server based error, there should also be a Windows Event Log associated with the error. The two common sections to look in are System and Application.
For every request to a web server, a log entry is created. The entry will contain information on the request (useful for identifying the request you are interested in) and the response that was made by the web server, useful for troubleshooting the issue. HTTP Responses are standard and follow a convention. Refer to this link for further details. The number after the 3 digit code may hold an important clue, for instance a 404 error appears to be a NOT FOUND issue but a 404 15 indicates that the request made was too long and could not be processed. The IIS Log module is optional, if you do not see the logs folder, or it is empty, you may need to add the log role via the Server Manager (Web Server (IIS) > Web Server > Common HTTP Features > Health and Diagnostics > HTTP Logging) .
Determining where the trouble is
A Geocortex Essentials system is comprised of many components; it is important to determine which component is causing the issue in order to resolve it. An issue may occur in:
- Geocortex Core
- Geocortex Essentials Manager
- A viewer
- The server or the operating system on the server
- A network component like a reverse proxy or web adapter
- A network policy, setting or firewall restricting a request
- A issue with the service (map, geometry, geoprocessing etc) the viewer is consuming
Some initial fundamental checks can be performed to pinpoint the cause of the issue.
- Symptoms of a completely dead system
- Essentials Manager and the viewers will not load
- The REST endpoint will not load in a browser http://MyServer/Geocortex/Essentials/Rest/sites (make sure “/sites” is added to the end, using just /Rest is not a valid rest endpoint)
- “Geocortex Core:*” processes may be missing from the task manager - process tab. A typical Essentials system will have 14 processes running plus 3 additional processes if a Geocortex Analytics Agent is installed.
- Geocortex Core service may be stopped in the task manager - services tab
Areas to check on an apparent dead system:
In a browser, can you reach http://MyServer (or https://MyServer)
Yes, I see an IIS logo
This shows the web server appears to be functioning and able to serve up web pages. If you've replaced the default IIS web page, you will see it here instead.
This indicates an issue with IIS on the server. You can also try creating a simple test.html file to see if you can view it. Typically someone from IT will need to get involved as the issue appears to be with the server itself and not Geocortex
In a browser, can you reach http://MyServer/Html5Viewer/Index.html
Yes, I see the World Cities default map
This shows the viewer is able to display a generic viewer and indicates the issue is most likely with the site being loaded or an issue with the full URL being used
This indicates an issue with the viewer itself and rules out a site specific issue. Use Fiddler to get a trace and see if an error can be found or look in the browser developer tools (F12) for errors in the console section
Sudden viewer loading issues are typically related to a code change in the site.xml file, a code change in the Desktop.json.js file or a networking issue. The Desktop.json.js file can quickly be ruled out by swapping it with a known good file. The LA County sample site would an example of a known good file (C:\Program Files (x86)\Latitude Geographics\Geocortex Essentials\Default\REST Elements\Sample Sites\LA_County\Viewers\LA_County_HTML\VirtualDirectory\Resources\Config\Default). Be sure to rename your current file so you do not lose it.
If a change was made recently to the site and saved, the site.xml file would most likely have been updated, this can be verified by the modified date. If a backup copy is available, the site.xml file as the source of the issue can be checked by substituting the backup file into the site folder. If a backup copy is not available, knowing the steps done to trigger the issue is important. Note what changes were done and submit a new support case, including the site.xml file, if possible. Review the viewer log and REST log for errors.
Fiddler is a powerful tool used to see requests being made from the browser (viewer) or a server (via a proxy setting). Fiddler has many settings but you can get away with only using a few:
Rules > Performance > Disable Caching – to ensure responses are not cached and returned with each request. Cached responses will have a response code of 304 and will contain no data returned by the server
Tools > Telerik Fiddler Options > HTTPS Tab > Decrypt HTTPS traffic – to be able to view HTTPS based traffic, only applicable with a viewer that uses https or https services
File > Capture Traffic (or F12) – to start and stop capturing of traffic
Ctrl X – to clear the list of requests
Responses are typically in JSON format but other formats are possible. Start by selecting “Raw” to see if you recognize the format and then select the actual format once recognized.
Examples of formats you may see are:
https://en.wikipedia.org/wiki/HTML (webView in Fiddler)
Requests and responses may be encoded or may be difficult to read due to their format. The following sites can be used to make them more easily read by the human eye –
JSON Pretty Print
Base 64 Decoding
There are at least two Knowledgebase articles on the Support Center that detail how to use Fiddler. If you want to check a viewer loading issue or a viewer request, like a measurement request to a geometry service, you can refer to this article –
Fiddler from browser to web server
For other issues you may need to see what Essentials is requesting. For instance, when a workflow is running, you will only see activity from client to server using the method above. In order to see what Essentials is doing when executing the workflow, request-wise, you will need to setup Essentials to use Fiddler as a proxy. This is done by changing the Essentials REST web.config file which then will forward any requests it makes via Fiddler, exposing them in Fiddler and making them visible to us. To see the requests from Essentials to external services refer to this knowledgebase article –
Fiddler as a proxy between Essentials and another server
There are several Fiddler tutorials available, an example of one is here.
If you do not want to use the full Fiddler tool there is a lightweight option available for the sole purpose of capturing and saving requests and responses. The lightweight version is called FiddlerCap and it is available here. The same page includes instructions on how to use FiddlerCap.
Caching is meant to speed up the web experience but it can also cause issues when troubleshooting. Browsers have cache and Essentials also has a site cache. If you make a change and then test the change and it appears to have no impact, you should make sure you are not dealing with a cached result. A site can be completely broke but still load in Essentials Manager due to the browser not making new requests and using cached responses. In Essentials Manager, on the Sites List page, the icon for each site has a "Reload" icon. This icon clears the site cache in Essentials Manager for that particular site. In the browser, try using an InCognito or InPrivate window to avoid caching. Using Fiddler use the Rules/Performance/Disable Caching option.
In summary, troubleshooting a web server / web application can be a complex operation and only gets easier with experience. Having a strong understanding of the various log files purpose and location is a requirement. Knowing how to use a web troubleshooting tool like Fiddler or the browser developer tools is also very helpful.