docs/release/userguide/Ftrace.debugging.tool.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 =====================
   6 FTrace Debugging Tool
   7 =====================
   8
   9 About Ftrace
  10 -------------
  11 Ftrace is an internal tracer designed to find what is going on inside the kernel. It can be used
  12 for debugging or analyzing latencies and performance related issues that take place outside of
  13 user-space. Although ftrace is typically considered the function tracer, it is really a frame
  14 work of several assorted tracing utilities.
  15
  16     One of the most common uses of ftrace is the event tracing.
  17
  18 **Note:**
  19 - For KVM4NFV, Ftrace is preferred as it is in-built kernel tool
  20 - More stable compared to other debugging tools
  21
  22 Version Features
  23 ----------------
  24
  25 +-----------------------------+-----------------------------------------------+
  26 |                             |                                               |
  27 |      **Release**            |               **Features**                    |
  28 |                             |                                               |
  29 +=============================+===============================================+
  30 |                             | - Ftrace Debugging tool is not implemented in |
  31 |       Colorado              |   Colorado release of KVM4NFV                 |
  32 |                             |                                               |
  33 +-----------------------------+-----------------------------------------------+
  34 |                             | - Ftrace aids in debugging the KVM4NFV        |
  35 |       Danube                |   4.4-linux-kernel level issues               |
  36 |                             | - Option to disable if not required           |
  37 +-----------------------------+-----------------------------------------------+
  38
  39
  40 Implementation of Ftrace
  41 -------------------------
  42 Ftrace uses the debugfs file system to hold the control files as
  43 well as the files to display output.
  44
  45 When debugfs is configured into the kernel (which selecting any ftrace
  46 option will do) the directory /sys/kernel/debug will be created. To mount
  47 this directory, you can add to your /etc/fstab file:
  48
  49 .. code:: bash
  50
  51  debugfs       /sys/kernel/debug          debugfs defaults        0       0
  52
  53 Or you can mount it at run time with:
  54
  55 .. code:: bash
  56
  57  mount -t debugfs nodev /sys/kernel/debug
  58
  59 Some configurations for Ftrace are used for other purposes, like finding latency or analyzing the system. For the purpose of debugging, the kernel configuration parameters that should be enabled are:
  60
  61 .. code:: bash
  62
  63     CONFIG_FUNCTION_TRACER=y
  64     CONFIG_FUNCTION_GRAPH_TRACER=y
  65     CONFIG_STACK_TRACER=y
  66     CONFIG_DYNAMIC_FTRACE=y
  67
  68 The above parameters must be enabled in /boot/config-4.4.0-el7.x86_64 i.e., kernel config file for ftrace to work. If not enabled, change the parameter to ``y`` and run.,
  69
  70 .. code:: bash
  71
  72     On CentOS
  73     grub2-mkconfig -o /boot/grub2/grub.cfg
  74     sudo reboot
  75
  76 Re-check the parameters after reboot before running ftrace.
  77
  78 Files in Ftrace:
  79 ----------------
  80 The below is a list of few major files in Ftrace.
  81
  82   ``current_tracer:``
  83
  84         This is used to set or display the current tracer that is configured.
  85
  86   ``available_tracers:``
  87
  88         This holds the different types of tracers that have been compiled into the kernel. The tracers listed here can be configured by echoing their name into current_tracer.
  89
  90   ``tracing_on:``
  91
  92         This sets or displays whether writing to the tracering buffer is enabled. Echo 0 into this file to disable the tracer or 1 to enable it.
  93
  94   ``trace:``
  95
  96         This file holds the output of the trace in a human readable format.
  97
  98   ``tracing_cpumask:``
  99
 100         This is a mask that lets the user only trace on specified CPUs. The format is a hex string representing the CPUs.
 101
 102   ``events:``
 103
 104         It holds event tracepoints (also known as static tracepoints) that have been compiled into the kernel. It shows what event tracepoints exist and how they are grouped by system.
 105
 106
 107 Avaliable Tracers
 108 -----------------
 109
 110 Here is the list of current tracers that may be configured based on usage.
 111
 112 - function
 113 - function_graph
 114 - irqsoff
 115 - preemptoff
 116 - preemptirqsoff
 117 - wakeup
 118 - wakeup_rt
 119
 120 Brief about a few:
 121
 122   ``function:``
 123
 124         Function call tracer to trace all kernel functions.
 125
 126   ``function_graph:``
 127
 128         Similar to the function tracer except that the function tracer probes the functions on their entry whereas the function graph tracer traces on both entry and exit of the functions.
 129
 130   ``nop:``
 131
 132         This is the "trace nothing" tracer. To remove tracers from tracing simply echo "nop" into current_tracer.
 133
 134 Examples:
 135
 136 .. code:: bash
 137
 138
 139      To list available tracers:
 140      [tracing]# cat available_tracers
 141      function_graph function wakeup wakeup_rt preemptoff irqsoff preemptirqsoff nop
 142
 143      Usage:
 144      [tracing]# echo function > current_tracer
 145      [tracing]# cat current_tracer
 146      function
 147
 148      To view output:
 149      [tracing]# cat trace | head -10
 150
 151      To Stop tracing:
 152      [tracing]# echo 0 > tracing_on
 153
 154      To Start/restart tracing:
 155      [tracing]# echo 1 > tracing_on;
 156
 157
 158 Ftrace in KVM4NFV
 159 -----------------
 160 Ftrace is part of KVM4NFV D-Release. KVM4NFV built 4.4-linux-Kernel will be tested by
 161 executing cyclictest and analyzing the results/latency values (max, min, avg) generated.
 162 Ftrace (or) function tracer is a stable kernel inbuilt debugging tool which tests real time
 163 kernel and outputs a log as part of the code. These output logs are useful in following ways.
 164
 165     - Kernel Debugging.
 166     - Helps in Kernel code optimization and
 167     - Can be used to better understand the kernel level code flow
 168
 169 Ftrace logs for KVM4NFV can be found `here`_:
 170
 171
 172 .. _here: http://artifacts.opnfv.org/kvmfornfv.html
 173
 174 Ftrace Usage in KVM4NFV Kernel Debugging:
 175 -----------------------------------------
 176 Kvm4nfv has two scripts in /ci/envs to provide ftrace tool:
 177
 178     - enable_trace.sh
 179     - disable_trace.sh
 180
 181 .. code:: bash
 182
 183     Found at.,
 184     $ cd kvmfornfv/ci/envs
 185
 186 Enabling Ftrace in KVM4NFV
 187 --------------------------
 188
 189 The enable_trace.sh script is triggered by changing ftrace_enable value in test_kvmfornfv.sh
 190 script to 1 (which is zero by default). Change as below to enable Ftrace.
 191
 192 .. code:: bash
 193
 194     ftrace_enable=1
 195
 196 Note:
 197
 198 - Ftrace is enabled before
 199
 200 Details of enable_trace script
 201 ------------------------------
 202
 203 - CPU coremask is calculated using getcpumask()
 204 - All the required events are enabled by,
 205    echoing "1" to $TRACEDIR/events/event_name/enable file
 206
 207 Example,
 208
 209 .. code:: bash
 210
 211    $TRACEDIR = /sys/kernel/debug/tracing/
 212    sudo bash -c "echo 1 > $TRACEDIR/events/irq/enable"
 213    sudo bash -c "echo 1 > $TRACEDIR/events/task/enable"
 214    sudo bash -c "echo 1 > $TRACEDIR/events/syscalls/enable"
 215
 216 The set_event file contains all the enabled events list
 217
 218 - Function tracer is selected. May be changed to other avaliable tracers based on requirement
 219
 220 .. code:: bash
 221
 222    sudo bash -c "echo function > $TRACEDIR/current_tracer
 223
 224 - When tracing is turned ON by setting ``tracing_on=1``,  the ``trace`` file keeps getting append with the traced data until ``tracing_on=0`` and then ftrace_buffer gets cleared.
 225
 226 .. code:: bash
 227
 228     To Stop/Pause,
 229     echo 0 >tracing_on;
 230
 231     To Start/Restart,
 232     echo 1 >tracing_on;
 233
 234 - Once tracing is diabled, disable_trace.sh script is triggered.
 235
 236 Details of disable_trace Script
 237 -------------------------------
 238 In disable trace script the following are done:
 239
 240 - The trace file is copied and moved to /tmp folder based on timestamp
 241 - The current tracer file is set to ``nop``
 242 - The set_event file is cleared i.e., all the enabled events are disabled
 243 - Kernel Ftrace is disabled/unmounted
 244
 245
 246 Publishing Ftrace logs:
 247 -----------------------
 248 The generated trace log is pushed to `artifacts`_ by kvmfornfv-upload-artifact.sh
 249 script available in releng which will be triggered as a part of kvm4nfv daily job.
 250 The `trigger`_ in the script is.,
 251
 252 .. code:: bash
 253
 254    echo "Uploading artifacts for future debugging needs...."
 255    gsutil cp -r $WORKSPACE/build_output/log-*.tar.gz $GS_LOG_LOCATION > $WORKSPACE/gsutil.log 2>&1
 256
 257 .. _artifacts: https://artifacts.opnfv.org/
 258
 259 .. _trigger: https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/kvmfornfv/kvmfornfv-upload-artifact.sh;h=56fb4f9c18a83c689a916dc6c85f9e3ddf2479b2;hb=HEAD#l53