Last week I got several questions from our dynaTrace AJAX Community members regarding advanced features I mentioned in the blog 5 Steps to Automate Browser Performance Analysis with Watir and dynaTrace AJAX Edition:

  • How to create custom timers in your own JavaScript code?
  • How to automate dynaTrace AJAX Session capturing?
  • How to capture values that are assigned to JavaScript object properties?

I believe that this information can be useful for anybody working with the FREE dynaTrace AJAX Edition in order to automate web site analysis and extend the captured data with additional measure points that are essential for you.

What are custom timers and what are they good for?

While recording a session with the dynaTrace AJAX Edition you can add custom markers to your recorded session via the dynaTrace AJAX Edition Toolbar in Internet Explorer. Simply enter a text in the marker text box and click Insert Mark:

Insert a custom Marker via the AJAX Edition Toolbar while recording a session
Insert a custom Marker via the AJAX Edition Toolbar while recording a session

When analyzing the data in the TimeLine View all Markers are visualized by the Marker icon. A tooltip shows the name you have given the Marker and the timestamp when the Marker was added:

TimeLine shows all Markers added while recording a session on
TimeLine shows all Markers added while recording a session on

This feature is very handy and is used by many of our community members when performing manual tests to either manually time certain sequences of their tests or to mark an interesting timestamp in order to find it quickly when analyzing the data. But there is more you can do with this feature.
First Use Case: In his last blog post – Alois highlighted the challenges of identifying the actual execution time of JavaScript code that makes use of timers or other asynchronous execution options such as dynamically creating script tags to download additional JavaScript code. In these cases it can be really challenging to follow the individual JavaScript traces that are triggered by timer invocations or by dynamically loaded scripts and calculate the exact time for a certain action. Automatically adding markers at the beginning and at the end of an asynchronous action solves the problem of measuring execution time.
Another use case comes with automated testing. When using functional testing tools such as Watir, Selenium, SilkTest, QTP, … you want to measure how long certain test steps take – you basically automate what you would normally do manually as explained in the beginning of this paragraph. Instead of clicking on the “Insert Mark” button the Testing Tool should automatically set markers to accurately and consistently measure timings for individual test steps.

How to create custom timers without using the toolbar?

Once dynaTrace AJAX Edition is active in your browser session a global JavaScript method called _dt_addMark is available to the web application. This allows us to automate marker creation in the two highlighted use case scenarios.

Instrument your JavaScript code

You can call _dt_addMark from your JavaScript code. Just make sure that you check if _dt_addMark has been defined – as it is only defined if the dynaTrace AJAX Edition is actively recording actions in your browser. The following code snippet shows how to check on the existence of this method and how to call it:

if(typeof(_dt_addMark)!="undefined") _dt_addMark('MyCustomTimerName');

You have to use this way of checking the availability of _dt_addMark because of the nature of how dynaTrace adds this method to the JavaScript engine. A simple if(_dt_addMark) will not work even though it works in other similar scenarios. The following is a simple html page that opens two alert boxes and creates markers before and after calling the method that opens the alert box. :

function myFunc(msg) { alert(msg); } 
// here is some script code 
if(typeof(_dt_addMark)!="undefined") _dt_addMark('beforeFirstCall'); 
if(typeof(_dt_addMark)!="undefined") _dt_addMark('after firstCall');
if(typeof(_dt_addMark)!="undefined") _dt_addMark('before secondCall'); 
if(typeof(_dt_addMark)!="undefined") _dt_addMark('after secondCall');

When running this sample with dynaTrace AJAX Edition we can see the Markers in the TimeLine

Custom added Markers in TimeLine View
Custom added Markers in TimeLine View

and also in the PurePath View

Custom added Markers in PurePath View
Custom added Markers in PurePath View

The Markers in the PurePath view are especially valuable. First of all we see all Markers in the top activity list. In case your markers were set in different JavaScript handlers or somewhere deep in the JavaScript traces (traces can especially get very deep if you use timers as every timer invocation is visualized as a new subnode in the JavaScript trace) the top list makes it easy to get an overview of all markers. Use the filter option of this view to e.g.: only show markers in case there is lots of other activity going on such as JavaScript, Rendering or Network traffic.
Besides seeing them in the activities list the markers also show up in the JavaScript trace at the position where these markers were created. The start time indicates the time stamp of when those timers were created. Simply do the math and we know how much time elapsed between the individual markers.

Insert markers with your testing tool

