Instrumenting client requests for EWS and REST in Exchange

Learn about the HTTP headers in EWS and REST requests and responses that can help you monitor and troubleshoot your Exchange application.

Last modified: April 24, 2014

Applies to: EWS Managed API | Exchange Online | Exchange Server 2013 | Office 365

In this article
Add instrumentation to requests
Log information from responses
Report EWS latency to Microsoft
Next steps
Additional resources

Has this ever happened to you? A user of your application reports an unexpected error. You want to investigate, but you can’t reproduce it. The error has disappeared for the user, and you’re left with very little actionable data. Frustrating, isn’t it? Let’s look at how you can proactively prepare for this scenario and hopefully avoid frustration in the future.

We recommend that you add additional HTTP headers to your requests to facilitate troubleshooting. You should keep a record of this information somewhere (for example, in a log file) so that you can retrieve it later if you need to. This is helpful when examining network traffic, and is also helpful if you contact Microsoft support for assistance.

Table 1.  Request headers for troubleshooting

HTTP header (EWS)

EWS Managed API equivalent

Notes

User-Agent

ExchangeService.UserAgent

Set this to a unique value that identifies your application. Use the same value for all requests that your application sends.

client-request-id

ExchangeService.ClientRequestId

Set this to a different unique value for every request your application sends. We recommend that you use a GUID. This ensures that every request you send has a unique identifier.

return-client-request-id

ExchangeService.ReturnClientRequestId

Set this to true to signal to the Exchange server that it should return the value of your client-request-id in the corresponding response. You can use this to correlate requests and responses in network traces or EWS Managed API traces.

X-ClientStatistics

ExchangeService.SendClientLatencies

Used to report EWS latencies to Microsoft if your application is accessing Exchange Online or Exchange Online as part of Office 365.

Just as your client can add additional instrumentation to the requests it sends, Exchange adds additional instrumentation to the responses in the form of HTTP headers. Your client should capture this information to go along with the request instrumentation information.

Note Note

If you are using the EWS Managed API, there is no direct equivalent for the HTTP headers. However, all HTTP response headers can be accessed via the ExchangeService.HttpResponseHeaders property.

Table 2.  HTTP response headers

HTTP header

Description

request-id

A server-generated ID for the request that corresponds to this response.

client-request-id

The value of the client-request-id header in the request. This header is only present if the request contains the return-client-request-id header with a value of true.

X-FEServer

The FQDN of the Client Access server that processed the request.

X-TargetBEServer

The FQDN of the mailbox server that processed the request.

X-DiagInfo

Additional diagnostic information, depending on the request.

x-ms-diagnostics

This header is only applicable if OAuth authentication is used in the request. It contains an explicit error code that specifies why an OAuth authentication failed. It takes the following format.

errorId;reason=”reason”error_type=”error type”

The reason field is a human-readable description of the error. The errorId field is an integer, and the error_type field is the string representation of that integer, as follows:

  • 2000000: invalid_signature

  • 2000001: invalid_token

  • 2000002: token_expired

  • 2000003: invalid_resource

  • 2000004: invalid_tenant

  • 2000005: invalid_user

  • 2000006: invalid_client

  • 2000007: internal_error

  • 2000008: invalid_grant

If your application uses the EWS Managed API or EWS to connect to Exchange Online, you can report latency in EWS requests directly to Microsoft. The information is passed via the X-ClientStatistics request header. If you are using the EWS Managed API, all you have to do is set the ExchangeService.SendClientLatencies property to true. If you are using EWS, you’ll need to measure the time between issuing a request and receiving a response, then add the X-ClientStatistics header to the next EWS request your application sends, using the following format.

X-ClientStatistics: MessageId=<value of request-id header>,ResponseTime=<time in milliseconds>,SoapAction=<EWS operation>

We maintain reports for these latencies and use them to continuously improve EWS services in Exchange Online.

After you’ve added client instrumentation to your application, you’re better prepared if something goes wrong. If that happens, you can use your instrumentation data to troubleshoot your application.

Show:
© 2014 Microsoft