Troubleshooting a GeoStream Server

To gain the information required for efficient troubleshooting, we recommend that you use an HTTP inspector, and optionally enable GeoStream's diagnostic logging modes.

Using an HTTP Inspector

HTTP inspection tools let you view requests/responses sent to/from remote servers via HTTP and HTTPS. These are built into many modern browsers such as Google Chrome, and there are also third-party, browser agnostic solutions available, such as Telerik Fiddler. In our examples here, we will discuss Telerik Fiddler, but the same concepts and terminology should be equally applicable to other HTTP inspectors.

When the GeoStream server handles any request, it will send a response. There are three parts of this response that are of particular interest for diagnostic purposes:

• HTTP Status Code - a numeric code indicating the status of the response. Numbers in the 2XX range indicate success, whereas numbers in the 4XX-5XX range indicate an error. In Telerik Fiddler, this is shown in the Result column of the main view.
  
• Response Headers - the headers of the HTTP response returned by the GeoStream server. If a known error condition is encountered, the GeoStream server will append a custom Error header in the Miscellaneous section, containing a diagnostic error message. In Telerik Fiddler, this can be found in the Headers tab of the response pane, in the bottom right.
  
• HTML Error Pages - if the GeoStream server is unable to start succesfully due to problems in the IIS environment, then no custom Error headers will be present. In these circumstances, it is worth inspecting the HTML Error Page automatically generated by IIS, as this may contain useful diagnostic information. These will be displayed in the browser if the error occurs when loading the page itself; if the error occurs when requesting a resource for that page (such as a tile), then an HTTP Inspector can be used to view these. In Telerik Fiddler, this can be done via the WebView tab of the response pane, in the bottom right.
  

Tip
Telerik Fiddler supports saving the HTTP request/response history into a session archive file, via File -> Save -> All Sessions. These may be requested by GeoBase Support when assisting with complex GeoStream issues.

GeoStream Logging

The GeoStream server supports optional diagnostic logging, which can be enabled by adding keys to web.config as children of the <appSettings> element. Logs will be created within your GeoStream Data Directory, as defined by the GeoStreamDataFolder key in web.config, in a sub-folder named Logs. Each log will be namespaced and timestamped in UTC.

For the diagnosis of general GeoStream issues, enabling Exception logging is recommended. This will log any errors encountered by the GeoStream server when serving tiles or handling JSON requests.

<appSettings>
    ...
    <add key="ExceptionLogging" value="true" />
    ...
</appSettings>

This creates logs with the following format: geoStreamExceptions_UTCDATE_UTCTIME.log.

To look through the history of the GeoStream server utilization, enable live stats logging. This is a diagnostic tool that logs the contents of the stats-live page every 5 seconds. The stats-live page shows the currently running tasks and the overall GeoStream load. The logging information can be useful if the GeoStream server gets overloaded or if there are long running tasks.

<appSettings>
    ...
    <add key="LiveStatsLogging" value="true" />
    ...
</appSettings>

This creates logs with the following format: liveStats_UTCDATE_UTCTIME.log.

If you are specifically having problems with WMS feeds, including satellite imagery, then enabling WMS Logging is also recommended; this will log details of all WMS requests and any errors occurring upstream, on the WMS/Satellite Imagery server.

<appSettings>
    ...
    <add key="GeoStreamWMSLogging" value="true" />
    ...
</appSettings>

This creates logs with the following format: wms_UTCDATE_UTCTIME.log.

If you are specifically having problems with geocoding requests, including AutocompleteGeocoding and Location Searches, then enabling Geocoding Logging is also recommended; this will log details of all geocoding requests.

<appSettings>
    ...
    <add key="GeocodingLogging" value="true" />
    ...
</appSettings>

This creates logs with the following format: geocoding_UTCDATE_UTCTIME.log.

To diagnose tile loading errors, open an HTTP inspector and attempt to view http://localhost/GeoStream/tile.aspx?t=6,-2,300,2,5. This should display a map centered on the Pacific Northwest.

Note that this assumes you are working on the server itself; if not, replace localhost with your server's hostname. Alternatively, run your HTTP inspector on the client during a GeoStream session, and multiple requests to tile.aspx will be captured; this is useful for pinning down authentication based issues, which will not be captured by the test URL above.

Caution
In its default configuration, Telerik Fiddler will not display requests to localhost. Substitute either your server's hostname, or 127.0.0.1, the loopback IPv4 address.

The table below will assist in troubleshooting your map issues, based on the response received:

If regular map tiles are working correctly, but satellite imagery is failing to display, then there could be a number of different root causes; for example incorrect credentials, problems contacting the satellite imagery server, problems on the upstream server. To capture diagnostics, we recommend enabling WMS Logging (see above), running an HTTP Inspector then either viewing the sample script tutorial.satellite-imagery.aspx (JavaScript) or enabling Satellite Imagery in the Map Explorer sample application (.NET) via Map Style -> Satellite Imagery.

The table below outlines different Error headers that may be included in responses from tile.aspx when requesting satellite imagery. In all circumstances, the GeoStream server will return an HTTP 200 OK response, together with an uncacheable, short expiry basemap tile in place of the requested satellite tile.

Note

An additional cause for not displaying satellite image tiles could be the fact that you have not disabled the proxy server in the web.config file or specifically defined a proxy server. If this is the case, ASP.NET applications will use the proxy settings that are defined in Internet Explorer for all outgoing communication. To disable the proxy server, add <system.net> <defaultProxy enabled="false" /> </system.net> to web.config. To set the proxy server, set the <proxy> setting for <system.net> <defaultProxy/> </system.net> within web.config.

For any issue not covered above, contact GeoBase support, ideally providing WMS Logs and a HTTP inspector session log demonstrating the problem.

Other commonly occuring GeoStream issues which do not fit into the categories above:

If your problem is not listed here, contact GeoBase support for further assistance.