Troubleshooting and Logging

The InfoSystems webservices uses two distinct strategies/systems for reporting errors to the consuming client.

1. Status Codes in the style of a string typically called StatusCode and often an accompanied message called ErrorMessage

2. Custom faults in the style of SOAP Faults containing an error string and some detail information.

In general "older" service methods/endpoints adhere to the style of status codes while newer endpoints exclusively uses faults.

Status Codes

In general all methods in the InfoWebXMLWebService service will produce a status code, and optionally a descriptive error message. You can look at the status code to determine if something went wrong, and what.

To figure out what status codes can be produced from a given method have a look at its description, in the remarks there will be a list of available codes. For instance at the time of writing CalculatePrice can return the codes 00, 17, 226 and 99.

Status codes are considered global so 00 always means that we think everything went alright, while 99 is always an unexpected error (typically a programming error). Likewise with all the codes so if you see status code 17 from another method you can assume it means the product code was not found.

At the current time there is no list of all status codes.

Note
If it happens that you get a status code from a method, then either that status code is wrong, or we forgot to update the documentation (most likely the later). Please send an e-mail to support detailing the problem so we might fix it.

Important
Methods that were designed to use status codes might still inadvertently return a soap fault. So be sure to trap the generic/general soapfault to avoid displaying gibberish to the end users.

Faults

SOAP Faults are the default way to report errors when using SOAP, it is sort of like an exception for languages that has such a concept. In fact in .NET and Java languages (and possibly others) the faults are converted to exceptions by the various helper tools that are commonly used.

The advantage of faults is that they can be announced in the WSDL contract making error handling part of the contract. If your framework does not provide you with a way to see which faults can be generated from a method, you will need to look at the WSDL. Consider using a tool to document it or use something like SoapUI to navigate the WSDL.

Important
Methods might accedentially return a fault it was not intended to. This happens when a programming error occured or the fault was not specified in the contract. In either case let us know and we will fix it. In addition its important that you trap/catch the generic soap fault to avoid displaying gibberish to the end users.

If you are a .NET developer you can utilize most of what you already know about .NET and specifically WCF and ASMX for logging, tracing, debugging etc. For some of the services we even have assemblies you can use for most of the contracts and DTO's. Take a look at the assemblies Infosoft.Common.Contracts and Infosoft.Data.Entities for each.

All applications in the InfoSystems suite supports logging through the log4net logging framework. What that means is that all the applications can be configured to output log information in different ways. Most of the time it is not nescary to look at the log files, but while developing it might prove helpfull to have a look at the logs.

Note
By default, accessing the logs requires access to the web server - so if you are not the direct customer of Infosoft, then most likely you won't have access to the log files.

By default the application will look for the log4net configuration in a file named logging.config. Infosoft provides a default configuration where most things are turned off. The default is to log warnings, errors and fatal events into a file in an xml format. For every day a new file will be created with a new date. Also by default the SQL statement logging is explicitly turned off, so even though you enable full logging no SQL will be included unless you turn it on separately.

The configuration that Infosoft ships is just a basic configuration that we feel meets most requirements. If you want more advanced logging, for instance logging to a database, conditional setups, syslog support or something else. Please refer to the official log4net configuration at the apache log4net website: http://logging.apache.org/log4net/

Note
Consider using a log parser tool to view the default xml files. YALV on codeplex is a fine viewer, but many exists that can read the log4j xml format.

What is logged

In general unexpected errors should be logged, in addition some business errors will be logged as warnings. Expected errors should also be logged, but as these are often handled explicitly there is rarely a need to look at the errors. It is important to note that logging is something that is added by the developers in the appropriate places of the software. As such not everything you would expect to get in a log file is there, however we strive to log as much relevant information as possible.

For most web service methods enter/exist events are logged, meaning that whenever a method is called you will see something like.

Executing Request CalculatePrice IT, P7, 01, 1234, NOK, 10000
Finished Executing Request CalculatePrice

This basically just indicates a request was recieved with some parameters, and that the method completed succesfully. If the execution failed an exception/error will be logged. When debugging this is often what you are looking for.

Sometimes something unexpected occurs and the service will report a generic error like the following

Error: The server was unable to process the request due to an internal error. For more information about the error, either turn on IncludeExceptionDetailInFaults (either from ServiceBehaviorAttribute or from the configuration behavior) on the server in order to send the exception information back to the client, or turn on tracing as per the Microsoft .NET Framework 3.0 SDK documentation and inspect the server trace logs.System.Exception {System.ServiceModel.FaultException}

Some times it means we screwed up, other times it means you screwed up and we didnt anticipate it with proper error handling (so it always means we screwed up).

As the information says, you can turn on exception details to get some more information, in many cases this can help you figure out what is wrong, and if not it might help Infosoft. The various Microsoft sources are rather complicated to follow if you are not a .NET developer. So we have included most of the needed elements in the default configuration, but you still need to do a few things

Enabling exception details

<serviceBehaviors>
  <behavior>
    <!-- Enable wsdl help "get" pages for http and https -->
    <serviceMetadata httpGetEnabled="true" httpsGetEnabled="true" />
    <!-- By default exception are disabled, you can enable these for testing purposes -->
    <serviceDebug includeExceptionDetailInFaults="true" />
  </behavior>
</serviceBehaviors>

Security Note
You should ONLY enable remote exception details on test/dev environments.

When developing against SOAP services its important to know that all method requests are in fact an XML file. It is sometimes hard to figure out what was actually sent by the client and what was recieved by the server. To that end it is possible to turn on a tracing mechanism in .NET for the services to produce the entire SOAP XML request and response as it was recieved by the server.

Enable server-side SOAP tracing

Now in the log file you will get a lot of XML, look for everything within the <envelope> tags, this is the raw SOAP request or response.

For more information about WCF Tracing and Logging, have a look at the Configuring Message Logging MSDN section

Note
Note that not all services supports configuring the logging mechanism in the described manner, for instance InfoWebXMLWebService does not support this logging style. Have a look at Enabling Tracing in ASP.NET Web Services for info on how to do it with ASMX services.

Other Resources