Master Tracealyzer with FreeRTOS

Getting Started with Tracealyzer on FreeRTOS

Integrate TraceRecorder, capture your first FreeRTOS trace, and analyze it in Tracealyzer.

Get Started Now



Step 1

Integrate TraceRecorder

Integrate TraceRecorder into your project, enabling detailed trace analysis.

Start Integration



Step 2

Configure Tracing

Necessary and common trace configurations to ensure accurate and efficient trace data capture.

Configure Now



Step 3

Capture Your First Trace

Capture your first trace and see how your FreeRTOS application executes.

Capture Trace

Prerequisites

Before you begin

Install Tracealyzer. If you haven’t done so, see detailed instructions here
Existing FreeRTOS application
FreeRTOS application builds and runs
Target/debug connection available

Step 1: Add TraceRecorder

Integrate TraceRecorder into Your Project

Add TraceRecorder

Add the TraceRecorder source files to your project and make sure they are compiled.
Add the TraceRecorder/include directory to your compiler’s include paths.

Configure TraceRecorder

Modify the FreeRTOSConfig.h file to enable tracing
1. configUSE_TRACE_FACILITY needs to be set to 1
2. #include "trcRecorder.h" needs to be added at the end of the file
In trcConfig.h set TRC_CFG_HARDWARE_PORT to the architecture used. For some hardware ports you need to #include the processor header file by replacing the row #error "Trace Recorder: Please include your processor's header file here and remove this line.". If the error line is removed and your project compiles, the header file isn’t needed. All available hardware ports can be found at the bottom of trcDefines.h.
TRC_CFG_FREERTOS_VERSION needs to be set in trcKernelPortConfig.h.

Start TraceRecorder

Enable tracing by adding a call to xTraceEnable(TRC_START);
Note: Some hardware ports require a specific initialization sequence. See the hardware-port documentation if your selected port uses the FreeRTOS tick as its timestamp source.

For complete TraceRecorder Integration details and advanced configuration, see the detailed TraceRecorder for FreeRTOS reference guide.

Note: If you are using FreeRTOS SMP or a multicore target, use the dedicated multicore setup guidance. TraceRecorder requires additional initialization and multicore configuration.

C

Step 2: Configure Tracing

Configure Tracing

Initial setup

You’ll begin by selecting a capture method that suits your needs, either Snapshot or Streaming. Each method offers unique benefits, so consider your requirements carefully before proceeding.

Snapshot: Store trace data in target RAM and retrieve it later by utilizing the RingBuffer stream port.
Streaming: Continuously transfer trace data to Tracealyzer using a stream port such as J-Link RTT, TCP/IP etc.

Recommended: Capture your first trace with Snapshot

Snapshot tracing is the simplest way to verify that TraceRecorder is working. It stores the latest trace data in target RAM using the RingBuffer stream port.

Need long-running or live traces?

Use Streaming instead.

Snapshot

Run → Halt → Save Snapshot → Open in Tracealyzer

Ensure all the files from RingBuffer streamport folder are copied into your project

Set the trace buffer size and select the ringbuffer mode in trcStreamPortConfig.h. This minimal configuration will allow you to capture essential trace data without overwhelming your system resources.

TRC_CFG_STREAM_PORT_BUFFER_SIZE decides the size of the trace buffer that is stored in RAM. A larger buffer stores more trace history but uses more RAM. Start with the default/recommended value for your platform and increase it if you need a longer trace.
TRC_CFG_STREAM_PORT_RINGBUFFER_MODE can be set to

- TRC_CFG_STREAM_PORT_RINGBUFFER_MODE_OVERWRITE_WHEN_FULL for continuously recording
- TRC_CFG_STREAM_PORT_RINGBUFFER_MODE_STOP_WHEN_FULL for stopping when the buffer is full

After your application has run, halt the target and store the RingBuffer content to your host. Instructions for how to achieve this in an easy manner may be found under “Capture Your First Trace” below.

Streaming

Run → Continously Capture in Tracealyzer → Stop

Streaming reduces the limitation imposed by the target’s RAM because trace data is continuously transferred to the host. The practical trace length and reliability still depend on the transport and its available bandwidth. To setup streaming you will:

Start by selecting a method for your data streaming

Streaming method Typical use

J-Link RTT Debug probe

TCP/IP Network-connected target

ITM ARM Cortex-M + debugger

Other stream ports See stream-port documentation
Copy the corresponding files of your selected stream port into your project
Ensure that your target streaming settings are matched in the Tracealyzer application

Streaming method	Typical use
J-Link RTT	Debug probe
TCP/IP	Network-connected target
ITM	ARM Cortex-M + debugger
Other stream ports	See stream-port documentation

For all the details of streaming configuration, see FreeRTOS Trace Streaming.

Note: TraceRecorder uses “Streaming Mode” as the default recorder configuration. This mode supports both snapshot and streaming capture depending on the selected stream port. The legacy Snapshot Mode is deprecated.

C

Step 3: Trace Capture

Capture Your First Trace

The capture procedure depends on your development environment. Select the method you use below.

Snapshot

Streaming

Opening the Trace

If you used Snapshot tracing, open the captured trace file in Tracealyzer. If you used Streaming, the trace is displayed in Tracealyzer as data arrives.

A successful trace should show recorded task execution, interrupts and other system events in the timeline.

If the trace is empty or doesn’t open correctly, see Troubleshooting.

Using Your Trace

Start by looking at:

Task scheduling — See when tasks execute, block and resume.
CPU usage — Identify tasks consuming significant CPU time.
Timing — Find long execution times and unexpected delays.
Interrupts — Understand how interrupts affect task execution.
User events — Correlate trace data with application-specific behavior and custom events/logs. All synchronized into one execution timeline.

To learn more about using Tracealyzer, see Tracealyzer Features and Capabilities.

Troubleshoot Your FreeRTOS Trace

Resolve common TraceRecorder setup and capture issues when using Tracealyzer.

Check the Setup Before Capturing Again

Start with a FreeRTOS application that builds and runs, a working target connection, and Tracealyzer installed on your host. Then follow the checks below for the symptom you see.

Build Fails After Adding TraceRecorder

Check that TraceRecorder/include and the selected stream-port files are in your project and that the recorder sources are compiled. Set configUSE_TRACE_FACILITY to 1 and add #include “trcRecorder.h” at the end of FreeRTOSConfig.h.

Hardware-Port or Version Error

Set TRC_CFG_HARDWARE_PORT for your target in trcConfig.h and TRC_CFG_FREERTOS_VERSION in trcKernelPortConfig.h. If your hardware port requires a processor header, include it where the port reports the missing-header error.

Trace File Is Empty

Confirm that your application calls xTraceEnable(TRC_START). For a RingBuffer snapshot, let the target run before halting it, then export the trace buffer and open the resulting file in Tracealyzer.

Snapshot Stops Too Soon

Check TRC_CFG_STREAM_PORT_BUFFER_SIZE in trcStreamPortConfig.h. Increase it if target RAM allows, or select TRC_CFG_STREAM_PORT_RINGBUFFER_MODE_OVERWRITE_WHEN_FULL to retain the most recent events instead of stopping when the buffer fills.

Streaming Data Does Not Arrive

Verify that the configured stream port matches your connection, such as J-Link RTT or TCP/IP, and that its transport is available to the Windows or Linux host. If events are lost during streaming, check the transport bandwidth and buffering. If necessary, reduce the trace event load or use a faster transport.

Enhance Your Tracing Skills

Unlock deeper insights by exploring advanced trace analysis techniques and optimize your FreeRTOS applications.

Explore Advanced Techniques