Share via

EWS best practices - Tracing and logging

  • Article

A lot of programmers will write code for EWS thinking that the code and some knowledge of EWS is all they need to troubleshoot issues.  With even simple applications there is a need to being able to getting traces of traffic and often the ability for applications to log the traffic themselves.　 Without such logs of traffic it be difficult to troubleshoot even many of the common issues and often it makes the difference in being able to make a determination of the cause of an issue so that a remedy may be applied.　 So, be sure to implement tracing you can turn enable from the start of an application so that you at least have a built-in safety net.  Logs can make the differences between an issue being resolved in minutes rather than days and when an issue is critical it may make enough difference so that you can go home at the end of the day and not have to give up your evening or even weekend.

Many developers fall into the trap of thinking they don’t need a way to do protocol tracing from their application or protocol tracing at all and end up having to add it later under stressful situations. So always keep in mind that while your code may work for now that it might not work properly later and either you, your support staff or customers may end up needing it badly in order to troubleshoot issues.

When the EWS API is used it’s not very hard to add basic logging since a trace listener is built into its classes. Below is an article which covers its usage:

How to: Trace requests and responses to troubleshoot EWS Managed API applications
https://msdn.microsoft.com/en-us/library/office/dd633676(v=exchg.80).aspx

You can also get logs of traffic when using Visual Studio generated proxy classes:

Debugging Proxies in Exchange 2010
https://msdn.microsoft.com/en-us/library/office/bb204041(v=exchg.140).aspx

If you are in the situation where you need to get a trace and modify your source code, deploy a new build and cannot… well, there is still hope.  .NET APIs and APIs built on them can leverage .NET logging of traffic.  This can be done in code and also by modifying the config file for an application.  Each .NET application can have a config file and often does.  You can modify the application’s config file and add settings to have the traffic sent to a file.  So, if you’re using the EWS Managed API (which is built on .NET), Visual Studio generated proxy classes or raw SOAP posts for EWS, you can log the traffic to a file. Also, you can redirect traffic from .NET calls to a logging proxy (like Fiddler) by also modifying the application’s configuration file.

Getting traces for .NET apps when you cannot modify the application and don't want to use more than one machine.
https://blogs.msdn.com/b/webdav_101/archive/2014/08/07/getting-traces-for-net-apps-when-you-cannot-modify-the-application-and-don-t-want-to-use-more-than-one-machine.aspx

The following really should be logged by tracing code:

  • All of the headers of the request (with the exception of things like passwords, etc).
  • The full body of the request.
  • All of the response headers.
  • The full response body.
  • The response code.
  • The date and time the call was made and the date and time the response came back.  The client time zone should also be logged.  This information is helpful if not totally necessary for matching to logs on the server.
  • Any error information.  Some APIs have an error collection tied to the response - be sure to extract and log this data since it may point directly to the cause of the issue.

One tool which I find extremely helpful is Fiddler.  Fiddler is a logging proxy which can SSL decode traffic on the fly.  One problem people run into with trying to get a log of EWS traffic is that it’s very likely SSL encoded.  Application based logging can SSL decode the traffic, however without having a certificate you’re not going to get to the decoded EWS traffic. If you have an on premise server then you may be able to get the server certificate and use it.  However, if you go against Exchange on-line then that is not going to be a possibility – even Microsoft support engineers won’t be able to get it for decoding traces.  The way that Fiddler helps in this situation is that it can proxy the request, decode the traffic and log that decoded traffic.

Fiddler
https://www.telerik.com/fiddler

There are times you will need to fallback to using Netmon.　 While Fiddler is very helpful for most EWS traffic issue there are times you may need to be able to see the traffic in a more pure form.　 As an example, Fiddler pulls traffic frames together to provide a more cohesive view of traffic.　 That's a great feature eh?　 But what if you need to see each frame separately?  So, be sure to read-up on Netmon.  Yes, you won't be able to see the bodies of SSL traffic decoded without a certificate, however it won't matter in many cases when you may be trying to diagnose traffic and routing issues.

