Introduction to Ftrace on Android

Ftrace, the Linux kernel’s internal tracing mechanism, is an indispensable tool for debugging and performance analysis, offering deep insights into kernel operations. On Android devices, understanding Ftrace is crucial for advanced system optimization, identifying performance bottlenecks, and debugging intricate kernel-level issues. This guide provides a comprehensive, step-by-step approach to setting up and utilizing Ftrace for event tracing on Android, enabling you to peek under the hood of your device’s kernel.

From scheduler behavior to interrupt handling, Ftrace records a vast array of kernel events, providing a chronological log that is invaluable for developers, researchers, and power users aiming to understand or modify their Android system’s core. We will explore how to access, configure, and interpret Ftrace data directly from your rooted Android device.

Prerequisites for Ftrace Setup

Before diving into Ftrace, ensure you have the following:

• A rooted Android device (required for su access to debugfs).
• Android Debug Bridge (ADB) installed and configured on your host machine.
• Basic familiarity with Linux command-line operations.

Confirm ADB connectivity and root access:

adb shellsu

If successful, your prompt will change to #, indicating root privileges.

Understanding Ftrace Fundamentals

Ftrace operates by inserting tracepoints at strategic locations within the kernel code. When an event occurs (e.g., a function call, a scheduler switch), data is logged into an in-memory buffer. This buffer can then be read and analyzed. The primary interface to Ftrace is through the debugfs filesystem, typically mounted at /sys/kernel/debug/tracing on Android.

Key Concepts:

• Tracers: Mechanisms to record specific types of events (e.g., function, sched_switch, irq_tracer).
• Events: Specific occurrences within the kernel that can be traced (e.g., sched:sched_switch, irq:irq_handler_entry). These are grouped into subsystems.
• Trace Buffer: An in-memory circular buffer where trace data is stored.

Step-by-Step Ftrace Configuration on Android

All Ftrace operations are performed via files within the /sys/kernel/debug/tracing/ directory.

1. Navigating to the Tracing Directory

adb shellsucd /sys/kernel/debug/tracing/

2. Listing Available Tracers

To see which tracers your kernel supports:

cat available_tracers

Output might look like: function_graph function nop sched_switch irq_tracer

3. Listing Available Events

Events are categorized into subsystems. To list all available events:

ls events/

To list events for a specific subsystem, e.g., ‘sched’:

ls events/sched/

Output might include: sched_switch sched_wakeup sched_migrate_task

4. Enabling and Disabling Tracers

To enable a tracer, write its name to the current_tracer file. For example, to enable the sched_switch tracer:

echo sched_switch > current_tracer

To disable all tracers and revert to the default nop (no operation) tracer:

echo nop > current_tracer

5. Enabling Specific Events

For more granular tracing, you can enable individual events or entire event subsystems. This is often more efficient than using a broad tracer like function.

To enable all events in the ‘sched’ subsystem:

echo 1 > events/sched/enable

To enable a specific event, e.g., sched_switch:

echo 1 > events/sched/sched_switch/enable

To disable:

echo 0 > events/sched/enable

or

echo 0 > events/sched/sched_switch/enable

6. Configuring the Trace Buffer Size

The default buffer size might be too small for detailed analysis. You can adjust it (in pages, typically 4KB each):

echo 1024 > buffer_size_kb # Sets buffer to 1MB (1024 KB)

You can also configure per-CPU buffer sizes:

echo 512 > per_cpu/cpu0/buffer_size_kb # 512KB for CPU 0

7. Starting and Stopping Tracing

To start recording events:

echo 1 > tracing_on

To stop recording:

echo 0 > tracing_on

8. Reading Trace Data

Once tracing is stopped, read the collected data from the trace file:

cat trace > /sdcard/ftrace_output.txt

Then, pull the file to your host machine:

adb pull /sdcard/ftrace_output.txt .

9. Clearing the Trace Buffer

It’s good practice to clear the buffer before a new tracing session:

echo > trace # Empties the trace file and buffer

Practical Example: Analyzing Scheduler Latency

Let’s use Ftrace to observe scheduler activity during a workload.

Scenario:

We want to understand how the kernel scheduler behaves when a CPU-intensive application starts.

Steps:

1. Initialize Ftrace: Clear the buffer, disable tracing, and set the desired tracer and events.

   echo > traceecho 0 > tracing_onecho sched_switch > current_tracerecho 1 > events/sched/enable # Enable all scheduler events

2. Set Buffer Size (Optional but Recommended):

   echo 4096 > buffer_size_kb # 4MB buffer

3. Start Tracing:

   echo 1 > tracing_on

4. Execute Workload: On your Android device, launch a CPU-intensive app or perform a task you want to analyze.

5. Stop Tracing:

   echo 0 > tracing_on

6. Extract and Analyze Trace Data:

   cat trace > /sdcard/sched_trace.txtadb pull /sdcard/sched_trace.txt .

   Open sched_trace.txt. You will see entries like:

   # tracer: sched_switch# # entries: 1234567# #                                _-----=> irq_disable# #                               / _----=> need_resched# #                              | / _---=> hardirq/softirq# #                              || / _--=> preempt_count# #                              ||| / _-=> migrate_disable# #                              |||| /     delay# #           TASK-PID   CPU#    |||||  TIMESTAMP  FUNCTION#            -0     [000] ....1    1.234567: sched_switch: prev_comm=swapper/0 prev_pid=0 prev_prio=120 prev_state=R ==> next_comm=system_server next_pid=1234 next_prio=120#     system_server-1234  [000] ....1    1.234678: sched_switch: prev_comm=system_server prev_pid=1234 prev_prio=120 prev_state=S ==> next_comm=kworker/0:1 next_pid=567 next_prio=120

   This output shows which tasks (prev_comm) are yielding the CPU to which other tasks (next_comm), along with PIDs, CPU core, and precise timestamps. Analyzing these entries helps identify tasks causing contention, unexpected context switches, or prolonged waits.

7. Clean Up:

   echo nop > current_tracerecho > traceecho 0 > events/sched/enable

Advanced Ftrace Features

• Event Filtering: You can filter events based on their fields. For example, to only trace sched_switch events where next_comm is ‘system_server’:

  echo 'next_comm ==
  
          
          
          
  
              
  
                  
              
              
  
                  
  Android Mobile Specs & Compare Directory
                  
  Are you researching mobile hardware properties, processor SoCs, GPU chipsets, or RAM configurations? Access our complete specs catalog to compare up to 5 devices side-by-side!
                  Compare Devices Specs →