Chapter 27. Tracing latencies using ftrace

The ftrace utility is one of the diagnostic facilities provided with the RHEL for Real Time kernel. ftrace can be used by developers to analyze and debug latency and performance issues that occur outside of the user-space. The ftrace utility has a variety of options that allow you to use the utility in different ways. It can be used to trace context switches, measure the time it takes for a high-priority task to wake up, the length of time interrupts are disabled, or list all the kernel functions executed during a given period.

Some of the ftrace tracers, such as the function tracer, can produce exceedingly large amounts of data, which can turn trace log analysis into a time-consuming task. However, you can instruct the tracer to begin and end only when the application reaches critical code paths.

Prerequisites

You have administrator privileges.

27.1. Using the ftrace utility to trace latencies

You can trace latencies using the ftrace utility.

Procedure

View the available tracers on the system.
```
# cat /sys/kernel/debug/tracing/available_tracers
function_graph wakeup_rt wakeup preemptirqsoff preemptoff irqsoff function nop
```
The user interface for ftrace is a series of files within debugfs.
The ftrace files are also located in the /sys/kernel/debug/tracing/ directory.
Move to the /sys/kernel/debug/tracing/ directory.
```
# cd /sys/kernel/debug/tracing
```
The files in this directory can only be modified by the root user, because enabling tracing can have an impact on the performance of the system.
To start a tracing session:
1. Select a tracer you want to use from the list of available tracers in /sys/kernel/debug/tracing/available_tracers.
2. Insert the name of the selector into the /sys/kernel/debug/tracing/current_tracer.
```
# echo preemptoff > /sys/kernel/debug/tracing/current_tracer
```
  Note
  If you use a single '>' with the echo command, it will override any existing value in the file. If you wish to append the value to the file, use '>>' instead.
The function-trace option is useful because tracing latencies with wakeup_rt, preemptirqsoff, and so on automatically enables function tracing, which may exaggerate the overhead.
Check if function and function_graph tracing are enabled:
```
# cat /sys/kernel/debug/tracing/options/function-trace
1
```
- A value of 1 indicates that function and function_graph tracing are enabled.
- A value of 0 indicates that function and function_graph tracing are disabled.
By default, function and function_graph tracing are enabled. To turn function and function_graph tracing on or off, echo the appropriate value to the /sys/kernel/debug/tracing/options/function-trace file.
```
# echo 0 > /sys/kernel/debug/tracing/options/function-trace
# echo 1 > /sys/kernel/debug/tracing/options/function-trace
```
Important
When using the echo command, ensure you place a space character in between the value and the > character. At the shell prompt, using 0>, 1>, and 2> (without a space character) refers to standard input, standard output, and standard error. Using them by mistake could result in an unexpected trace output.
Adjust the details and parameters of the tracers by changing the values for the various files in the /debugfs/tracing/ directory.
For example:
The irqsoff, preemptoff, preempirqsoff, and wakeup tracers continuously monitor latencies. When they record a latency greater than the one recorded in tracing_max_latency the trace of that latency is recorded, and tracing_max_latency is updated to the new maximum time. In this way, tracing_max_latency always shows the highest recorded latency since it was last reset.
- To reset the maximum latency, echo 0 into the tracing_max_latency file:
```
# echo 0 > /sys/kernel/debug/tracing/tracing_max_latency
```
- To see only latencies greater than a set amount, echo the amount in microseconds:
```
# echo 200 > /sys/kernel/debug/tracing/tracing_max_latency
```
  When the tracing threshold is set, it overrides the maximum latency setting. When a latency is recorded that is greater than the threshold, it will be recorded regardless of the maximum latency. When reviewing the trace file, only the last recorded latency is shown.
- To set the threshold, echo the number of microseconds above which latencies must be recorded:
```
# echo 200 > /sys/kernel/debug/tracing/tracing_thresh
```
View the trace logs:
```
# cat /sys/kernel/debug/tracing/trace
```

To store the trace logs, copy them to another file:

# cat /sys/kernel/debug/tracing/trace > /tmp/lat_trace_log

View the functions being traced:

