Mark's Sitecore Blog

Santa’s little xDB Helper

Sorry for the xmas pun but hey, it’s December.

Back to topic. Debugging xDB issues on a remote environment can be very difficult. Is the MongoDB connection OK? Is tracking configured correctly? Are contacts being created and identified? Is my data pushed to the correct places, when my session ends? Why is GeoIP detection not working?

Luckily, there is a nice little helper page named xdbHelper  initially created by Ivan Buzyka. I have added some extensions to it to make it even more useful. Here is what i looks like *ugly UI alert!*


Flush your session

The most important feature of xdbHelper is to allow you to terminate your session immediately. This will make Sitecore store your temporary session data in the analytics database and also helps to check whether data is being aggregated in the reporting db tables without wasting time waiting for sessions to expire.

After clicking the “flush session” button, check if the number of interactions in MongoDB has gone up. If not, there is an issue with session state configuration or processing data. Check the Sitecore log for details.

Check if Analytics Tracking is running

The page will display a warning at the top if Tracker is not active. If not this can be due to several issues

  • Incorrect configuration
  • No connection to MongoDB
  • Invalid license

Check the Sitecore log for more detailed information. Usually it states right at the start why Tracker was not able to be initialized.

Check MongoDB Connection

Often it is not immediately evident through logs that there is no connection to MongoDB. xDB Helper will show you if there is no connection and why if failed.

Check GeoIP resolving

Ever so often I’ve run in to issues with GeoIP resolving in production. Mostly related to Loadbalancers not forwarding client IP addresses or special formatting of forwarding headers. xdbHelper will display the received client IP and also the X-Forwarded-For header if present.

If no Country is displayed, geo IP lookup is either disabled or not configured correctly. If your loadbalancer forwards the client IP through a header (i.E. X-Forwarded-For), make sure you have the appropriate header set in

<setting name="Analytics.ForwardedRequestHttpHeader" value="" />

Test identifying contacts

In case you identify contacts on your site (i.E. through form submissions), you can use this page to verify that identification works correctly. It is also possible to manually set identification and name / surname to help searching for your contact in the Experience Profile dialog.

I have found this to be very useful to find the correct datasets inside my analytics database.

How to set up

  1. Download the code from github
  2. Set a random, hard-to-guess string as AccessKey in xDBHelper.aspx.cs
  3. Compile and deploy the files to your solution to a hard to guess subfolder in your webroot. (not /sitecore/admin)
  4. Access through https://yoursite/somefolder/xdbHelper.aspx?key=*AccessKey*

A word of caution:

Make sure you take appropriate measures to prevent public access to this page. Especially because the internal X-Forwarded-For http header is exposed.


Leave a Reply

Your email address will not be published. Required fields are marked *