Master Tracealyzer with ThreadX
Getting Started with Tracealyzer on ThreadX
Integrate TraceRecorder, capture your first ThreadX trace, and analyze it in Tracealyzer.
Step 1
Integrate TraceRecorder
Integrate TraceRecorder into your project, enabling detailed trace analysis.
Step 2
Configure Tracing
Necessary and common trace configurations to ensure accurate and efficient trace data capture.
Step 3
Capture Your First Trace
Capture your first trace and see how your ThreadX application executes.
Prerequisites
Before you begin
- Install Tracealyzer. If you haven’t done so, see detailed instructions here
- Existing ThreadX application
- ThreadX application builds and runs
- Target/debug connection available
- Decide upon the ThreadX tracing solution:
- Percepio TraceRecorder (described in this guide)
- Modern Tracealyzer integration
- Kernel tracing
- Streaming/snapshot architecture
- ThreadX native tx_trace
- Legacy ThreadX tracing
- Kernel and middleware tracing
- Snapshot only tracing
- Percepio TraceRecorder (described in this guide)
Step 1: Add TraceRecorder
Integrate TraceRecorder into Your Project
__inside_$(notdir $(basename$(@)))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
#include"trcRecorder.h"at the end of tx_api.h- Enable
TX_ENABLE_EVENT_TRACEeither in tx_user.h (make sureTX_INCLUDE_USER_DERINE_FILEis defined), or by a compiler flag. - In trcConfig.h set
TRC_CFG_HARDWARE_PORTto the architecture used. For some hardware ports you need to#includethe 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. - In trcKernelPortConfig.h set
TRC_CFG_CPU_CLOCK_HZto the frequency used by the timer for time stamping in the hardware port. - Add a preprocessor definition:
__inside_$(notdir $(basename $(@))). This creates a preprocessor definition like__inside_myfilebased on the currently compiled .c file. - Add
-include trcCTI.hin the GCC build flags.
Start TraceRecorder
- Enable tracing by adding a call to
xTraceEnable(TRC_START);at the top of thetx_application_definefunction.
For complete TraceRecorder Integration details and advanced configuration, see the detailed TraceRecorder for ThreadX reference guide.
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_SIZEdecides 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_MODEcan be set to
-
TRC_CFG_STREAM_PORT_RINGBUFFER_MODE_OVERWRITE_WHEN_FULLfor continuously recordingTRC_CFG_STREAM_PORT_RINGBUFFER_MODE_STOP_WHEN_FULLfor 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 to match all target settings within the Tracealyzer application
For all the details of streaming configuration, see ThreadX 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.
Step 3: Trace Capture
Capture Your First Trace
The capture procedure depends on your development environment. Select the method you use below.
Snapshot
- VS Code
- STM32CubeIDE
- GDB or Eclipse
- Renesas e2 studiot
- IAR Embedded Workbench for Arm
- Lauterbach TRACE32
- Other Application Notes
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 ThreadX Trace
Resolve common TraceRecorder setup and capture issues when using Tracealyzer.
Check the Setup Before Capturing Again
Start with a ThreadX 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
Confirm that the TraceRecorder source files are included in the build and that the TraceRecorder include directory is on the compiler include path. Check that ThreadX event tracing is enabled with TX_ENABLE_EVENT_TRACE and that the required user configuration is active. Verify the hardware port and processor header settings in trcConfig.h.
Hardware-Port or Version Error
Check that TRC_CFG_HARDWARE_PORT matches your target architecture and that any required processor header is included.
Trace File Is Empty
Check that tracing is enabled with xTraceEnable(TRC_START) in tx_application_define and that ThreadX event tracing is active. For Snapshot capture, run the application before halting the target and saving the RingBuffer data. Confirm the RingBuffer stream port is configured and its files are included in your project. For Streaming, verify the selected stream port matches your connection and that the transport is running.
Snapshot Stops Too Soon
If your snapshot ends before the behavior you want to inspect, increase TRC_CFG_STREAM_PORT_BUFFER_SIZE to retain more trace history. Check available target RAM, then adjust the buffer size in trcStreamPortConfig.h and rebuild. With overwrite mode, the buffer keeps the most recent events; with stop-when-full mode, recording ends when it fills. Choose the mode that best fits your investigation.
Streaming Data Does Not Arrive
Check that TraceRecorder is enabled and that your selected stream port matches the target connection. Confirm the stream port files are included in your build, the transport is active, and Tracealyzer is listening on the correct interface. For J-Link RTT, verify the probe is connected and the RTT control block is available. For TCP/IP, check the target address, port, and network access. If data still does not appear, review the stream port configuration and confirm the target is running.