Master Tracealyzer with Zephyr
Getting Started with Tracealyzer on Zephyr
Integrate TraceRecorder, capture your first Zephyr trace, and analyze it in Tracealyzer.
Step 1
Integrate TraceRecorder
Step 2
Configure Tracing
Step 3
Capture Your First Trace
Capture your first trace and see how your Zephyr application executes.
Prerequisites
Before you begin
- Install Tracealyzer. If you haven’t done so, see detailed instructions here
- Existing Zephyr application
- Zephyr application builds and runs
- Target/debug connection available
Step 1: Add TraceRecorder
Integrate TraceRecorder into Your Project
Add TraceRecorder
- Add the following minimal configuration to your prj.conf:
CONFIG_TRACING=yCONFIG_PERCEPIO_TRACERECORDER=y
Configure TraceRecorder
- The following settings are recommended but not mandatory:
# Disable the "Syscall" event categoryCONFIG_TRACING_SYSCALL=n
# Disable “polling” events which are sometimes frequent and costly
CONFIG_TRACING_POLLING=n
Start TraceRecorder
The Zephyr build system will now automatically integrate TraceRecorder into your project
For complete TraceRecorder Integration details and advanced configuration, see the detailed TraceRecorder for Zephyr 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.
Add the following configurations to your prj.conf:
CONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RINGBUFFER=yCONFIG_PERCEPIO_TRC_CFG_STREAM_PORT_RINGBUFFER_SIZE=10240
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.- To define the buffer behaviour when it get’s full you can select either of:
-
CONFIG_PERCEPIO_TRC_STREAM_PORT_RINGBUFFER_MODE_OVERWRITE_WHEN_FULL=yfor continuously recording (DEFAULT)CONFIG_PERCEPIO_TRC_STREAM_PORT_RINGBUFFER_MODE_STOP_WHEN_FULL=yfor 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 - Enable the chosen method by adding one of the following configurations to your prj.conf file:
PERCEPIO_TRC_CFG_STREAM_PORT_RTT=y
PERCEPIO_TRC_CFG_STREAM_PORT_ITM=y
PERCEPIO_TRC_CFG_STREAM_PORT_TCPIP=y
PERCEPIO_TRC_CFG_STREAM_PORT_UDP=y
PERCEPIO_TRC_CFG_STREAM_PORT_ZEPHYR_SEMIHOST=y
PERCEPIO_TRC_CFG_STREAM_PORT_ESP_IDF_APPTRACE=y
PERCEPIO_TRC_CFG_STREAM_PORT_STM32_USB_CDC=y - Ensure your target settings are matched in the Tracealyzer application
For all the details of streaming configuration, see Zephyr Trace Streaming.
Step 3: Trace Capture
Capture Your First Trace
Snapshot
- VS Code
- STM32CubeIDE
- GDB or Eclipse
- Renesas e2 studiot
- IAR Embedded Workbench for Arm
- Lauterbach TRACE32
- Other Application Notes
Streaming
Opening the Trace
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
-
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 Zephyr Trace
Check the Setup Before Capturing Again
Start with a Zephyr 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 tracing is enabled in your prj.conf with CONFIG_TRACING=y and CONFIG_PERCEPIO_TRACERECORDER=y. Clean and rebuild the project after changing settings. If the error persists, consult the TraceRecorder for Zephyr reference guide.
Trace File Is Empty
Check that tracing is enabled and TraceRecorder starts before the events you want to capture. For Snapshot, confirm the target ran before you halted it and saved the RingBuffer contents. For Streaming, verify the selected stream port matches your connection and that Tracealyzer is receiving data. If the trace is still empty, review your configuration and capture procedure, then try again.