Title: Tracking Exceptions in Web Services with GUIDs

This article demonstrates a technique for tracking exceptions across process boundaries in distributed systems using Globally Unique Identifiers (GUIDs); data from log files, bug reports, and on-screen error messages can then be correlated, allowing specific errors to be pinpointed.

Particular attention is paid to XML Web Services, with additional reference to DCOM, CORBA, Java/RMI and .Net Remoting..

The examples are given in C#, but the technique can be applied easily to Java and other languages.

When dealing with modern distributed applications, it is often very useful to track an exception as it crosses process and machine boundaries. A comprehensive picture of the "distributed error" can then be constructed from log files of the different applications and components affected.

Languages such as C# and Java have an inbuilt mechanism to provide detailed error information - the Exception Stack Trace - which helps greatly to identify the source of runtime application errors. However, this information in itself does not always provide the full picture of an error condition.

The approach outlined here uses GUIDs (see Sidebar: GUIDs) effectively to "tag" exceptions before they leave one part of an application and appear in another. This allows exceptions to be tracked irrespective of whether the application is stand-alone or distributed, and irrespective of the transport, protocol or component architecture used.

XML Web Services is the name given to the latest class of middleware technologies designed to provide cross-platform Remote Procedure Calls (RPC). Previous technologies such as DCOM, CORBA and Java/RMI all have strengths, but often suffer from implementation difficulties, and none is really both platform- and language-independent [_10], [_11]. XML Web Services are described concisely in [_16] as follows:

The increasing success of XML Web Services, and SOAP [_9] in particular, as the "glue" for cross-platform RPC can be put down to several factors, including:

All these properties make XML Web Services very attractive for building scalable, flexible distributed applications. For a more comprehensive introduction to XML Web Services, see [_8].

The Simple Object Access Protocol (SOAP) [_9] is probably the most common dialect used by XML Web Services. The W3 introduction [_17] to SOAP states: SOAP is fundamentally a stateless, one-way message exchange paradigm, but applications can create more complex interaction patterns (e.g., request/response, request/multiple responses, etc.) by combining such one-way exchanges with features provided by an underlying protocol and/or application-specific information. Although SOAP does not specify a transport protocol, HTTP is normally used. With the resultant "SOAP-HTTP Binding", XML Web Services using SOAP and HTTP rely on message exchange using a combination of an HTTP Header and SOAP (XML) payload.

A SOAP message to retrieve (say) the author and title of a book might look something like this:

POST /cgi-bin/book-info.cgi HTTP/1.1
MethodName: GetBookDetails
MessageType: Call
Content-Type: text/xml-SOAP

<GetBookDetails>
  <ISBN>0201615622</ISBN>
</GetBookDetails>

Notice the standard HTTP POST request (first five lines), and that the SOAP payload (the GetBookDetails element) is simply XML.

The response from the Web Service might look like this:

200 OK
Content-Type: text/xml
Content-Length: 115

<GetBookDetailsResponse>
  <author>
    Herb Sutter
  </author>
  <title>
    Exceptional C++
  </title>
</GetBookDetailsResponse>

The XML payload contains a root element GetBookDetailsResponse that is the response to the original GetBookDetails request. Real-world SOAP messages would be somewhat more complex, but the principle above remains. For a much more comprehensive overview of SOAP, see [_10].

SOAP deals with errors using a Fault response element. Any errors encountered by the Web Service, either in the request itself, or during the processing of the request, are detailed in the Fault element. For example, if the GetBookDetails request above failed due to an unknown ISBN, the XML payload of the response might look something like this:

<GetBookDetailsResponse>
  <fault>
    <faultcode>700</faultcode>
    <faultstring>Processing Error</faultstring>
  <runcode>1</runcode>
    <details>
      <Message>
        ISBN Not Recognised!
      </Message>
    </details>
  </fault>
</GetBookDetailsResponse>

The /fault/details node contains a Message element, with an explanation of the error. (Note: in practice, XML Namespaces would be used for both the request and the response XML: these have been omitted for clarity.)

We will return to the SOAP Fault shortly.

The Microsoft .Net Framework simplifies many of the implementation details of SOAP web services by classes in the System.Web.Services namespace [_20], in particular, the WebService class, from which - by default - all other SOAP Web Services in .Net are derived.^[1]

One of the most useful aspects of the Framework is that a SOAP Fault response is converted automatically to a System.Web.Services.Protocols.SoapException [_18], which is thrown in the context of the calling client. Details of the error contained in the SOAP Fault element are made available as properties of the SoapException instance.^[2]

This conversion also works in the opposite direction: a SoapException escaping from the Web Service is converted automatically into a SOAP Fault response. In fact, the .Net Framework ensures that only exceptions of type SoapException escape from a Web Service call: if an uncaught exception raised within a Web Service method is not a SoapException, the Framework throws a new SoapException, storing the uncaught exception as its InnerException. Details of the original exception are extracted into the SOAP Fault/details element.

