Introduction

Welcome to Tracealyzer

Overview

Percepio Tracealyzer is a powerful tool for tracing and visualization of embedded and IoT software systems at runtime. More than 30 views offers amazing insight into the real-time behavior, speeding up debugging, validation and performance optimization. This saves you many hours of frustrating trial-and-error troubleshooting. With Tracealyzer you see what is really going on in your system!

Tracealyzer provide state-of-the-art visualization developed since 2004 and actually understands the meaning of many software events from supported RTOSes and middleware stacks. This allows Tracealyzer to perform advanced analyses and provide many specialized visualizations, with intuitive links between the views and highlighting of related events. The resulting visualization makes it much easier to draw conclusions from the data, understand the problem and verify the solution.

For RTOS-based systems, Tracealyzer shows task scheduling and timing, calls to RTOS services (including blocking and timeouts) and internal RTOS events such as task activations and OS ticks. Tracealyzer can also show interrupt handlers as well as User Events logged from your application code.

On top of this, Tracealyzer allows you to create user-defined visualizations using State Machines and Custom Intervals. This way, you can visualize specific aspects of importance for your system and the problem at hand.

Tracealyzer can be used side-by-side with a traditional debugger and complements the debugger view with a higher level perspective, ideal for understanding real-time issues where a classic debugger is not sufficient.

Tracealyzer does not require additional tracing hardware, which means that it can be used in deployed systems to capture rare errors which otherwise are hard to reproduce.

Percepio Tracealyzer consists of two main components:

  • The PC application Tracealyzer, that provide trace visualization. Tracealyzer v4.2.0 officially supports Microsoft Windows and Linux hosts. In the latter case, please refer to the Running on Linux section below.
  • A trace creation component. Tracealyzer supports several third-party solutions provided by RTOS vendors, and Percepio also provides the Percepio Trace Recorder library that supports several RTOSes and soon also bare-metal setups. Read more under the Creating and Loading Traces section.

Running on Linux

Tracealyzer v4.2.0 officially supports running the host application on Linux, using the Mono framework. On some Linux distributions, you may need to install additional libraries. For detailed information, see RunningOnLinux.txt in the Tracealyzer application directory.

User Interface

Tracealyzer offers over 30 views, providing different perspectives of the trace data. There are several ways of accessing and arranging these views.

The most frequently used views are found in the Navigation Bar (the left-side icons). You can adjust the contents of the Navigation Bar in the Navigation Bar Settings (File menu -> Settings).

To overview all views and features in Tracealyzer, select "All Views" as shown above. This provides a brief description of each view along with a thumbnail picture, a button to open the selected view ("Show View") and a User Manual link ("Read More"). You can also open the views by double-clicking on the thumbnail pictures.

You may also access the views from the Views menu, just like in older versions of Tracealyzer.

You can rearrange the views by docking them next to other views, or change the view to a free-floating window. To move a view, place the mouse cursor over the name list in the top (where the "X" close button is), hold down the left mouse button and drag the view. When dragging the view, possible docking targets are displayed. Move the mouse cursor to the desired docking target and release the mouse button. If you release the mouse button when not on a docking target, the view will become a free-floating window. This way, you can combine multiple views and arrange them any way you like.

If you have multiple screens, you can create additional main windows (one for each screen) and move views in between them. To do this, right-click on the name list of the view and select "Undock to New Window".

Mouse Actions

Generally, the mouse buttons behave like this:

  • Left Click
    • Set (or clear) selection, highlighting in all views
  • Left Double-Click
    • Drill-down if available, i.e. show more information about the selection, like opening the Instance Details
    • Set (or clear) selection and focus, scrolling most other views to show the information
  • Right Click
    • Open context menu to get more options

There are three types of views that react to mouse wheel actions:

  • Vertical Timeline
    • Wheel will scroll the timeline (up/down)
      The best example of this view is the Trace View
  • Horizontal Timeline
    • Wheel will scroll the timeline (left/right)
      This includes all plots and histograms, like CPU Load
  • Lists
    • Wheel will scroll the position (up/down)
      This includes anything showing a scroll bar, including this manual

For views with different scroll bars, like Trace View, holding SHIFT will switch the wheel scrolling from the timeline to the view (horizontal).

For views with a timeline, holding CTRL will change from scrolling to zooming; wheel up to zoom in, wheel down to zoom out.

If your mouse has additional buttons the first two ones (which normally handles Browse Forward and Browse Back in your normal web browser) will also zoom in/zoom out.
It is up to the operating system to tell Percepio Tracealyzer which buttons they are, and because of this it is not possible to change these mappings within the application.

View Ports and Sync

A View Port is the part of the trace that is currently in view. By default, Tracealyzer has two view ports, "Details" showing 100 ms and "Overview" showing 10 s, and each timeline view is connected to either Details or Overview. All views connected to same view port are synchronized, so if zooming and scrolling one, all are updated.

You may change the view port of view using the Sync option in the view menu. Selecting "Unsynchronized" means that the view is independent from other view ports. The "Unsynchronized" option can be used the pause views when recording in streaming mode with live visualization.

By Selecting Sync -> Custom..., you may create a new view port for this view. You may then connect other views to your new view port in order to synchronized them.

The View Port Overview view lists all view ports and shown their current position on the trace timeline.

Filtering

By default, filtering is synchronized for all views using the same View Port. This is possible to turn off by using Sync -> Unsynchronized Filter. Note! When the View Port is changed the filter will always be set to that View Port.

When changing the filter using either a built in legend (used in most horizontal views) or the Filter tool, all changes are made directly for each view.

When either filter or view is Unsynchronized this will be indicated by the icon in the menu and by showing "No Sync" in the title bar.

Layouts

A layout is the arrangement of the views in Tracealyzer. You may store and restore the layout using the options in the Layout menu:

  • Reset to Default Layout - Applies the default layout.
  • Remember Layout - Enable this option to let Tracealyzer remember the previously used layout and restoring it when starting Tracealyzer.
  • Layout Locked - If this option is enabled, the views can't be rearranged. Can be useful to prevent accidental changes once you are happy with your layout.
  • Save New Layout - Sets a name for the current layout, so it can be restored later. This allows for having multiple layouts for different kinds of analysis.
  • Manage Layout - Allows for renaming or removing a saved layout.
  • Layouts - Allows for restoring a previously saved layout.

Tool Windows

Apart from all visualizations, Tracealyzer provides Tool Windows that are important to know. Some of these are shown by default, but if you close them, you can open them again from the View menu.

Selection Details show additional information and statistics about the selected entity, e.g. a task in the trace.

Performed Events show a list of all trace events corresponding to the selected entity.

Navigation opens the Navigation Bar, if not displayed.

View Port Overview shows the available view ports, which synchronize the timeline views.

Filter allows for selecting what information that are displayed in the views.

Time Formats

Tracealyzer supports different time formats and modes that can be selected through the View -> Time Format menu.

  • Trace Time - A human readable time mode. The format is typically hh:mm:ss.ms.µs, where the more significant parts are omitted if zero.
  • Native Ticks - The timestamp from the trace format in its native frequency.
  • Event Index - This uses the order of events in Tracealyzer event list instead of time.
  • Wall Time - The full date and time, formatted using .NETs DateTime and TimeSpan objects. This mode is only available when there is some form of time reference.

Time Offset Mode

In addition to different formatting modes, Tracealyzer also supports different offset modes configurable from the View -> Time Offset Mode menu.

  • Relative Trace Start - The first event in the trace is time 0.
  • Relative Trace End - The last event in the trace is time 0. This means everything except the last event will have a negative timestamp.
  • Absolute - The absolute time according to this trace format and/or trace recording solution. This is usually relative to system startup or the point where tracing was enabled.
  • Relative to user defined point - If you right-click a point in any view that has a timeline, you can specify that time as relative time 0.

Keil µVision Integration

Percepio Tracealyzer integrates with Keil µVision to allow for tracing of Keil RTX5 and the Keil MDK middleware. The tracing is done using the Keil Event Recorder, included in Keil MDK. Percepio Tracealyzer connects to Keil µVision to receive the trace data, and this connection also allows for controlling the Keil µVision debugger. An example trace can be found in the RTX5 folder. To open it, you can simply drag-and-drop tracedata.evr into Percepio Tracealyzer, or use the File -> Open command.

"Percepio Tracealyzer enables unparalleled insight into the execution, timing and interactions of the RTX5 real-time operating system, the MDK middleware components and the user application. Percepio is the first ARM partner to utilize our new Event Recorder technology, which provides time deterministic high-speed access to a running target system."
Reinhard Keil, Director of MCU Tools at ARM.

