http://www.percepio.com/

Main Window

Trace View

This is the main view of Tracealyzer, showing all recorded events on a vertical timeline going downwards. The main component of this view is scheduling trace, showing fragments of actors displayed as color-coded rectangles. The colors are unique for each actor, and are assigned based on scheduling priority. By actor we mean an execution context - a task or ISR. The default color scheme is the natural light spectrum, going from red (high priority) to blue (low priority), and finally light gray for the idle task. The exact colors used depends on the number of actors in the trace and their relative priorities. The color scheme can be changed and you can even set your own custom colors, see View -> Trace View Settings -> Set Color Scheme.

To the far left are labels showing actor names. When zooming out, the name labels are filtered so that only the most important ones are shown. Repeated labels of the same actor are then hidden, in favor of labels for less frequent actors. However, there are always at least one label per visible actor, and you can click in the trace to show the corresponding actor name label.

View Modes

The execution of tasks and interrupts can be visualized using three visualization modes, which you can quickly switch between to get best clarity for each situation. The modes are:

Gantt View Mode: Shows one column per task and interrupt. This is best for spotting execution patterns, rare tasks or interrupts. This is the default visualization mode for smaller single-core systems with up to 20 tasks. (Shortcut Key "g")
Merged View Mode: Shows all tasks and interrupts in a single column, with sideway indents to show preemption and blocking. This gives a more compact display compared to Gantt View Mode and the best sense of execution order and preemptions hot-spots. This is the default visualization mode for single-core systems with more than 20 tasks. (Shortcut Key "m")
Split View Mode: Shows tasks and interrupts in two columns, with indents like in the Merged View Mode. This removes the "noise" from interrupts by presenting them separately. (Shortcut Key "s")

Events

The main view also show event labels of different types, kernel notices, kernel service calls and user events, if enabled in the visibility filter in the lower right. The events are shown as color coded labels to the right of the fragment in which they occur.

Events labels are shown in different colors depending on type:

  • Red labels - blocking kernel calls.
  • Green labels - Return of blocking kernel calls.
  • White labels - Kernel calls that returned without blocking.
  • Orange labels - Kernel calls that failed or returned due to a timeout (not shown for all functions).
  • Yellow labels - User Events.
  • Light blue labels - Kernel notices, such as "Actor Ready" - when tasks become ready to execute.

Note
Due to limitations in the ThreadX event tracing, Tracealyzer is not always able to show the status of API calls. Orange labels are only shown in some special cases (like tx_byte_allocate). For other API functions, white or green labels are no guarantee that the call succeeded. You may however insert User Events to log relevant error codes returned by the API calls.

Note
Delay calls are shown in white, not red, even though they block the executing task. This since delays are unconditional blocking and the sole purpose of these kernel calls. The red, green and orange labels are used only for blocking on shared resources, e.g., mutexes, which may not be intentional and thereby of greater interest to study.

Clicking on a task or ISR fragment selects the corresponding actor instance and highlights it. You can follow the execution of the selected actor using the "Previous Instance" and "Next Instance" buttons. Clicking an event label selects and highlights both the actor instance and the event. When an actor instance is selected, the Actor Information display is updated, as illustrated above. This is a tree structure containing a lot of information, both general statistics of the actor and information about the specific instance. Most tree nodes that refer to a particular point in the trace are links to that location. By double-clicking them you navigate the trace view to that position. The linked tree nodes include all "Lowest" and "Highest", Triggered By", "Triggers" as well as the list of events in the end.

Double-clicking on an actor, system call or user event opens a focused view showing a list of all related events, e.g., the Object History View. This shows all system calls on a selected kernel object, i.e., a message queue, semaphore or mutex. A similar view is opened if double-clicking on an actor, showing all instances of the actor. Double-clicking on a user event shows the User Event Log, showing a textual log view of the user events. A more powerful textual log view is the Event Log.

When selecting a blocking call (red label) or a resume from blocking (green label), the matching event (call or return) event is also highlighted. You may jump to that event by pressing F8, or by using the context menu option "Find Entry/Exit of Blocking Kernel Service Call".

Note
When there are too many events in the current view to fit on the screen, they'll be hidden and replaced by X events not shown. If this happens, zoom in or use the visibility filter to reduce the number of events. The events of the selected actor instance are however always displayed.

Zoom and navigation features

To navigate the trace, you can use the mouse wheel or the scroll bar (in the right). You can also drag the view by holding down the mouse wheel or middle mouse button. The arrow buttons and page up/down buttons can also be used when the trace view area has focus.

You can select an interval by holding in the left mouse button. By right-clicking on the selection, you open a context menu with various options for the selection interval, such as Zoom In.

To measure the time between two events, select one of the events and then hold the SHIFT key while selecting another event.

Note
When searching for a particular location, it's often easier to use the Finder or one of the graphical overviews to find it. When using another view to navigate the trace, you can click or double click to focus the trace view on this location. All graphical views also support selecting a time interval (by pressing the left mouse button and dragging) and showing this interval in the trace view.