Figure 4. Mapping SoapExceptions to SOAP Faults

Figure 4 shows how information about an error in the Web Service method is transmitted back to the calling client. Thus, if the Web Service were to create a unique identifier for the error, and pass that identifier back to the client, we would be able to track that specific error as it travels across machine/process boundaries. Assuming that the error is logged in both places, we would have a way to link together error information from one application component with that from another.

Figure 5 shows a C# class definition for a simple base class to help with tracking exceptions:

using System;

public class TrackedException : Exception
{
  #region .ctor signatures in System.Exception
  public TrackedException() : this(Guid.NewGuid())
  {}

  public TrackedException(string message) : 
     this(message, Guid.NewGuid())
  {}
  // etc...
  #endregion

  #region .ctors providing tracking ability
  using GUIDs
  protected TrackedException(Guid errorID) :
     base()
  {
    this.errorID = errorID;
  }

  protected TrackedException(string message,
     Guid errorID) : base(message)
  {
    this.errorID = errorID;
  }
  // etc...
  #endregion

  #region Tracking
  private Guid errorID;
  /// <summary>
  /// Uniquely identifies this exception
  /// </summary>
  public Guid ErrorID
  {
    get { return errorID; }
  }
  #endregion
}

The TrackedException class in Figure 5 automatically creates a new GUID in its constructors. Derived classes therefore do not need to concern themselves with GUID creation: in fact, they cannot, as the constructors relating to GUIDs are protected. Other useful base class constructors could be defined (e.g. matching the signatures of System.Exception), also priming the ErrorID property.

Wherever a TrackedException is thrown in code, we know that it will have a GUID-based ErrorID property, which we can include in log file data.

Crucially, however, in the context of Web Services, we can also include this GUID in the SOAP Fault response, by throwing explicitly a SoapException from within a Web Service method if an exception is thrown during processing:

[WebMethod] //Attribute needed for Web Service
           //'plumbing'
public string GetBananaPrice(string cityName)
{
  try
  {
    // some processing
  }
  catch (TrackedException te)
  {
    string message = te.GetType().Name + " " +
       te.Message;
    // N.B. Constructor parameters simplified
    // here
    throw new SoapException(
      message, 
      ExceptionHelper.WrapDetails(te.ErrorID),
      te);
  }
}

The call to the hypothetical ExceptionHelper.WrapDetails() method returns a System.Xml.XmlNode object that will be inserted into the SOAP Fault response XML payload.

The client calling the Web Service in Figure 6 would use code like this:

// Create local proxy for Web Service
// Connection to remote machine is handled 
// automatically
PricesWebService ws = new PricesWebService();
try
{
  string bananaPrice = 
     ws.GetBananaPrice("Havana");
}
catch (SoapException se)
{
  // Extract the GUID stored by the Web
  // Service from the XML
  string errorGUID = se.Details.InnerText; 
  string message = se.Message;
  // Log the error here at the client...
  Console.Out.WriteLine("Error when calling 
     GetBananaPrice(): " + message + " GUID: "
     + errorGUID);
  // TODO: 
  // Present the GUID to the user 
  // Notify admin using GUID
}

The Details property of the SoapException at the client contains the XML from the XmlNode that was inserted in the catch handler of the Web Service method: the GUID of the original exception (see Figure 6). Logging this at the client will allow us to tie together the error logs from the two applications; showing the GUID to the user (see Figure 8) would allow her to copy/paste the GUID into a bug report (for example), further correlating the error information.

The same GUID appearing in different log files will refer to the same exception instance; due to the nature of GUIDs (see Sidebar: GUIDs) we can assume that a GUID will never be duplicated.

There is an advantage in presenting only a GUID rather than detailed error information to the user: it may not always be appropriate to divulge the details of an error (for security reasons, for example). The GUID acts as an opaque handle to the already-logged error; a bug report containing just the GUID should be enough to put that report in context.

It is fairly easy to extend the GUID-based error tracking to certain other frameworks and technologies. For Java/RMI (and its .Net analogue, .Net Remoting), it is basically enough to make the TrackedException class available to each side of the Remoting channel.^[3] The ErrorID property of the exception instance will be serialized along with the rest of the object, and therefore be available to the calling client. [Note that a UUID class was introduced only in Java 2 SE 1.5, so earlier versions of Java will have to rely on other UUID implementations - see Sidebar: GUID Implementations, [c]]

Figure 8. Presenting the error GUID to the user

CORBA and DCOM differ substantially in their support for exceptions. DCOM does not transmit exception details from server to client, relying instead on (much less useful) "HRESULT" return codes [_5] [_22]. There is therefore no simple way to extend the GUID-based exception tracking to DCOM.^[4]