Testing tools that allow you to inject JavaScript into the application under test can take advantage of _dt_addMark as well by calling this method between test steps to automatically time individual user interactions. I already covered this topic in the following blog post: Automate Browser Performance Testing with Watir and dynaTrace AJAX Edition. Check out the paragraph called Advanced Step – adding custom markers.

How dynaTrace AJAX Session Capturing works

You have probably noticed that – although you have the dynaTrace AJAX Edition Add-on installed in Internet Explorer – the AJAX Edition is only capturing data when the browser gets started from the dynaTrace AJAX Edition or by clicking the dynaTrace toolbar button which launches the AJAX Edition and connects to it. The magic that triggers data capturing lies in some environment variables that the Add-On checks when the Add-On gets loaded into the browser. The dynaTrace Community Forum Entry Automation with dynaTrace AJAX Edition explains all available environment variables.

The variable DT_IE_AGENT_ACTIVE defines whether the Add-On should be active. If the value is set to true the Add-On tries to connect to the dynaTrace AJAX Edition. When launching the browser from the dynaTrace AJAX Edition, iexplorer.exe is launched with this environment variable set to true. The toolbar button in the dynaTrace AJAX IE Toolbar is another way to “wake-up” the Add-On by telling it to launch and or connect to the running instance of the dynaTrace AJAX Edition and then start collecting data.

Another interesting variable is DT_IE_SESSION_NAME. This variable allows you to define the name of the captured session. This is especially useful when running multiple tests on different browsers against different applications. I’ve seen users to come up with a pattern like BROWSERVERSION_MACHINENAME_WEBAPP_BUILD_DATE, e.g.: IE7_WINXP_COMMERCEAPP_B324_20100413.

Hints for using it with your testing tool

Key for this to work is to launch the browser with these environment variables set to the correct values, DT_IE_AGENT_ACTIVE=true and DT_IE_SESSION_NAME=YourSessionName. In case your testing tool doesn’t allow you to specify environment variables for the launched browser you can globally set these environment variables so that every instance of IE will have them set. The problem with that obviously is that every instance of IE will try to connect to the dynaTrace AJAX Edition. On a “pure testing machine” where you only run your browsers through your testing tool this should be a doable option.

Remember: In order for this to work you have to have a running dynaTrace AJAX Edition as the Add-On won’t collect any data without an active connection to the dynaTrace AJAX Edition.

Troubleshooting Tip: Use a tool like Process Explorer to verify if the environment variables have been correctly set for the browser instance used by the testing tool. Sometimes testing tools re-use existing IE processes that do not have the environment variables set.

Capturing method and property arguments

By default method arguments and return values of JavaScript or DOM methods are not captured by dynaTrace AJAX Edition. This option can be turned on via the Preferences Dialog as explained on the community portal post Enable Argument Capturing. Once this option is turned on dynaTrace AJAX Edition captures method arguments and return values of JavaScript and DOM methods. It also captures some values of DOM properties, e.g.: User-Agent, … In general property values are not captured.

A community member recently asked if there is a way to capture property values of JavaScript objects. Here is a sample code snippet that he posted. He wanted to capture the value of Sizzle that got set to the query property:


There are multiple workarounds for this:
a) Implement getters & setters for the query property. Getters & Setters are JavaScript methods where the AJAX Edition automatically captures the set-argument and the get-return value

window.peppy.setQuery = function(querystring) {this._query = querystring;}
window.peppy.getQuery = function() {return this._query;}

Sizzle = window.peppy.getQuery();

The drawback of this approach is that it may require massive change of your JavaScript code as you need to add getters and setters for all properties that you want to capture.

b) Use a dummy logging method and pass the value you want dynaTrace AJAX to capture

function dummyFunc(arg) {}

dummyFunc("Value of Sizzle: " + Sizzle);

This approach is less intrusive to your own code than the previous example but it still requires you to add some additional lines of code.

c) Use _dt_addMark to create a marker with the value you want to capture

if(typeof(_dt_addMark)!="undefined") _dt_addMark("Value of Sizzle: " + Sizzle);

You can follow the conversation I had with Olivier about this on the General Usage Issues Community Forum Page.

More advanced material?

This advanced material shows you what else is possible with the dynaTrace AJAX Edition. We are constantly working on making the tool better to support our community in their specific use cases. In order to learn more about your requirements I encourage you all to either comment on this post, comment on the community forum pages or add a wish to the wish list so that we know what features are required out there to make your day easier.

For folks that are new to this blog I recommend to check out some other blogs and resources such as Web Performance Best Practices on, Webinar with on Best Practices to prevent AJAX/JavaScript performance problems or End-To-End Web 2.0 Performance Engineering with dynaTrace.