Master Tracealyzer with ESP-IDF

Getting Started with Tracealyzer on ESP-IDF

Integrate TraceRecorder, capture your first ESP-IDF 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 ESP-IDF application executes.

Capture Trace

Prerequisites

Before you begin

Install Tracealyzer. If you haven’t done so, see detailed instructions here
Existing ESP-IDF application
ESP-IDF 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 by making the following adjustments in your CMakeLists.txt:
- Add TraceRecorder by adding:
```
set(EXTRA_COMPONENT_DIRS <TraceRecorderPath>/kernelports/ESP-IDF_FreeRTOS)
```
- Ensure MINIMAL_BUILD is disabled. If not, ensure to comment out:
```
idf_build_set_property(MINIMAL_BUILD ON)
```

Configure TraceRecorder

No action needed

Start TraceRecorder

Start by rebuilding your application, by so, the TraceRecorder settings will appear in menuconfig.
Open the menuconfig by running idf.py menuconfig (or use the ESP-IDF Explorer tab in VS Code)
Navigate to Percepio TraceRecorder and enable the Enable Percepio TraceRecorder option (if it can’t be found please try to make a clean rebuild)

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

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

Make the following configurations in menuconfig (as described above)

Ensure the StreamPort option is set to “Ring Buffer“

This minimal configuration will allow you to capture essential trace data without overwhelming your system resources.

Ring 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 of 10240 bytes and increase it if you need a longer trace.
Ring Buffer Mode: defines what should happen when the buffer get’s full. Set it to either of:

- Overwrite: for continuously recording and always store the last events
- Stop: 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
ESP-IDF AppTrace	Trax interface
J-Link RTT	Debug probe
TCP/IP	Network-connected target
ITM	ARM Cortex-M + debugger
Other stream ports	See stream-port documentation

Select the desired method as StreamPort in menuconfig
Ensure that your target streaming settings are matched in the Tracealyzer application

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 ESP-IDF Trace

Resolve common TraceRecorder setup and capture issues when using Tracealyzer.

Check the Setup Before Capturing Again

Start with an 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 the TraceRecorder source files are included in your ESP-IDF build and that the component path in CMakeLists.txt points to the correct ESP-IDF FreeRTOS port. Confirm MINIMAL_BUILD is disabled, then run a clean rebuild so the TraceRecorder menuconfig options are available. If the compiler reports a missing processor header or a hardware port mismatch, verify the target port and required includes in your configuration.

Hardware-Port or Version Error

Check that your TraceRecorder hardware port matches the ESP-IDF target and FreeRTOS version used by your project. Use the port included with your TraceRecorder release, and confirm the required headers and configuration are available. If the error persists, clean the build, verify your ESP-IDF and TraceRecorder versions are compatible, then rebuild.

Trace File Is Empty

Confirm that tracing is enabled in menuconfig and that TraceRecorder starts successfully when your application runs. For Snapshot capture, let the application generate events before halting the target, then save the RingBuffer contents and open the resulting file in Tracealyzer. Check that the RingBuffer has enough capacity and that its mode matches your needs. For Streaming capture, verify the selected stream port matches your connection and that data reaches Tracealyzer. Rebuild after configuration changes and capture again.

Snapshot Stops Too Soon

If your snapshot ends before the behavior you want to inspect, increase the Ring Buffer Size in menuconfig to retain more trace history. The buffer uses target RAM, so raise it gradually and confirm your device has enough memory. In Ring Buffer Mode, choose Overwrite to keep the latest events or Stop to preserve the first events until the buffer fills. If you need a longer continuous capture than RAM allows, switch to Streaming and select a transport with enough bandwidth for your event rate.

Streaming Data Does Not Arrive

Check that TraceRecorder is enabled and starts when your application runs. Confirm the StreamPort selected in menuconfig matches your connection, such as J-Link RTT, AppTrace, or TCP/IP, and that Tracealyzer is configured for the same transport. Verify the probe or network connection is active and that the target is running. If data still does not appear, review the stream port configuration, check for connection errors, then rebuild and capture again.

Enhance Your Tracing Skills

Unlock deeper insights by exploring advanced trace analysis techniques and optimize your ESP-IDF applications.

Explore Advanced Techniques