Unlike DCOM, CORBA does transmit exceptions across the communication channel. If we make TrackedException a CORBA::UserException, we can define a public property errorID, which will contain the string representation of the GUID:

// CORBA IDL
#pragma prefix "example.com"
module TrackedExceptionExample
{
  interface FruitPrices
  {
    exception TrackedException
    {
      string errorID;
    };

    string get_banana_price(
       in string cityName)
            raises (TrackedException);
    };
};

Some CORBA implementations already provide for a way to associate extra information with the exception - see [_23].

However, for situations that do not provide this ability to 'hook' the exception GUID (for example, in 'interop' scenarios [_21] ^[5]), it may be possible to append the GUID to the error message. C# code for a modified version of the TrackedException class to append the GUID to the error message would look like this:

using System;
public class TrackedException : Exception
{
  #region .ctor signatures in System.Exception
  public TrackedException() : 
     this(Guid.NewGuid())
  {}
  public TrackedException(string message) :
     this(message, Guid.NewGuid())
  {}
  // etc...
  #endregion
  #region .ctors providing tracking ability
     using GUIDs
  protected TrackedException(Guid errorID) :
     base(String.Format(FormatString,
          "TrackedException", errorID))
  {
    this.errorID = errorID;
  }
  protected TrackedException(string message,
     Guid errorID) : base(String.Format
     (FormatString, message, errorID))
  {
    this.errorID = errorID;
  }

  // etc...
  #endregion
  #region Tracking
  public static readonly string FormatString = 
     "{0} - ErrorID: {1}";
  private Guid errorID;
  // <summary>
  // Uniquely identifies this exception
  // </summary>
  public Guid ErrorID
  {
    get { return errorID; }
  }
  #endregion
}

The constructors ensure that a GUID is associated with the exception (as in Figure 5), but also automatically store the string version of the GUID in the Message property of the exception, by modifying the data passed to the base class constructor.

This approach sacrifices encapsulation for the ability to track exceptions across process and machine boundaries. Logging the received error message would still allow the correlation of error information from the various parts of the distributed system, because the original exception GUID is stored in the error message.

The System.Exception class in C# 2.0 (currently in Beta, and due for release some time in 2005) has a new member: Data of type IDictionary. This allows the association of arbitrary named data items with a given exception. The ErrorID property of TrackedException could be re-implemented to store the GUID in the Exception.Data dictionary, because this would remove the need for special treatment:

public class TrackedException : Exception
{
  // Constructors go here...
  // ...
  // for example:
  public TrackedException (Guid errorID) :
     base ()
  {
    this.Data["GUID"] = errorID;
  }
  public Guid ErrorID
  {
    get
    {
      return this.Data["GUID"] as Guid;
    }
  }
}

The reason for this becomes clear when logging exceptions, we would just log all information in the Data dictionary (logging the Name, and calling .ToString() on the Value for each entry):

try
{
  // some processing...
}
catch (Exception ex)
{
  // In practice, this code would go in a 
  // generic logging method somewhere...
  Exception innerException = ex;
  while (null!=innerException)
  {
    // Log the basic exception details here
    // e.g. StackTrace, Message, etc....
    // Log the Data dictionary entries
    string[] names = ex.Data.Names;
    foreach (string name in names)
    {
      Log.WriteLine(name + " = " + 
                    ex.Data[name]);
    }
    innerException = innerException.InnerException;
  }
}

Arguably, the need for a separate TrackedException class is removed with C# 2.0, because any and every exception can have a tracking GUID associated with it, stored as a named entry in the IDictionary Data member, rather than needing a separate property ErrorID.

The concept of exception tracking presented in this article is similar to the idea presented in [_6] and [_7], where contextual information associated with an exception is maintained for later analysis. This article extends the idea across process, machine and protocol boundaries, however, relying on offline log file analysis to restore the contextual information.

The overhead associated with generating and transmitting a GUID may be unacceptable in some cases. However, in most situations, the benefits gained from being able to track exceptions using a string of 30-something characters will probably outweigh the slight performance hit.

An example project demonstrating the ideas in this article is available from www.accu.org.

This article demonstrated a simple scheme to track exceptions across Web Services and other distributed systems using GUIDs.

The benefits of using this scheme become apparent when the need arises to correlate information from multiple error logs and bug reports: the details of specific exceptions can be reconstructed at a later stage, and problems diagnosed more thoroughly.

A prototype of this scheme has been in operation for several months for a real-world project using SOAP Web Services (http://www.lamip.org/) and proven to be very useful indeed.

Thanks to the Editor, Paul Johnson, for requesting this article.

Thanks also to Kev Watkins, Liz Chapman, Mike Graves, Jason Neylon, Besim Atalay, Gerald Krafft, Denny De La Haye, Esme Tearle, and Rebecca Dyer for help and suggestions.