Understanding Runtime Tracing

The sequence diagram produced by the Runtime Tracing feature uses a notation taken from the Unified Modeling Language, thus it can be correctly referred to as a UML-based sequence diagram.

To view the UML sequence diagram report:

  1. Select the Runtime Tracing Viewer tab.

  2. As you recall, the Runtime Trace viewer displayed all objects and all method calls involved in the execution of the UMTS base station code. Using the toolbar buttons , zoom out from the tracing diagram until you can see at least four vertical bars.

  3. Make sure you are looking at the top of the runtime tracing diagram using the slider bar on the right.

  4. Right-click within the runtime tracing diagram and select Hide Memory Usage Bar. Repeat in order to select Hide Coverage Bar and Hide Thread Bar. You will return to these bars in a moment.

What you are looking at is a sequence diagram of all events that occurred during the execution of your code.

The vertical lines are referred to as lifelines. Each lifeline represents a Java object instance. The very first lifeline, represented by a stick figure, is considered the "world" - that is, the operating system. In this UMTS base station tracing diagram, the next lifeline to the right represents an object instance named Obj0, derived from the UmtsServer class.

Green lines are constructor calls, black lines are method calls, red lines are method returns, and blue lines are destructor calls. Hover the mouse over any method call to see the full text. Notice how every call and call return is time stamped.

Everything in the Runtime Trace viewer is hyperlinked to the monitored source code. For example, if you click on the Obj0::UmtsServer lifeline, the source file in which the UmtsServer class definition appears is opened for you, the relevant section highlighted. (Close the source file by right-clicking the tab of the Text Editor and selecting Close.) All function calls can be left-clicked as well in order to view the source code. Look at the very top of the Obj0::UmtsServer lifeline. It's "birth" consists of a UmtsServer() constructor. Left-click the constructor if you wish to view the steps that occur when an object of the UmtsServer class is instantiated.

Notice how the window on the left-hand side of the user interface - called the Report Window - contains a reference to all classes and class instances. Double-clicking any object referenced in this window will jump you to its birth in the Runtime Trace viewer. This window can also be used to filter the runtime tracing diagram; closing a node associated with a source file or class will collapse all of the associated lifelines into a single, consolidated lifeline.

Filters

Continue to look around the trace diagram. Can you locate the repetitive loop in which the UMTS base station looks for attempted mobile phone registration (it always starts with a call to the method baseStation.LogServer.checkLog())? You can filter out this loop using a couple of methods. One is to simply hover the mouse over a method or function call you wish to filter, right-click-hold and select Filter Message. An alternative method would be to use a predefined filter. You will do both.

To use sequence diagram filters

  1. Hover the mouse over any call of the baseStation.LogServer.checkLog() method, right-click-hold and select Filter Message - the function call should disappear from the entire trace.

  2. Select the menu item Runtime Trace->Filters (you'll see the filter you just performed listed here)
    Click the Import button, browse to the installation folder and then the folder \examples\BaseStation_Java, and then Open the filter file filters.tft

  3. Select BaseStation Phone Search Filter if necessary.

  4. Click the OK button.

The loop has been removed.

  1. Using the Zoom Level dropdown list on the toolbar, select a level of 50%:

Memory Usage Bar

The Memory Usage Bar is a graphical representation of the amount of memory allocated by the monitored application at any moment represented within the runtime tracing diagram.

To use the Memory Usage bar:

  1. Right-click-hold in the Runtime Trace viewer and select Show Memory Usage Bar.

You can now see, along the left-hand side of the runtime tracing diagram, a red, vertical bar. The caption of the Memory Usage Bar indicates the maximum amount of allocated memory that occurred during execution, while the mouse tool tip can be used to discern the amount of allocated memory at any moment along the graph. (Depending on your JVM, you may also notice garbage collection, indicated by areas where there is a sudden drop in the number of allocated bytes.)

This diagram can be used to expose memory intensive parts of your program that may in fact be needless churn that slows down overall execution time. You could trigger garbage collection immediately prior to suspect moments within your application, using the Runtime Trace viewer to help you decide where the garbage collection should occur, to study whether or not memory usage has become excessive. Note that this feature is specific to Java support.

  1. Right-click-hold in the Runtime Trace viewer and select Hide Memory Usage Bar.

Coverage Bar

The Coverage Bar highlights, in synchronization with the runtime tracing diagram, the percentage of total code coverage achieved during execution of the monitored application. The Coverage Bar's caption states the overall percentage of code coverage achieved by the particular interaction presently displayed in the Runtime Trace viewer.

To use the Coverage bar:

  1. Right-click-hold in the Runtime Trace viewer and select Show Coverage Bar.

Scroll down the runtime tracing diagram; note how code coverage gradually increases until a steady state is achieved. This steady state is achieved following the moment at which the mobile phone has connected to the UMTS base station. Dialing the phone number increases code coverage a bit; shutting off the phone creates a last burst of code coverage up until the moment the UMTS base station is shut off. Can you locate where, on the runtime tracing diagram, the mobile phone simulator first connected to the UMTS base station? Note that the Coverage Bar is available for all supported languages.

  1. Right-click-hold in the Runtime Trace viewer and select Hide Coverage Bar.

Thread Bar

The UMTS base station is actually a multi-threaded application; the Thread Bar graphically indicates the active thread at any given moment within the runtime tracing diagram.

To use the Thread bar:

  1. Right-click-hold in the Runtime Trace viewer and select Show Thread Bar.

Now you are looking at the Thread Bar. (Hovering your mouse over the Bar reveals the name of the active thread within a tool tip.) A left-click on the Thread Bar opens a threading window, detailing thread state changes throughout your application's execution. Pressing the Filter button in this detail window specifies the state of each thread within the region of the Thread Bar that was double-clicked. Note that this thread monitoring feature is also available for the C++ language.

  1. Right-click-hold in the Runtime Trace viewer and select Hide Thread Bar.

Not only can the runtime tracing feature capture standard function/method calls, but it can also capture thrown exceptions.

  1. View the very bottom of the runtime tracing diagram using the slider bar.

Do you see the icons for the catch statement - ? The second Catch Exception statement is preceded by a diagonal Throw Exception. Why diagonal? Because when the exception was thrown, prior to executing the Catch statement, the UmtsException constructor was called. Click various elements to view the source code involved in the thrown exception and thus decipher the sequence of events.

This exception occurred by design, but it is clear how the runtime tracing feature, through the power of UML, would be extremely useful if you have:

And you are guaranteed the identical functionality for application execution on an embedded target.

Further Work