# cat /sys/kernel/debug/tracing/set_ftrace_filter

Filter the functions being traced by editing the settings in /sys/kernel/debug/tracing/set_ftrace_filter. If no filters are specified in the file, all functions are traced.
To change filter settings, echo the name of the function to be traced. The filter allows the use of a '*' wildcard at the beginning or end of a search term.
For examples, see ftrace examples.

27.2. ftrace files

The following are the main files in the /sys/kernel/debug/tracing/ directory.

ftrace files

trace: The file that shows the output of an ftrace trace. This is really a snapshot of the trace in time, because the trace stops when this file is read, and it does not consume the events read. That is, if the user disabled tracing and reads this file, it will report the same thing every time it is read.
trace_pipe: The file that shows the output of an ftrace trace as it reads the trace live. It is a producer/consumer trace. That is, each read will consume the event that is read. This can be used to read an active trace without stopping the trace as it is read.
available_tracers: A list of ftrace tracers that have been compiled into the kernel.
current_tracer: Enables or disables an ftrace tracer.
events: A directory that contains events to trace and can be used to enable or disable events, as well as set filters for the events.
tracing_on: Disable and enable recording to the ftrace buffer. Disabling tracing via the tracing_on file does not disable the actual tracing that is happening inside the kernel. It only disables writing to the buffer. The work to do the trace still happens, but the data does not go anywhere.

27.3. ftrace tracers

Depending on how the kernel is configured, not all tracers may be available for a given kernel. For the RHEL for Real Time kernels, the trace and debug kernels have different tracers than the production kernel does. This is because some of the tracers have a noticeable overhead when the tracer is configured into the kernel, but not active. Those tracers are only enabled for the trace and debug kernels.

Tracers

function: One of the most widely applicable tracers. Traces the function calls within the kernel. This can cause noticeable overhead depending on the number of functions traced. When not active, it creates little overhead.
function_graph: The function_graph tracer is designed to present results in a more visually appealing format. This tracer also traces the exit of the function, displaying a flow of function calls in the kernel.
Note
This tracer has more overhead than the function tracer when enabled, but the same low overhead when disabled.
wakeup: A full CPU tracer that reports the activity happening across all CPUs. It records the time that it takes to wake up the highest priority task in the system, whether that task is a real time task or not. Recording the max time it takes to wake up a non-real time task hides the times it takes to wake up a real time task.
wakeup_rt: A full CPU tracer that reports the activity happening across all CPUs. It records the time that it takes from the current highest priority task to wake up to until the time it is scheduled. This tracer only records the time for real time tasks.
preemptirqsoff: Traces the areas that disable preemption or interrupts, and records the maximum amount of time for which preemption or interrupts were disabled.
preemptoff: Similar to the preemptirqsoff tracer, but traces only the maximum interval for which pre-emption was disabled.
irqsoff: Similar to the preemptirqsoff tracer, but traces only the maximum interval for which interrupts were disabled.
nop: The default tracer. It does not provide any tracing facility itself, but as events may interleave into any tracer, the nop tracer is used for specific interest in tracing events.

27.4. ftrace examples

The following provides a number of examples for changing the filtering of functions being traced. You can use the * wildcard at both the beginning and end of a word. For example: *irq\* will select all functions that contain irq in the name. The wildcard cannot, however, be used inside a word.

Encasing the search term and the wildcard character in double quotation marks ensures that the shell will not attempt to expand the search to the present working directory.

Examples of filters

Trace only the schedule function:

# echo schedule > /sys/kernel/debug/tracing/set_ftrace_filter

Trace all functions that end with lock:

# echo "*lock" > /sys/kernel/debug/tracing/set_ftrace_filter

Trace all functions that start with spin_:

# echo "spin_*" > /sys/kernel/debug/tracing/set_ftrace_filter

Trace all functions with cpu in the name:

# echo "cpu" > /sys/kernel/debug/tracing/set_ftrace_filter

Chapter 27. Tracing latencies using ftrace

27.1. Using the ftrace utility to trace latencies

27.2. ftrace files

27.3. ftrace tracers

27.4. ftrace examples

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links