Tracing

Overview

ESP-IDF provides a tracing system for program behavior analysis and debugging. It lets you collect runtime data from ESP32 and send it to a host computer with minimal overhead.

The system is centered on the esp_trace component. It owns the public tracing API, manages the active trace session, and connects trace encoders with trace transports. Other tracing features, such as SEGGER SystemView, Gcov, and the apptrace transport, plug into this model.

The esp_trace component supports common trace formats and transports, and is designed to be extensible. New trace formats and transports can be added without modifying ESP-IDF. For more information about the design, see Tracing Architecture.

Trace formats: SEGGER SystemView for industry-standard FreeRTOS analysis (see System Behavior Analysis with SEGGER SystemView), or your own recorder (see Integrating a Custom Trace Library).
Transports:
- the apptrace transport (app_trace component) over JTAG or UART

Choosing Your Path

Goal	Where to look
Analyze FreeRTOS task/ISR behavior	SEGGER SystemView
Send/receive arbitrary application data, or log to host	Application Level Tracing transport
Collect source code coverage	Gcov
Trace every function entry and exit automatically	Function tracing
Integrate a third-party trace recorder	Custom trace library

Choosing a Transport

The trace format and the transport are selected independently. Pick the host link based on your available hardware:

apptrace over JTAG: Highest throughput and host-initiated control (start, stop, or dump). Requires a JTAG adapter and OpenOCD on the host. Best for SystemView and on-demand Gcov dumps.
apptrace over UART: Uses a spare UART instead of a debug probe, at lower throughput than JTAG. Pick a UART that is not used by the console.

Key Features

Automatic initialization: Tracing is configured automatically at startup
Multi-core support: Works on single and dual-core chips
Extensible: Add custom trace formats or transports; see Tracing Architecture

Quick Start: SystemView Tracing

To enable SEGGER SystemView tracing for FreeRTOS system analysis:

Add the espressif/esp_sysview dependency to your project's idf_component.yml.
Select the external trace library by enabling CONFIG_ESP_TRACE_LIB_EXTERNAL.
Select the apptrace transport by enabling CONFIG_ESP_TRACE_TRANSPORT_APPTRACE.
Set the data destination to JTAG by enabling CONFIG_APPTRACE_DEST_JTAG.
Build and flash your application:
```
idf.py build flash
```

For detailed SystemView usage, OpenOCD setup, and host-side visualization, see System Behavior Analysis with SEGGER SystemView.

Detailed Guides

Examples

system/app_trace_basic: Basic application tracing
system/sysview_tracing: SystemView tracing example
system/sysview_tracing_heap_log: Heap tracing with SystemView
system/gcov: Source code coverage over JTAG
system/function_tracing: Compiler-instrumented function entry/exit tracing
system/esp_trace_custom_library: External trace library integration template

Was this page helpful?

Thank you! We received your feedback.
If you have any comments, fill in Espressif Documentation Feedback Form.

We value your feedback.
Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.