Creating and Loading Traces

Introduction

This section explains how to create and load traces.

Keil RTX5

Enable Tracing

Percepio Tracealyzer requires Keil MDK (µVision) version 5.23, but it is recommended to use the latest stable release. Specifically, it relies on the Event Recorder interface. To configure this for use with Percepio Tracealyzer, follow these steps:

Step 1. In the "Manage Run-Time Environment" dialog, found under Project -> Manage -> Run-Time Environment, verify that you are using RTX5 and not an older version of Keil RTX. Make sure there are no selections under CMSIS:RTOS and make sure you have selected the Source variant of CMSIS:RTOS2:Keil RTX5. If your project was using an older version of RTX and you like to upgrade, see the RTX5 Migration Guide.

Step 2. Enable the Event Recorder support in the "Manage Run-Time Environment" dialog, under Compiler:Event Recorder, as illustrated above.

Step 3. Check the buffer size setting of the Event Recorder in EventRecorderConf.h ("Number of Records"), as illustrated below. The buffer needs to allow at least 512 records but we recommend 1024 if you have enough RAM. Each record uses 16 bytes RAM.

Step 4. Add #include "EventRecorder.h" in your main file and add a call to EventRecorderInitialize early in your main function, preferably before calling osKernelInitialize, but after the clock initialization. It is possible to initialize the Event Recorder at a later point, but this will not get a complete trace of the start up.

Step 5. Verify that the Event Recorder is working through these steps:

  1. Build and Download to target
  2. Start a Debugging session
  3. Open the Event Recorder view (under the "Analysis" button, see below screenshot)

  4. Step over EventRecorderInitialize and verify the Init Event shows up in the view.
  5. Step over the first osThreadNew call and verify events show up in the view.
  6. Run the target and check that events keep coming as expected.

To learn more about the Event Recorder and its API, see the Event Recorder documentation.

Step 6. For best performance, make sure the clock frequency of your debug interface is at the maximum setting. In the project options in Keil µVision, select the Debug page and "Settings" in the top right corner to open the settings of your debug probe. For ULINK debug probes, the setting is called Max. Clock. Select the highest setting allowed (e.g. 50 MHz).

Step 7. To ensure correct timestamps, verify that Core Clock setting is correct, under Project > Options > Debug > Settings > Trace. If not sure, you may inspect the global variable SystemCoreClock after SystemCoreClockUpdate has been executed.

Step 8. Finally, you need to enable the UVSOCK interface in Keil µVision. Select Edit > Configuration > Other and take a look at "UVSOCK (TCP/IP) Settings". Check the "Enabled" checkbox. The Port setting can typically remain at the default value (4823), unless this port is already used by another application.

Trace Recording

When completed the steps to configure Keil µVision, now start Percepio Tracealyzer. First, verify that Percepio Tracealyzer uses the correct UVSOCK port by selecting File > Settings. The "Keil µVision Port" setting needs to match the corresponding setting in Keil µVision, as described in step 8 above (i.e. under Edit > Configuration > Other > UVSOCK (TCP/IP) Settings > Port).

See Settings for more information.

To record a trace simply click the Record button, normally found at the left side bar in Percepio Tracealyzer. When connected to µVision there are a few additional actions to perform using the Action button, making it possible to Enter/Exit debug mode and to Run, Stop or Reset the target. See Streaming section for more information.

When using the Record button, Percepio Tracealyzer will automatically try to start recording the trace after connecting to µVision.

When satisfied, click Stop button in the navigation bar, or Stop Session in the Live Stream view, and the trace will open automatically. Each trace creates a directory of data files found under "[User]\Documents\Percepio Tracealyzer-Traces\[date and timestamp]". To make a new trace, simply click either the Record button or Start Session.

Troubleshooting

