# Tracing

[中文]

## Overview

ESP-IDF provides a tracing system for program behavior analysis and debugging. It lets you collect runtime data from ESP32-H4 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

  - the USB Serial JTAG transport

## 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.

- USB Serial JTAG: Uses the chip's built-in USB peripheral over a single USB cable, with no external adapter. Trace data flows over the peripheral's serial (CDC) interface, not its JTAG interface. Available when USB Serial JTAG is not already taken 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:

1. Add the `espressif/esp_sysview` dependency to your project's `idf_component.yml`.

2. Select the external trace library by enabling CONFIG_ESP_TRACE_LIB_EXTERNAL.

3. Select the apptrace transport by enabling CONFIG_ESP_TRACE_TRANSPORT_APPTRACE.

4. Set the data destination to JTAG by enabling CONFIG_APPTRACE_DEST_JTAG.

5. 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

- Tracing Architecture
- Application Level Tracing Transport (apptrace)
- System Behavior Analysis with SEGGER SystemView
- Gcov (Source Code Coverage)
- Compiler-Instrumented Function Tracing
- Integrating a Custom Trace Library

## Related Documentation

- ESP Trace: ESP Trace API reference

- Application Level Tracing: Application Level Tracing (transport) API reference

- JTAG Debugging: JTAG debugging setup and hardware configuration

- SEGGER SystemView: Official SystemView tool and documentation

- OpenOCD: Open On-Chip Debugger

## Examples

- system/tracing/app_trace_basic: Basic application tracing

- system/tracing/sysview_tracing: SystemView tracing example

- system/tracing/sysview_tracing_heap_log: Heap tracing with SystemView

- system/tracing/gcov: Source code coverage over JTAG

- system/tracing/function_tracing: Compiler-instrumented function entry/exit tracing

- system/tracing/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.