Network Monitor 4.3
https://www.microsoft.com/en-us/download/details.aspx?id=4865

When it comes to thinking in terms of logging EWS traffic for troubleshooting issues you should consider that you may need to get traces of traffic at multiple points.　 There may be times that being able to get a trace at any given point may be critical in trying to　troubleshoot issues.　 Sometimes between the client application and the Exchange Web Service there may be other applications and hardware which can mangle, redirect or block traffic.　

When it comes to thinking in terms of logging EWS traffic for troubleshooting issues you should consider that you may need to get traces of traffic at multiple points.　 There may be times that being able to get a trace at any given point may be critical in trying to　troubleshoot issues.　 Sometimes between the client application and the Exchange Web Service there may be other applications and hardware which can mangle, redirect or block traffic.　 Fiddler and Netmon and be helpful anywhere along the path.　 However, Fiddler may struggle some with a high rate of traffic and even Netmon may - so be sure to be able to filter when using those tools for tracing.

.           
When using the EWS Managed API with Exchange Online there are two settings which you should set or be able to enable setting on the service object.  These settings will cause headers to the Exchange serves which tell them to send back additional information.

ReturnClientRequestId   - This will give us more data back about the servers used in the response headers.  The information back will help identify the mailbox server and CAS server used during the call.  This information will be critical in the case the Exchange Online servers and their logs need to be examined by Microsoft datacenter engineers or by the Exchange developers since it will tell them which servers to look at..

SendClientLatencies  - This will provide latency info which is used by Microsoft to improve EWS and Exchange Online.

If you have access to Exchange server your sending EWS traffic to then you can use traffic logged on the server.　 See the content below on how to use Log Parser and Log Parser Studio with IIS logs on an Exchange server for troubleshooting EWS issue.   Note that you won't be able to get at Exchange Online server logs.　

Troubleshooting EWS requests using IIS logs with Logparser
https://blogs.technet.com/b/caseys/archive/2012/01/23/troubleshooting-ews-requests-using-iis-logs-with-logparser.aspx

Introducing: Log Parser Studio
https://blogs.technet.com/b/exchange/archive/2012/03/07/introducing-log-parser-studio.aspx

Log Parser 2.2
https://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=24659

Also see:

EWS Best Practices
https://blogs.msdn.com/b/webdav_101/archive/2015/05/03/ews-best-practices.aspx

How to: Trace requests and responses to troubleshoot EWS Managed API applications
https://msdn.microsoft.com/en-us/library/office/dd633676(v=exchg.80).aspx

Tracing and Instrumenting Applications
https://msdn.microsoft.com/en-us/library/zs6s4h68(v=vs.110).aspx

How to: Add Trace Statements to Application Code
https://msdn.microsoft.com/en-us/library/zd83saa2(v=vs.110).aspx

Getting traces for .NET apps when you cannot modify the application and don't want to use more than one machine.
https://blogs.msdn.com/b/webdav_101/archive/2014/08/07/getting-traces-for-net-apps-when-you-cannot-modify-the-application-and-don-t-want-to-use-more-than-one-machine.aspx

Trace Listeners
https://msdn.microsoft.com/en-us/library/4y5y10s7(v=vs.110).aspx

How to: Use TraceSource and Filters with Trace Listeners
https://msdn.microsoft.com/en-us/library/ms228993(v=vs.110).aspx

How to: Enable Tracing for an ASP.NET Application
https://msdn.microsoft.com/en-us/library/0x5wc973.aspx

Cloud Diagnostics - Take Control of Logging and Tracing in Windows Azure
https://msdn.microsoft.com/en-us/magazine/ff714589.aspx

Troubleshoot a web app in Azure App Service using Visual Studio https://azure.microsoft.com/en-us/documentation/articles/web-sites-dotnet-troubleshoot-visual-studio/

Enable diagnostics logging for web apps in Azure App Service https://msdn.microsoft.com/en-us/library/zs6s4h68(v=vs.110).aspx/

Application Insights API for custom events and metrics https://azure.microsoft.com/en-in/documentation/articles/app-insights-api-custom-events-metrics/