In order to get the best result when tracing, please consider the following:

  • It is advised to call EventRecorderInitialize() early in main, before creating any kernel objects, but make sure this is called after the core clock (i.e., the timestamping source) has been configured.
  • Start the recording session at the system startup. While it is possible to connect to a running system and receive a trace, it will lack information about all previous events.
  • Use constant strings instead of local (stack) variables when registering object names. This way Percepio Tracealyzer can read the names from target memory even when it is not receiving all create events.
  • If the time scale presented in Percepio Tracealyzer seems to be scaled incorrectly, verify the Core Clock setting, as explained in Step 7 in the Enabling Trace guide.
  • If the debug probe used is not fast enough there may be overflows, i.e., that the Event Recorder is not able to keep up with the stream of events. Percepio Tracealyzer will generate a warning if this is detected and mark the location in the trace where the overflow was detected. The result is normally a gap in the trace, during which the last logged task seem to execute and may seem to have an unusually long execution time. To avoid such problems, try the following:
    • Increase the size of the Event Recorder buffer (see Step 3 in the Enabling Trace guide).
    • Increase the clock frequency of the debug interface (see Step 6 in the Enabling Trace guide.
    • Try a faster debug probe - a ULINKplus or ULINKpro is recommended.
  • Keil µVision allows for filtering of events in order to reduce the amount of data produced. But assuming your debug probe can manage the data rate, we recommend recording all events. This since Percepio Tracealyzer does some pretty advanced analysis of the trace and calculate the states of objects based on the operations observed. If you want to filter the trace in runtime, don't exclude kernel events related to task scheduling. You may exclude API calls, if excluding ALL events related to that kind of object. Otherwise, if some kernel object is partially traced, it may be displayed incorrectly.

Live Stream

This view displays information about the data collection itself, while recording a streamed trace. The diagram in the middle shows the CPU load of the target system, i.e., the percentage of processor time spent in application tasks (i.e. not idle) in relation to the total processing time.

The Live Stream view also shows if the trace data rate is higher than the streaming connection can handle, causing events to be lost. In such cases, it displays a counter showing the number of dropped events. If you encounter that, please refer to the Troubleshooting section corresponding to your RTOS.

Using the "Disable Live Visualization" checkbox, you can disable all live updating views in Tracealyzer, and the continuous loading of the trace. This way, you can record traces of unlimited length, and then use the Trace Preview to analyze them and load relevant sections.

The CPU load visualization is however not affected by this setting. This can remain active also when recording very long traces, as its memory usage is constant and independent of the recording length.

While streaming, use Sync -> Unsynchronized to pause the live updates for a view, making details in the view easier to find. To have the view update again, use Sync menu and pick the Details or Overview, marked with default one for the current view.

Trace Preview

The trace preview window shows a high level summary, from which you can select and load a smaller section of the trace of relevance. This is intended for very large traces that can't be loaded in full, due to the amount of RAM required.

The preview shows the CPU load of the target system over the entire trace, which gives a high-level overview of the system behavior. From this graph, you may select and load a smaller section by holding down the left mouse button in the graphs and dragging.

The table below the graphs shows statistics and extreme values for actor properties, such as execution times and response time, over the entire trace. You can locate the corresponding point of an extreme value by double-clicking on the corresponding table cell. This will highlight the point in the graphs and select a section centered on this point.

Memory Estimate

In the bottom of the preview window, you find the memory estimate indicator. Since loading a very long trace can easily eat up all available memory, you should make sure to not load too long sections. The memory estimate shows the estimated memory usage of loading the current selection, helping you avoid running out of RAM.

The gray part (on the left) shows the amount of memory used by your operating system and other applications.

The blue part (in the middle) shows how much memory Tracealyzer is currently using.

The right-most part is green if the current selection is estimated to fit in memory, yellow if the selection is estimated to be a close fit, or red if estimated to be too large to load.

Note
A yellow or red area does not necessarily mean that the trace can't be loaded. This is just an estimate, and if there is enough virtual memory available the trace will load anyway, but the performance of your computer is likely to be affected.

User Events

Introduction

You may log any event or data in your application code as User Events by adding calls to the recorder library.

As shown below, user events are displayed in in the Vertical Trace view (as yellow labels in the left view), in the Event Log (lower right view) and if you include data arguments in your user events, you can plot this data using the User Event Signal Plot.

If you log any kind of state transitions in your system as user events, you can define a State Machine based on these events.

User events inserted at strategic locations can be used for detailed profiling of your system, i.e., to measure the time between these events. This by defining a Custom Interval based on the user events.

The details of logging user events depends on the recorder library used, which depends on which RTOS you are using. Learn more under Creating and Loading Traces, in the subsection about your specific RTOS.

User Events in Keil RTX5

Overview

User Events are custom events that you generate from your application code. They can be used for logging any kind of event and/or data, including variables in control algorithms, states, inputs and outputs. User Events are logged and transferred in the same way as other events, but are intended to be generated from your application code rather than by kernel functions.

In Keil µVision, User Events are logged by calling the functions EventRecord2, EventRecord4 or EventRecordData. Timestamps are stored automatically. EventRecord2 stores two 32-bit integers while EventRecord4 allows for storing four integers. EventRecordData stores up to 1024 bytes and can be used for storing strings as ASCII text. These are described further in the Event Recorder documentation, but as an example, EventRecord2 has the following declaration:

uint32_t EventRecord2(uint32_t id, uint32_t val1, uint32_t val2)

The id parameter is a numeric event code, containing three fields:

  • msg_no (bit 0-7): identifies the specific event, within the scope of the component.
  • component (bit 8-15): identifies the "producer" of the event, e.g. a certain software component or subsystem.
  • level (bit 16-17): the "importance" of the event (can be used for runtime filtering of events).
    • EventLevelError (0x00000U): Run-time error in the component.
    • EventLevelAPI (0x10000U): API function call.
    • EventLevelOp (0x20000U): Internal operation.
    • EventLevelDetail (0x30000U): Additional detailed information of operations.
To pack these three fields into a single 32-bit identifier for the EventRecord functions, you may use the EventID macro.

Example:


              #define ComponentSensorY 0xBB
              #define EventInputY 0x00
              ...
              EventRecord2( EventID(EventLevelDetail, ComponentSensorY, EventInputY), mySensorValue, 0 );
            

The resulting events are shown with yellow labels, as illustrated below, assuming they are enabled in the View Filter. You can also view the User Event data in the Event Log Event Log and in the User Event Plot.

The default numeric display can however be difficult to comprehend, at least if you have multiple types of events. To get a better understanding, you can setup Percepio Tracealyzer to translate the numeric codes into a custom format with descriptive names and labels, as illustrated below.

Custom Formatting

The custom formatting is specified by creating a SCVD file (Software Component View Description). SCVD is an XML format specified by ARM and detailed documentation is found here. The SCVD format allows you to specify custom formatting for your User Events, based on Events and Components. An example from the demo trace is shown below.

(Click to open file in external editor)

The Component elements specify the producers of events, and is used for grouping the User Events into "User Event Channels", i.e., the names shown in the View Filter such as "Sensor Y" and "Sensor Z" in the above screenshot. A component typically refers to a software component/module/subsystem, but the meaning of a Component is up to the user. Note that components are not mandatory to specify. If no matching component is found for an Event, the numeric component code is shown instead.

For each Component specified, the following attributes are supported:

  • no (mandatory): The numerical code of the component, corresponding to bits 8-15 in the event id. Percepio Tracealyzer groups all events matching this component code into the same User Event Channel.
  • name (mandatory): The name of the component, sets the name of the User Event Channel.
  • brief: A shorter name for the component (optional). Overrides as name for User Event Channel if specified.

Note that Components must be placed withing a "Group" section, as shown in the example. However, Percepio Tracealyzer does not care about which Group a particular Component belongs to, the Group names or the number of Groups specified.

For Events, the following attributes are supported:

  • id (mandatory): the event code provided to the EventRecord calls (lower 16 bits, msg_no and component).
  • property (mandatory): the string to show for this event in Percepio Tracealyzer.
  • level (optional): the importance of the event (Error, API, Op, Detail).
  • value (optional): a format string for the data arguments, e.g. "%d[val1]", where %d specifies the data type and val1 specifies to use the first parameter. The follows format specifiers are supported:
    • %d: decimal integer value
    • %x: hexadecimal integer value (32-bit or 64-bit)
    • %S: address as symbolic name, or hexadecimal value if failed
    • %t: ASCII text
    • %E: symbolic enumeration value, or decimal value if failed

    Multiple arguments can be specified within the format string, e.g. "%d[val1] %x[val2]". The value attribute is optional; the default formatting is used if not specified.

    See the Keil's Value Output page for more information.

To apply your SCVD file to the trace data, you need to register the SCVD file in Keil µVision. You find this option under Project > Options > Debug. There click on "Manage Component Viewer Description Files", then "Add Component Viewer Description Files" and there select your SCVD file.

To modify an existing SCVD file, you don't need to run a new trace session every time to verify the results. You can simply edit the local copy of the SCVD file found in the trace directory (under "[User]\Documents\Tracealyzer for Keil RTX5-Traces\...") and reload the trace in Percepio Tracealyzer to apply your changes. However, note that this is a local copy that won't be used for the next trace session, so remember to also update the original SCVD file as specified in "Manage Component Viewer Description Files".

Intervals and State Machines

Introduction

Tracealyzer allows for defining custom data sets, based on events in the trace, which can be visualized and analyzed in several ways. This allows you to analyse system-specific properties, i.e. the things that really matters for your system.

There are two kinds of custom data sets: Intervals and State Machines.

An Interval is used to measure or highlight the time between two specific events. By adding an Interval definition, you create a data set containing all intervals (pairs of events) matching the definition.

Example: Assuming a trace containing the user events "On" and "Off", you can define an interval starting at "On" and ending at "Off", and thereby see all "On" -> "Off" sequences, independent of other events in between.

A State Machine is used to visualize any kind of state information logged in the trace. When defining a state machine, you specify the events corresponding to related state changes, and how to extract the state information from those events. This results in a group of interval data sets, one for each observed state, representing the state machine.

Example: Assuming a trace containing the user events "On" and "Off", you can define a state machine "MyFSM" based on these events. Each occurrence of "On" or "Off" is then interpreted as the new state of "MyFSM".

Tracealyzer also provides a predefined list of intervals and states for objects that Tracealyzer is aware of. This way you can include, e.g., task scheduling states, and even TCP socket states (assuming you are using a TCP stack supported by Tracealyzer).

Intervals and states can be visualized and analyzed in several ways, as shown in the below example. In this example, the intervals are generated by defining a state machine based on user events, but all kinds of intervals can be shown in this way.

Intervals and states can be displayed in several Tracealyzer views, and you can also generate statistics.

  • Trace View
    Intervals/states are shown in the trace view as a separate "Interval" field, in parallel with the RTOS trace. This effectively provides a software logic analyzer.
  • Interval Timeline
    Intervals/states can also be displayed in a separate timeline using Interval Timeline view, as shown in the upper right view above.
  • Interval Plot
    The duration of intervals can be plotted over time, as shown in the lower right view above. The X axis indicates the start time of the interval, and the Y axis shows the duration. This way, you can study the time between two events and how it changes over time.
  • State Machine Graphs
    A state machine can be viewed as a directed graph, showing all observed states and state transitions. Just open the State Machine Graph.
  • Statistics
    You may generate a statistics report for intervals, including state intervals, where you can see the shortest, longest and average duration over the whole trace. Do this by opening the Intervals and State Machines window and then right-click on the interval definition in the list.
Note: You may use the Filter view to select which intervals to display.

Intervals and state machines are added by using Views -> Intervals and State Machines, shown in the below screenshot. Here you see all your custom data sets and you also have three buttons for adding new definitions. Learn more about this dialog on the Intervals and State Machines tool page.

Intervals and States for Keil RTX5

When tracing an RTX5 system, there is a possibility to include events from the TCP stack in Keil MDK. Tracealyzer includes awareness of the Keil TCP events and generates a state machine for each TCP socket in the trace.

They are however not shown by default. To see them in the trace, open the Intervals and State Machines tool and select "Add Predefined", where all sockets found in the trace are listed. Select and add the ones you are interested in, and they are shown in the trace.

Views

Actor Instance Graphs

The Actor Instance Graph views display timing properties of actor instances, like execution time, response time, response interference and fragmentation. Use the combo box at the right to select which property to see.

Each data point in the graph represents a specific actor instance, where the x-axis shows the timing information and the y-axis the property value.

This example shows execution time per actor.
Clicking a plotted instance will show and highlight it in the trace view. You can filter actors by clicking on an actor in the legend to the right.

Actor Migrations

The Actor Migrations graph shows the amount of context switches over time. For each time interval, a bar is drawn for each actor beginning or resuming execution at least once in that interval.

The height of each bar, or bar section, shows the number of migrations within the given interval.

Actor Statistics Report

The Statistics Report provides performance statistics for tasks and traced ISRs. This includes minimum, average and maximum values for properties like task executions times and response times. Moreover, most metrics are linked to the main trace view, allowing you to quickly find the corresponding trace locations. The report can be generated for a selected interval, or for the whole trace.

You generate the Statistics Report using the option in the View menu. This option is also available when right-clicking on a selected interval in other views. A configuration dialog is then shown where you can select which tasks, ISRs and properties for these you wish to include.

The available properties include high level statistics per task and ISR, like CPU usage, but also provides more details statistics for individual Actor Instances. As explained in Terminology section, an "Actor Instance" means one iteration of a task loop, or an ISR execution from entry to exit.

The interval in focus of the report is shown in the bottom ("Interval: "), either the selected interval from the main trace view, or the full trace if no selection exists.

Available properties are:

  • Count: The number of Instances of the Actor in the trace or selected interval.
  • CPU Usage: The relative amount of processor time used by the Actor (in percent).
  • Execution Time: The time in microseconds for executing one Actor Instance, excluding any time spent in preempting tasks and traced ISRs. If there are Actors not included in the trace (ISRs without trace calls, or excluded tasks), the reported Execution Time may include the time spent in such Actors.
  • Response Time: The time from the start of an Actor Instance until it is finished. If "Actor Ready" events are included in the trace, those are counted as the starting point of the Instance.
  • Periodicity: The time between two adjacent Instances of the same Actor, measured from start to start. If "Actor Ready" events are included in the trace, they are counted as the Instance start.
  • Separation: The time between two adjacent Instances of the same Actor, measured from end to start. If "Actor Ready" events are included in the trace, they are counted as the Instance start. A separation of 0 means that the Instances follow in direct sequence.
  • Fragmentation: The number of scheduling fragments within the Instance (i.e., the trace view rectangles). This value indicates the number of interruptions, e.g., ISRs, preemptions by higher priority tasks, blocking on mutexes etc.

Click the Show Report button to generate and view the report. The report has three sections, an introduction, a table with descriptive statistics (min, average, max values). The distribution histograms are only included if the checkbox Show Graphical Diagrams is enabled

All properties related to time are by default expressed in microseconds, but this is affected by the "Time Format" setting found under the View menu. The report can also be generated in text format, that is easy to import in other tools. Use the "Data Export" option to output the data in text format. To save the report, select "Save As" in the File menu of the Statistics Report Viewer.

All min and max values are linked to the Finder dialog, as well as the histogram bars. When clicked, the Finder dialog is opened with the filter set to find matching Instances. The first match is then shown directly in the main trace view.

Asynchronous Stack Trace

This view shows stack trace information from asynchronous data. It will show the current stack trace state at any given time.

Default behavior is to reload the stack trace when selection or view area is updated. This can be changed in the View menu.

Communication Flow

The Communication Flow graph offers a quick overview of the communication and synchronization between actors in a trace, through message queues, semaphores and mutexes.

This graph can be generated over a whole trace, or for a specific interval only. For example, you might use the CPU Load Graph view to identify a peak where there is a lot of activity, then select that peak using a mouse drag selection, right click and select "Show Communication Flow" in the context menu to show the communication flow graph of that specific interval.

Actors are shown as rectangles, and other objects are shown as ellipses or hexagons. Ellipses are used for directional communication and synchronization objects, while hexagons are used for bi-directional objects like Mutexes and similar.

Double-clicking on any node opens a related view that displays all matching events, such as the Object History view.

There are two modes in this view:

  • Actors and Objects: Shows all objects and dependencies, both actor communication and dependencies on synchronization objects, like Mutexes.
  • Actors Only: In this mode, only those actors are shown which have communication dependencies to other tasks. Dependencies on bi-directional objects (e.g. Mutexes) are not shown.

The classification of objects into directional objects (ellipses) and bi-directional objects (hexagons) are based partially on the static type of the object, partially on the service calls found referencing the object. This since semaphores can be used for both purposes, as a directional signal (a form of communication), and as a synchronization lock, i.e., like a Mutex. A object is treated as a synchronization object (hexagon) if there are actors that both increment and decrement the object state (e.g., do both a "LockMutex" and "ReleaseMutex"). This means that a semaphore can show up as a hexagon (if one actor both signals and waits for it) while a mutex in rare cases might show up as an ellipse, if only one type of operation ("LockMutex" or "ReleaseMutex") is recorded on the particular object.

Applying filters

Sometimes it's useful to filter out specific tasks or objects, such as if you have a debug or log writer task that many other tasks send data to. By default, all actors and objects that do not perform any communication are hidden, but you can adjust these settings using View -> Select Objects.... You can also right-click a node to hide it.

When right-clicking a node, you'll also be presented with options to show only connected nodes, in one, two or unlimited steps. This shows only actors and objects that affect or are affected by the selected actor or object via directed communication (undirected communication such as through mutexes are not followed even though the objects will be displayed).

The Show All Connected and the Show All Connected Only options will show the same nodes (actors/objects) but might show different sets of edges (lines). The difference is that the former does not hide communication between those nodes even if it's unrelated to the selected node. For example, if you have the communication chains taskA -> queueB -> taskB -> outputQueue and taskA -> outputQueue and you show nodes connected to taskB, Show All Connected Only (2 steps) would show only the first chain while Show All Connected (2 steps) would also show the second chain.

Context Switch Intensity

The Context Switch Intensity graph shows the amount of context switches over time. For each time interval, a bar is drawn for each actor beginning or resuming execution at least once in that interval.

The height of each bar, or bar section, shows the number of context switches within the given interval.

CPU Load Graph

The CPU Load Graph displays CPU usage over time, per actor and in total. By default, it shows all actors except the idle task. The analysis works by dividing the trace into a number of intervals, the default is 100 intervals.

The CPU usage for an actor in an interval is the amount of CPU time used by the actor within this interval, divided by the length of the interval. For each interval, all actors executing in that interval will be drawn as rectangles stacked on top of each other. The height of each actor's rectangle represents the CPU usage for that actor in that time interval and the combined height is the total CPU usage for that interval.

To customize the view, use the Select Actor(s) menu. There you can select which actors you wish to include in the view. If the graph is "noisy" (due to short intervals), you can reduce the number of intervals through the Resolution menu. If you wish a more detailed graph, you can increase the number of intervals by selecting a higher resolution. If you wish to focus on a specific area, you can click and drag to select an interval and use the Zoom menu or right click to zoom in on it. You can also use the Zoom or right click menu to show the selection or current view in the trace view or in all open views.

Clicking an actor in the graph will display information about that actor in the clicked interval and double clicking an actor will center the trace view on that interval. A gray outlined rectangle shows the interval of the current trace view. This rectangle may be very narrow and appear as a line if the trace view is small.

Event Intensity

The Event Intensity graph displays the number of events per event type, during the selected interval.

By default, the interval is divided into 50 time slices. The number of slices can be changed via the Resolution or Time Resolution menus.

Event Log

The Event Log displays the trace as a textual event listing, with powerful filtering tools. The view also supports exporting the trace as text file.

Clicking on any entry will highlight the corresponding event in the Vertical Trace View.

Filters

The text box above the event log functions as a quick text-based filter. Type any text and click Apply, and only entries containing that text will be displayed. To revert to displaying all entries, delete the search string and click Apply again.

The next four buttons - User Events, Service, Info Events and Raw Events - toggles the visibility of their respective class of events.

Clicking the Advanced button opens a panel with even more filtering options:

By Content
In the upper part of the panel you have the line content filters. You can choose to include only entries matching one or more regex patterns and/or excluding any entry matching one or more regex patterns. Both text boxes supports multiple patterns by placing one pattern on each line.

By Timestamp
By using the Exclude Events Before/After Timestamp filters, you can display events within a specific interval only.

By Event Type
In the bottom of the panel you have the Sources tree view. Here you can select which types of events you want to include as well as which individual channels you want to include for user events.

Find

Using the Find menu item, you can quickly locate a particular event.

  • Find: Opens the Find dialog. This lets you find an event or log message by string contents.
  • Find Next: If a search pattern has been entered in the Find dialog, the next match will be shown. Otherwise the Find dialog will open.
  • Goto Timestamp: Opens the Goto Timestamp dialog. This lets you find an event by timestamp.

Formatting

Using the Formatting menu item, you can configure the view.

  • Show Timestamps: Toggles the display of event timestamps.
  • Color Events By Type: Toggles the coloring of line backgrounds based on event type.

Export

Using the Events -> Export menu item, you can export the trace as a text file. This can be used to compare traces (using a plain diff/merge tool), e.g., for debugging (compare the event order in two traces with different behavior) and for regression testing (Does v1.2 behave the same as v1.1? If not, what differs?). All formatting and filtering used in the Event Log view is applied also in the Export function. This can be very powerful when comparing traces, as you can exclude irrelevant events and also the timestamps, e.g., if you wish to compare traces with small differences in timing.

I/O Intensity

The I/O Intensity view shows the amount of data sent or received on a particular I/O Channel object, per time interval. An I/O Channel is a traced object correponding to a system-level input or output. For instance, if using the Keil TCP stack, all the TCP sockets are recognized as I/O channels.

A histogram is displayed over the timeline (X axis), with a fixed number of bars each representing a fraction of the current view port. The height (Y axis) of the bars shows the total number of bytes sent or received in each time interval. Double-clicking on any of the bars in the I/O Intensity view will show the correponding time interval in the Trace View (and also in other views associated to the "Detailed" view port).

The display depends on two filters, as well as a Resolution setting. The "Send/Receive" filter in found the window menu, and in the right-side panel you can select which I/O Channel objects to include.

The resolution (i.e. number of bars) can be set in the menu. For instance, if selecting Resolution "High (100)", and the zoom level is 1 second, it will be divided into 100 intervals of 10 ms each.

I/O Plot

The I/O Plot displays the amount of data sent or received in "I/O Channel" events. An I/O Channel is a traced object correponding to a system-level input or output. For instance, if using the Keil TCP stack, all the TCP sockets are recognized as I/O channels.

Each data point represents an I/O Channel Event, where the X axis shows the time of the event and the Y axis shows the amount of data sent or received, in bytes. Double-clicking on the data points shows the correponding event in the trace view.

The display depends on two filters, the "Send/Receive/Combined" filter setting in found the window menu, and in the right-side panel you can select which I/O Channel objects to include. In using the "Combined" option, both Send and Receive events are plotted. Send events are then shown as positive values on the Y-axis and Receive events as negative values on the Y-axis.

Interval Coverage Graph

The Interval Coverage Graph displays the percentage of time covered by intervals in each channel in a set. Depending on the nature of the channels in the set, the value may be higher than 100%.

  • For a state machine, this view will show the amount of time spent in each state. In this case, the total should always be 100%.
  • If used with the Actor Fragments/(All) interval set, this will display CPU load across all cores. In this case, the total will add up to (number of cores) * 100%.
  • If used with the Actor Instances/(All) interval set, this will show some form of demand for processing time.

By default, the interval is divided into 50 time slices. The number of slices can be changed via the Resolution or Time Resolution menus.

Memory Heap Utilization

This view visualizes the heaps in the current trace.

You can show or hide individual heaps by clicking on them in the legend field to the right. If you click on a marker in the graph you can see information about that event in the information panel. Double-clicking will focus the main view on that event.

Message Receive Time

This plot shows the message receive time, i.e., the time from a queue is put in a message queue, until it is received. This way, you can see if messages to a task are delayed.

Object History

The Object History view displays all service calls for a specific object, or memory allocations (malloc/free) on a Heap object. This view is easiets to open by double-clicking on an event label, e.g., in the Vertical Trace View.

The Object History is displayed as a list, where each line corresponds to an event - the actor making the call, the type of event and the status of the object.

For queue objects, the current length of the queue is shown in the right column, with sequence numbers on the individual messages (the rectangles). The color of a message indicates the actor that sent the message. If selecting a successful send or receive event, it is possible to follow the message to the receiver or sender by using the buttons in the tool panel on the right, "Goto sending event" and "Goto receiving event". This allows you to follow the messages sent between individual task instances, e.g. to find the location where a queue message with incorrect data was sent.

The event list can be filtered to only display events of a certain service or from a certain task, using the two Filter menus. Clicking an event will display details about it in the panel to the right, which also features navigation buttons. Double-clicking an event will highlight it in the trace view.

When viewing heap events, such as "malloc" and "free", it is also possible to filter out all the allocations that have been freed, leaving only the remaining allocation. This can be used to find any memory leaks. See also Memory Heap Utilization.

Object Utilization

This view visualizes the state of objects over time, such as the number of messages in a message queue. It can be used to identify situations where the system has trouble processing all input within a reasonable time.

You can filter what actors to visualize by clicking on them in the legend field. If you click on a marker in the graph you can see information about that event in the information panel. Double-clicking will focus the main view on that event.

OS2 Event Log

The CMSIS-OS2 Event Log can display raw events received from Keil µVision.

Note
The CMSIS-OS2 Event Log does not support live mode, but can be used after a CMSIS-OS2 trace is loaded.

The Raw Event Log shows the events in a list, ordered by when the event was received, with one line per event. By default, all events are shown. You may however use filters and either highlight the matching events (Highlight items) or hide any non-matching events (Hide items). The filtering is only in the local view, it doesn't affect the data provided for the other Percepio Tracealyzer visualizations.

Filtering can be done in two ways, by Level (All Operations, API calls, Errors, ...) and/or by Text Filter (free text search, case insensitive) on the columns Component, Event Property and Value. If both kinds of filters are set, Level and Text Filter, the events need to match both filters to be included.

The options Highlight items and Hide items decides what to do with the matching events. If using Highlight items, the Next button is enabled which allows for stepping to the next matching event. The Hide items option can be used to hide all unrelated events. This can be used if only looking for a particular event, e.g. a specific error logged as a User Event.

Besides filtering, the View menu provide the options Highlight Overflows and Highlight Incomplete. Overflow indicates that events are lost, in case more events are produced than the Event Recorder is able to transfer. Learn more about overflows in the Recording Traces for RTX5 section. Incomplete events are ignored when the trace is loaded into the main Percepio Tracealyzer application, but are still shown in the Raw Event Log.

When running as a live view, the user can set the Event Log to not update on incoming events. This will make it a little easier to set up a proper filter, although that could be done before the recording starts. It will also show a drop-down with the current SCVD files.

To know how much time has passed between two events, select one of them and right-click to get the context menu and pick Set Time Reference. When a reference time is set, selecting any item will show how far before or after the reference time it is. You may then select Reset Time Reference to restore the normal view.

You may export the events to a file using File > Export. Select a filename and click Save to save the file and open it in the default text editor. All events are exported, regardless of the filter.

It is also possible to open the Raw Event Log from an existing trace file. From the main menu in Percepio Tracealyzer, select View > Raw Event Log.

Priority Changes

In case a task changes scheduling priority, it is displayed in this horizontal view. The Y-axis shows the new priority level.

Service Call Block Time

The Service Call Block Time graph displays the kernel blocking times of service calls, i.e., the time between entry and return of blocking calls.

Each data point represents a specific service call, where the x-position indicates the point in time and the y-position the blocking time. Clicking a data point (a service call) will highlight it in the trace view. This can be used to identify unintentional blocking, e.g. on a Mutex, which could be a cause to unusually high response times of tasks.

Note
If accessed from the View menu of the main window, this view will plot all calls on any object. You can bring up the view for a single object by right-clicking on a service call in the trace view and selecting Blocking Time Graph from the [Object Name] submenu.

Service Call Intensity

The Service Call Intensity graphs displays the number of Service Calls over time. This allows you to find hot spots with many service calls.

The individual services are color coded using a separate color scheme, shown in the right-side legend. You can toggle the visibility of services in this view by clicking on the labels in the legend.

State Machine Graph

This view displays a directed graph showing the state transitions in the trace as defined by a state machine. In the screenshot below, the state transitions have been logged in the user event channel "SystemState". See Intervals and State Machines introduction for further information on state machines and the related concept of intervals.

Any kind of state information can be displayed like this, assuming a state machine has been defined that tells Tracealyzer how to interpret the events into state transitions. See Intervals and State Machines view for further information on how to define state machines. Defining a state machine also generated intervals between state transisions that can be displayed in timeline views.

Tracealyzer also has pre-defined awareness of some states, such as task scheduling state. In the Intervals and State Machines view, select Add Predefined to see the available data sets. For instance, if using TCP stack supported by Tracealyzer, you can add each TCP socket as a state machine and also display the socket states as intervals on the timeline.

Trace View

This is the main view of Percepio Tracealyzer, showing all recorded events on a vertical timeline going downwards, or a horizontal timeline going right.

First some terminology. By actor we mean an execution context - a task or ISR. The colored rectangles (fragments) in the "CPU0" field represent uninterrupted execution of an actor, starting and ending with a context-switch.

Each actor has a unique color, based on its scheduling priority. The same color is used to represent the actor in all Tracealyzer views. 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.

Event Type Priority

When using a zoom setting that will not show all events, the Trace View (Events field) will try to hid events depending on the Event Type priority. By default this option is turned off, making sure events are not hidden without the operator knowing about it.
See Events for information on the sections.

To enable this and to change the priority, go to Event Priority Settings and re-order the types.

Fields

Each section in the Trace View is called a Field. The different Fields are separated by thick lines. The field names are shown in the header, i.e. in the top part of the trace view, when using the vertical orientation. Fields can be configured or hidden by right-clicking the header, or by clicking on the "gear" icon ().

There are three main field types, showing different kinds of information:

  • Scheduling field: Labeled "CPU0" for single-core systems. Shows the execution of actors, as solid rectangles (i.e. fragments). On multi-core systems you will also have "CPU1", "CPU2", etc.
  • Intervals field: Displays intervals and states. Such fields are named after the displayed data set.
  • Metrics field: Shows metrics embedded next to all other trace fields.
  • Events field: Shows event labels for e.g. kernel API calls and user events. This is always named "Events Field". The field will show all events from fields to its left, making it easy to see different events at the same time.

Moreover, there is always an "Actor Names" field available, although not always visible. To see it, click View -> Show Actor Names. There you also find an option to toggle the display of all Event fields, View -> Show Events.

To add a new Field, click View -> Add Field and select one from the list.
It is also possible to configure and rearrange the fields, using View -> Setup Fields.
All fields have configuration available which can be accessed using the gear icon in its header (at the top or to the left) of the field, or by right-clicking on header.

Note that Events field only displays events originating from fields on its left side. So, if adding additional fields, or rearranging the fields, note that the make sure that each Scheduling field has an Events field on its right side. Multiple Scheduling fields may however share a common Events field.

Horizontal Mode

You may change the orientation of the trace view between vertial and horizontal in the local View menu of the trace window. Both modes offer the same features, but we recommend vertical orientation to make it easier to read text labels.

In horizontal mode, you may close the Event field and instead add Interval fields to display application states and kernel objects, such as message queues. An example is shown in the above screenshot. To do this, select View -> Add Field -> Interval field and then click the "Add Interval..." button. You then get a list of all available data sets, including predefined data sets for e.g. message queues.

Trace View Options

For multi core systems actors can, depending on scheduling rules, run on different cores (even within the same instance). In traces where this happens, it is not always clear how to show that an actor is running on a core that is not in the current field.
The option View -> Show Actor Fragments on other Cores can select if actor fragments running on cores not included by current filter are drawn with gray lines, or not drawn at all.
The image on the left shows with this option enabled, the one on the right with it disabled.

Scheduling Field Options

This field can be customized to only show a subset of the available actors by using Select Actors or CPUs (for multi core traces) by Select CPUs
Note! Applying actor selection will work together with current filter; if an actor is not in the current filter it will not be shown in the Scheduling Field either.

Normal sort order for the field is highest priority to the right for vertical mode, or bottom for horizontal mode. This can be changed by checking Reverse Draw Order.

For traces with many actors it is possible to activate Hide Inactive Actors. This will only show "lanes" for actors that have an active instance in view, otherwise they will be hidden.
Each hidden actor will be "shrunk" to a slim line, making it easy to get an indication on if there are many or few actors hidden.
Note! Each field will remember the setting for hiding, as long as Percepio Tracealyzer is set to remember layout. If the default value is to be changed, use Settings -> Project Settings.

Metrics Field Options

This field shows metrics, like CPU load, or Actor Execution time. When the field is created a Select Metrics dialog will be shown to show the available metrics. The same dialog can be opened by clicking Select Metrics. Some metrics has different channels available, and when this is available it will be possible to switch the channel directly from the menu without having to open the dialog.

Event Field Options

This field can be set to show Event Hotspots, which will indicate where the events are located when zooming out as gray squares at the edge of the Event Field. This will help identifying if there are certain times when more events than usual is happening.

Intervals Field Options

The interval field can be changed to show a different interval than it was originally created with, see Interval for more information.

View Presets

The execution of tasks and interrupts can be visualized using different visualization presets, which you can quickly switch between to get best clarity in each situation.
Each preset will set up the fields needed to show the type of information required.
The presets are:
Gantt Preset Shows one column per task and interrupt. This is best for spotting execution patterns, rare tasks or interrupts.
(Default shortcut key "G")
Merged Preset Shows all tasks and interrupts in a single column, with sideways 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 preemption hot-spots. This preset uses calculated data it is not available for live tracing.
(Default shortcut key "M")
Split Preset 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. This preset uses calculated data it is not available for live tracing.
(Default shortcut key "S")
Flat Preset Shows all tasks and interrupts in one single column (per core).
(Default shortcut key "F")
Intervals Preset Only show intervals, see Intervals for more information. This preset is only available when there are intervals active.

It is also possible to set up custom presets. Under the View -> View Presets, either select Save Preset or Manage Presets.

Events

The main view also show event labels of different types, notices, 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 service calls.
  • Green labels - successful return of blocking service calls.
  • White labels - service calls that completed without blocking.
  • Orange labels - service calls that returned due to a timeout.
  • Yellow labels - user events.
  • Light blue labels - notices, such as "Actor Ready" - when tasks become ready to execute.
  • Blue-green labels - asynchronous events, any events from asynchronous data sources.

Note that 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 service calls. The red, green and orange labels are used only for blocking on shared resources, e.g., message queues, semaphores and mutexes, where the blocking may not be intentional and thus 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" and "Next" buttons in Selection Details 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 opens the Instance Details view, which gives lots of information focused around that actor. Double-clicking on a system call opens a focused view showing a list of all related events, e.g., the Object History View. This shows all service calls on a selected object, i.e., a message queue, semaphore or mutex. Double-clicking on a user event shows the Event Log, with filters applied.

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 using the button in Selection Details pressing F8, or by using the context menu option "Find Entry/Exit of Blocking 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 the text X events not shown. If this happens, zoom in or use the visibility filter to reduce the number of events. If the number of events for a selected actor is not too many, they will be shown even if the rest of the events are hidden.

Note
If a large number of events are hidden, it is possible to see where they are located with the event hotspots; gray rectangles showing where the events are located, see Event Field.

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.
The first event will still be selected, making it possible to measure to different events and see the result.

Note
When searching for a particular location, it is 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.

User Events Signal Plot

This view allows for plotting data from user events arguments. If a user event have multiple data arguments, only the first is plotted. Each user event channel is plotted as a separate curve. You can change what user event channels that are displayed in the Filter.

For more information about user events, see User Events section.

View Port Overview

This tool shows the view ports that are used by any view. Multiple views can share the same view port, see User Interface section for more details.

Both the view ports and the view selection is visible.

Tools

Actor Overview

The Actor Overview displays a list of instances of an actor.

All Views

The All Views window shows an overview of all views and features in Tracealyzer. Type something in the quick filter box to only show views that match your search term.

Select "Show View" or double-click the thumbnail picture to launch the selected view. Click "Read More" to open the User Manual page about this view.

API Connection Monitor

The API Connection Monitor shows the current status of connections to the Tracealyzer API, which allow other tools to communicate with Tracealyzer.
This is for instance used by the "Percepio Trace Exporter" plugin for Eclipse (found in the Eclipse marketplace) and for Atmel Studio 7 (found in the Microchip Gallery).

When the monitor is running, a status icon will be shown at the bottom right corner of the main Percepio Tracealyzer window. The color is green if connected, yellow if trying to connect, and red if there are problems with the connection.

If using our Eclipse or Atmel Studio plugin, it is possible to request a snapshot from the target directly, provided it is possible to do inside Eclipse or Atmel Studio.

The Tracealyzer API also allows for tool partners to integrate with Tracealyzer. Details can be provided on request.

Application Warnings

This view shows any warnings from the Tracealyzer application during the current session. This shows if the recorder library has reported a configuration problem, or other issues that may occur.

Bookmark Organizer

Bookmarks are saved locations in a trace that are of particular interest.

Bookmarks are saved with the trace and restored when you reload the trace. Because they are saved in an internal directory it is recommended to use the bookmark organizer to export and import the bookmarks.

Export Actor Data

The Actor data exporter will Export all information from the selected actors to a text file. This allows you to either view the data offline or import it to a different tool.

Filter

Filtering in Percepio Tracealyzer is done in the Filter view, which shows application objects organized in different groups. Each group lists all objects of that type that can be filtered on.

Filterable objects are sometimes also organized in a hierarchy, giving you the option to easily enable or disable a whole group of objects.

Since filtering is potentially set per view, the filter dialog will show the attached view that the filter affects. All views belonging to the same synch group will be affected when changing the filter.

If the filter view is wide enough, the group selection will be shown as a list instead of a combo box.

Filters will by default be saved between Tracealyzer sessions. This can be disabled in the window menu by toggling View > Auto Load Filter.
It is also possible to save or load explicit filters using View > Save Filter from Current View/Load Filter to Current View.

Finder

The Finder window lets you quickly find actor instances, service calls and user events, using various filters. It also lets you jump to a particular point in time.

Two Finder Tools

Tracealyzer includes two "Finder" tools, the "Quick Finder" and the more advanced "Finder". They allow for searching for just about anything in Tracealyzer, including events, actors, views, and even help pages. Events are matched with respect to their displayed text, including user event channel names etc.

When combining multiple terms in a search query, the result will include hits on any search term, but the best matching entries will be shown first.

Quick Finder

The Quick Finder is a small search bar which will open inside the current view. It performs fast searches but only shows a limited amount of hits. Use the arrow keys and Enter, or the mouse, to select something from the list of hits, or refine the search keywords. When something is selected the default behavior is to close the Quick Finder. Cancel the search with the close button, or by pressing Escape.

The best way to open the Quick Finder is via the keyboard shortcut (default is Ctrl + F), but the Find menu can also be used. There is a special case of the Quick Finder that only finds timestamps in the current trace, with the default keyboard shortcut of Ctrl + G. These keyboard shortcuts can be changed using the Keyboard Mapping settings.

To keep the Quick Finder open when something is selected, click the small Pin button on its top right corner. The small D (for Detach) button on top will open the same search in the full Finder.

Full Finder

The full Finder view can be opened from the Find menu, or using the key shortcut Ctrl + Shift + F (default mapping). The main difference compared to the Quick Finder is that it will keep finding all items until done, or until you stop it. This makes it useful for larger searches, i.e. that may result in many matching events.

Advanced Find using Tracealyzer Query Language (TQL)

With the Tracealyzer Query Language (TQL) it is possible to quickly apply advanced filters on the items to find. Two parts will affect the outcome, any prefix keywords and the where clause.

If the first word in the search string matches a keyword, like actor or time, items from the corresponding group will be ranked higher in the find result.

To apply advanced filters, start by adding a where clause at the end. The where clause will not actually apply until it is complete, so while typing the find result may even become empty. You may add several filters if you wish to restrict the search further, using and or or.

If both keywords and where is applied, only results matching the keywords will appear.

Examples are shown later in this section.

Actor Instances

Finding actor instances can be prioritized by adding actor or instance as a keyword.

If an actor is selected in the result, press the TAB key to see min/max values for the current actor, like execution time and fragmentation. This will help when setting an advanced filter.

Supported keywords for where clause:

  • start - the start time of the instance
  • ready - the ready time of the instance
  • end - the end time of the instance
  • timestamp - same as start
  • instance - the instance number, starting from 1
  • index - same as instance
  • execution - the execution time of the instance
  • response - the response time of the instance
  • wait - the wait time of the instance
  • fragments - the number of fragments of an instance
  • period - the period of the instance (time from start of previous instance to start of this instance)
    Not available for live traces
  • separation - the separation of the instance (time from end of previous instance to start of this instance)
    Not available for live traces
You don't need to use the full name of keywords after where, as Tracealyzer then guesses which one you mean. For instance, entering "... where exec > 1000" works will be interpreted as "... where execution > 1000".

Keywords can be compared with decimal values, and most can also be compared to min and max.

Example where clauses for actor instances:

  • where exec is max
  • where frag > 2 and wait < 10000

Events

Finding events can be prioritized by adding event as a keyword.

The whole event text is used for matching, including displayed parameter values. Events will not be included in the search until terms with at least three characters are included.

Supported keywords for where clause:

  • time - the time of the event, in current time mode

Example where clauses for events:

  • where time < 100000
  • where time between 200000 and 300000

Timestamps and Intervals

Finding timestamps or intervals can be prioritized by adding time as a keyword.

If one time is entered, it will be used as a timestamp. If two times are entered, it will be used as an interval. Any more times after this will be used as timestamps.

Timestamps and intervals will ignore where clauses.

Opening Views

Finding views to open can be prioritized by adding view or open as a keyword.

The view will be matched by the name, but also additional keywords that describes what the view shows. Results will not only allow new views to be opened, but also currently active views that match the search terms.

Opening views will ignore where clauses.

User Manual

Finding views to open can be prioritized by adding help as a keyword.

All pages from the User Manual can be found from the Finder.
It will however not search through the whole text of the page, but do a quick match on keywords, similar to how views are matched.
To perform free text searches in the whole User Manual, simply open it (default shortcut is F1) and use the built in find.

User Manual will ignore where clauses.

User manual searches is only included if the built in User Manual is available.

Keywords

In addition to the contents of the current trace, all views, and user manual, there are a few useful keywords to perform certain actions:

  • start - scroll to the start of the trace
  • top - same as start
  • left - same as start
  • end - scroll to the end of the trace
  • bottom - same as end
  • right - same as end
  • all - zoom out to show the whole trace
  • full - same as all
  • zoom in - same as using the zoom in button
  • zoom out - same as using the zoom in button
  • zoom - same as zoom in

Keywords will ignore where clauses.

Examples

  • time 200000
    Centers the current View Port on timestamp 200000.
  • actor MyTask where exec is max
    Instances of actor "MyTask" with highest observed execution time.
  • actor MyTask where resp > 2000
    Instances of actor "MyTask" with response times above 2000 time units (normally µs).
  • actor MyTask where frag > 2 and wait < 10000
    Instances of actor "MyTask" with more than 2 fragments and wait time below 10000.
  • event MyEvent where time < 1000000
    Events containing the word "MyEvent" occuring before timestamp 1000000
  • event MyEvent where time between 100000 and 200000
    Events containing the word "MyEvent" occurring after timestamp 100000 and before timestamp 200000.
  • end
    Scrolls to the end of the trace.
  • all
    Zooms out to show the whole trace.

Instance Details

Whenever an instance is double-clicked, its details will be shown.

The details includes the currently selected instance. Besides the details, these views are also available:

  • Actor Instances shows all available instances of the selected task. The current selection is highlighted with light blue background, and if different the selection of the main window as well with a teal background.
  • Local Trace shows the current trace view with the selected instance focused, see Trace View for more information.
  • Communication Flow shows any communication that this particular instance performs, see Communication Flow for more information.

Interval Details

Whenever an interval or state machine is double-clicked, its details will be shown.

The details includes the currently selected interval. Besides the details, these views are also available:

  • Local Trace shows the current trace view with the selected instance focused, see Trace View for more information.
  • Interval Instances shows all available instances of the interval. The current selection is highlighted with light blue background, and if different the selection of the main window as well with a teal background.
  • State Machine will show a state machine graph of the current machine, only available of the interval describes a state machine.
  • Transitions will show all transitions, if the interval describes a state machine. It can also be set to filter for specific From or To states, either with Or logic (match either) or And logic (match both).

If the interval describes a state machine, additional buttons "Prev State" and "Next State" will be available in the Details section, which will step to the previous/next transition of any channel, while the normal Previous and Next buttons will step to the previous/next interval instance of the same channel.

Intervals and State Machines

This view allows for defining Intervals and State Machines, which allows for user-defined visualization of the recorded events in several views.

The view also lists all Intervals and States machines that have been activated. You can right-click these entries for the following options:

  • Statistics - Shows a statistics report focusing on the durations.
  • Show Timeline - Shows the states/intervals over time, much like a logic analyzer view.
  • Show Plot - Plots the durations of the states/intervals.
  • Create Inverted - Creates a new inverted data set. If the original data set is intervals from Event A to Event B, the inverted data set is the intervals from Event B to the next Event A.
  • Compute Overlap - Creates a new data set that is the intersection of two data sets

Predefined

This opens the Predefined States and Intervals, where you can select from predefined defitions of known states and intervals in the trace. You may activate these data sets to see additional information about objects that Tracealyzer is aware of. For instance, if you are using a TCP stack supported by Tracealyzer, you can include TCP socket states this way.

Custom State Machine

This lets you define a custom state machine. There are two ways:

The simple option assumes the state transitions are logged as user events, on a user event channel specific for this purpose. All messages on this user event channel are assumed to be state transitions.

The advanced option lets you define a state machine based on any events that match a regular expression, including both user events and kernel events.

Custom Intervals

Select this option to open an editor for custom interval definitions. Begin with specifying a name for the interval, and then provide two rules for the beginning and end of the interval. The first interval will begin at the first event matching Interval Start, and finish at the first following event matching Interval End.

To check if the definition will actually generate any intervals, use the Test button. It might take a little while to do for a long trace, because it will read the whole trace until matches are found, or the trace ends. When the definition is completed, use Save to save and apply to the loaded trace. This will show the interval in any open Vertical Trace view.

Keyboard Mapping

All keyboard shortcuts can be changed for the current user. It is also possible to assign shortcuts to your favorite view.

Select a command to add or edit its shortcut. Clicking Restore restores the default shortcut for the command.

Navigation Bar

The Navigation Bar is by default docked to the left, and shows a list of available views.

The list is normally ordered based on how much time is spent with each view open, thus keeping the most used views easily accessible. Note the All Views option, that gives an overview of all views and features in Tracealyzer.

To configure what is displayed on the Navigation Bar, see the Navigation Bar Settings (found under File -> Settings -> Navigation Bar Settings).

Object List

The Object list shows all Objects.

The list can be sorted on either column by clicking the column headers.

Double-clicking an entry in the list opens the Object History view for that object.

Performed Events

When anything is selected in any view, this view shows any associated events.

Selection Details

The Selection Details view displays information about the currently selected Actor in the main view. The info shown include among others timing, fragmentation and any events that have occurred. Property values for the selected instance, as well as actor average, minimum and maximum values. Double-clicking on a maximum or minimum value scrolls the main view to show the corresponding instance in the trace.

Trace Overview

The Trace Overview shows details of the recorded trace as well as any warnings produced by the recorder.

User Manual

Pressing F1 will open the context sensitive help.
If any view is active it will show the help page for that view.
If no view is active the User Manual is shown.

Settings

Overview

All settings for connections and user interface can be found under Settings.

To make it easier to find settings, a Find text box is in on top of the settings tree.

Projects

All settings, with the exception of those found under Global Settings, are specific to a project. These combine settings, like target connection information (streaming/snapshot settings) and the recently used traces, making it easier to switch.

When starting Percepio Tracealyzer the first time the Default Project is selected, to allow new users the easiest way to start using it.
If you are developing for multiple targets, it is a good idea to set up different projects for each.
Uncheck Reopen last Project either from the checkbox at the bottom of the Welcome screen, or from Global Settings, to allow project switching on startup.

To switch between different projects, Percepio Tracealyzer has to be restarted. All currently available projects can be accessed by the File > Project menu, which allows simple switching.

Global Settings

These settings affect how Percepio Tracealyzer behaves. They are not tied to a particular project.

File associations can be modified here.

Project Settings

These settings, and all pages in the tree, apply to the currently active project. Changes take effect when you click OK or Apply.

Percepio Tracealyzer usually saves trace data in your local Documents folder. If you want to save data somewhere else, e.g. if you plan to record a very long trace and need extra disk space, you can specify another folder as Trace Directory. Note that if the current directory is the default one, the Trace Directory field will be empty when opening the settings.

For trace previews there are two threshold values.

  • The lower limit (ask if exceeding) sets when preview mode is suggested.
  • The higher limit (always use if exceeding) sets when preview mode is automatically used.

To always use preview for all traces, set the always limit to 1, or to completely disable preview, set suggest limit to a very high value.

Note
The limit is not the raw trace size (i.e. size on disk), but the estimated RAM memory consumption; the difference is depending on the used trace format.

API Connection Monitor Settings

Settings for the Tracealyzer API, which allows for other tools to interact with Tracealyzer.

Check "Start API Connection on Startup" to start the API connection directly when starting Tracealyzer.

Use the Host and Port sections to select what host and port to use. Leave host blank to use localhost.

Tracealyzer support both XML and JSON formats, select the appropriate one.

Note
Normally when the API is used Tracealyzer will be launched by the other application. When it is, the Host, Port, and Type settings are overridden.

Check "Reconnect if Disconnected" to have the API try to reconnect if the other end disconnects.

Check "Ask on Trace Received" to always get a message box if a new trace is sent over the API.

ARM Keil Connection Settings

These are the settings used for communicating with ARM Keil µVision

The default setup is to connect to an existing µVision instance, but Percepio Tracealyzer can also be configured to start a new Keil µVision instance for the trace session. Simply change the Connect Mode setting to Start new µVision instance and make sure the Keil µVision Path is correct (default is C:\Keil_v5\UV4\UV4.exe).

If a different port is used in Keil µVision, make sure the matching port is used in Percepio Tracealyzer.

If logging of the UV SOCK communication is needed, set up the Log Path. Default is to overwrite the log file for each instance, check Log Path Append to append to the log instead.

Streaming from Keil µVision will enter debug mode automatically if needed. It is possible to decide if debug mode should be exited when the streaming stops.

Here is more help to set up Keil µVision Recording.

Automatic Event Filtering Settings

This setting controls which event labels that are displayed in an Event Field, in case the window is too small to display all events enabled in the main Filter. By enabling the automatic event filtering, you can often avoid the "all or nothing" display in Event Fields when scrolling or zooming. This way, you can still see important evens (e.g. User Events) even if there are a lots of less important events in the current view. Note that the Automatic Event Filtering is independent of the main Filter settings.

Note
Automatic Event Filtering is disabled by default.

When the Trace View is zoomed out too much to show all events in the view, the events with lower priority will be hidden first, see the Trace View for more details.

To change the priority order, drag and drop the event types to the desired priority level (highest at the top, lowest at the bottom).

Note
In Mono there is a problem with the drag and drop support, so instead buttons are added to move the types to higher or lower level.

Note
Changes will not be saved until Apply or OK is clicked.

To reset to default display priorities, click the Reset to Default button, and then apply.

Docking Settings

The docking settings can be set to be suit the current monitor setup quickly, or set to custom behavior.

To understand the difference between different variants, see the section on User Interface.

Layout Mode

  • Default - In this mode, new docked views will open in up to four different tab groups before starting to add the views as tabs.
  • Tabbed - In this mode, new docked views will add to the main tab group.

Floating Mode

  • Default - In this mode, new floating views will be shown as separate floating views.
  • Docked - In this mode, new floating views will instead be docked.

Navigation Bar Settings

The Navigation Bar Settings will allow you to customize which icons will show up in the navigation bar, and also the sort order.

Sort Order
  • Sort by activated time - In this mode the sort order is the time spent with each view open.
  • Sort by number of activations - In this mode the sort order is the number of times a views has been opened, including times it is opened by setting/changing layout.
  • Custom order - In this mode it is possible to change the order of the icons, where the first ones are on top.

Note
Even if using Custom order, views that are part of a group will be shown in the extended menu.

Performance Settings

Here are all settings that can affect performance in a negative way.

Many trace formats support raw events, but they are normally not included when loading a trace. If raw events are wanted, check Include Raw Events in Trace check box.

Note
Loading raw events will normally result in double the number of events in the trace, which will both affect the time it takes to load the trace and how much memory the trace will require.

Snapshot Settings

Settings for the Snapshot tool.

Select the snapshot engine to use. Apply (or OK) will automatically reflect this in the Snapshot tool.

View Settings

These settings are the default values for views.

Terminology

ActorAn execution context - a task, thread or an Interrupt Service Routine (ISR).
Actor InstanceAn execution of an actor. For interrupt service routines, this means from start to finish of the ISR handler. For tasks, this is application-dependent but typically means one iteration in the main loop. See Instance Finish Event. An Actor Instance consists of one or several fragments, depending on preemptions, blocking and interrupts.
Execution TimeThe amount of CPU time used by an Actor Instance, excluding preemptions.
Response TimeThe time from the start of an actor instance until it finishes.
FragmentA time interval when a specific actor executes uninterrupted. Fragments are visualized as colored rectangles in the scheduling trace. A fragment belongs to a specific Actor Instance.
FragmentationThe number of fragments within an Actor Instance. If an Actor Instance executes in full without preemptions, the fragmentation of the instance is 1.
Instance Finish EventA service call that is considered as the finish of a task instance, typically in the context of repeating tasks with a main loop. By default, Percepio Tracealyzer considers blocking "receive" calls (including waiting for semaphores and other events) as well as "delay" calls to be Instance Finish Events. Blocking on Mutex calls are however not considered as IFEs.
ISRInterrupt Service Routine, i.e., the handler of an interrupt.
ObjectAn object referenced in a traced event, such as a queue, semaphore, mutex or task.
ServiceTypically an API function provided by the kernel, often performing an operation on a object.
PeriodicityThe time between two consecutive instances of an actor, counted from the start of the previous actor instance to the start of the current actor instance.
SeparationThe time between two consecutive instances of an actor, counted from the end of the previous actor instance to the start of the current actor instance.
TaskA thread of execution. Percepio Tracealyzer generally refer to threads as "tasks".

Support and Licensing

For technical support, contact support@percepio.com.

To request a quote, contact your nearest distributor. If we are not represented in your region, or you have other licensing questions, please contact sales@percepio.com

Want some help getting started?
Get up and running fast with a free 45 minute consulting session with Niclas Lindblom, Senior FAE at Percepio. This is not a slideshow presentation – Niclas will assist you via video conference, hands-on, using your own project, tools, and hardware. Contact support@percepio.com to book a time!


Copyright Percepio AB 2019, all rights reserved.

Generated for Percepio Tracealyzer, version 4.3.5.12810