To zoom in or out, use the zoom buttons on the tool panel, the numpad + and - buttons or the zoom options in the right-click menu.

You can also zoom with your mouse wheel when holding down the Ctrl key. The scroll-to-zoom behavior is always active when Scroll Lock is enabled. If your mouse features back and forward buttons, you can use these to quickly zoom in and out.

Tool Panel

To the right of the trace view is the tool panel. At the top is the Actor Information display, which shows information about the selected actor and the currently selected actor instance, such as timing, fragmentation and any events that occur. Property values for the selected instance are displayed as well as actor average, maximum and minimum. Double-clicking on maximum or minimum values shows the corresponding instance in the trace.

For more information about the Actor metrics, see the Actor Instance Graphs section.

You can adjust the size of the three tool panel sections by dragging the borders with the mouse cursor, both the vertical layout within the tool panel and the width. You can also minimize each of the three sections in the tool panel by clicking on the title bar.

In the View Controls, the topmost buttons navigate to the previous and next instance of the same actor, based on the currently selected.

Next follows the view settings. You can set the view size (zoom level) by typing the desired view size into the view size text box and pressing enter. Under the view size setting are the grid settings. The grid is the white and gray stripes in the trace view, which shows the time scale.

Below the view settings are buttons to zoom in and out. The "Preset..." button provides predefined zoom levels, that you may edit if desired.

At the bottom of the tool panel is the View Filter that controls what is displayed in the trace view, tasks, ISRs, kernel notices, kernel service calls, and user events.

By default, all recorded actors (tasks and ISRs) are selected but no event labels (unlike the picture on the right, where all events are included). Unchecking an actor will not hide it completely, but cause it's fragments to be drawn as outlined gray rectangles. Any events in unchecked actors will be hidden.

Double-clicking on a "leaf node" opens another view (depending on the event type), that list all events of that kind, such as the Kernel Object History view. This is similar to when double-clicking on an event label, although no particular event is highlighted in this case.

Note that kernel service calls can be filtered in two "dimensions", "Kernel Object Uses" and "Kernel Service Calls". If you select entries in just one of these dimensions, no filtering is made with respect to the other dimension. But if you select entries from both subtrees, only those events that match both a selected kernel service and a selected kernel object are included. This allows for advanced filtering, such as only "send" calls on a particular message queue. Note that if selecting an incompatible combination, e.g., a Mutex function and a Timer object, you will not get any matching events.

Advanced features

Tracealyzer can identify activation causes for actor instances. For example, an instance might be activated when another actor sends to a queue or signals a semaphore. To go to the activation cause of the selected actor instance, press F9.

Tracealyzer can also identify instances triggered by the selected instance, either from the Actor Information display ("Triggers") or by pressing F10. In using F10 and there are multiple instances activated by the selected instance, you get a menu where you can select which activated actor you wish to follow.

Menu options

File

The File menu features standard options such as open trace, reload current trace and recently opened trace files. It also includes Export Current View as Image, Export Actor Data and External Tools.

Open: Loads a trace from a specified file. You can also simply drag a trace file into the Tracealyzer window.

Reload: Reloads the data from the currently open file and updates the visualizations. Can be used if the trace file has been updated.

Save Current View as Image: Allows you to export the current trace view to an image, e.g., for documentation or for sharing an issue with colleagues.

Export Actor Data: Export statistical data to a text file. The exported data includes start time, execution time, response time and fragmentation of each instance of the selected actors. You can export it as tab separated fields for import in other tools or space aligned columns for easy reading.

Settings: Allows for specifying the timestamp clock frequency and custom formatting of User Events.

Find

The Find menu allows you to quickly find the previous or next instance from the selected instance. It also lets you open the Finder dialog (can also be opened using CTRL-F).

View

The View menu allows you to configure the trace view and to open other views. See the respective page for information about the other views.

New Trace Window: Opens up a new trace view.

Trace Details: Shows recorder-related properties of the current trace, such as the number of events and the length of the trace, as well as additional technical details.

Trace View Settings: Allows you to configure the trace view, such as the colors of actors and whether to display bookmarks or not.

Trace View Mode: Allows you to set the View Mode, as introduced in the View Modes topic above.

Time Unit: Allows you to change the time unit used throughout the application.

Time Mode: Allows you to change the relative zero point in time.

Show Tool Panel: Allows you to toggle the visibility of the tool panel on the right. This can be useful if you wish to make the application window smaller, e.g., when having multiple views open. The tool panel can be restored using the trace view context menu.

Bookmarks

The Bookmark menu allows you to create and organize bookmarks. If you want to share bookmarks with colleagues, you can export and import them using the respective menu options. Any bookmarks will also be displayed in this menu.

Help

The help menu includes the User Manual, the license system dialog, and a shortcut to the target system code required by Tracealyzer, as well as diagnostic information about the application.


Copyright Percepio AB 2017, all rights reserved.