docs/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 KVMFORNFV, 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 KVMFORNFV               |
  32 |                             |                                               |
  33 +-----------------------------+-----------------------------------------------+
  34 |                             | - Ftrace aids in debugging the KVMFORNFV      |
  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 KVMFORNFV
 159 -------------------
 160 Ftrace is part of KVMFORNFV D-Release. KVMFORNFV 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 kernel in real
 163 time 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 KVMFORNFV can be found `here`_:
 170
 171
 172 .. _here: http://artifacts.opnfv.org/kvmfornfv.html
 173
 174 Ftrace Usage in KVMFORNFV Kernel Debugging:
 175 -------------------------------------------
 176 Kvmfornfv has two scripts in /ci/envs to provide ftrace tool:
 177
 178     - enable_trace.sh
 179     - disable_trace.sh
 180
 181 Enabling Ftrace in KVMFORNFV
 182 ----------------------------
 183
 184 The enable_trace.sh script is triggered by changing ftrace_enable value in test_kvmfornfv.sh
 185 script to 1 (which is zero by default). Change as below to enable Ftrace.
 186
 187 .. code:: bash
 188
 189     ftrace_enable=1
 190
 191 Note:
 192
 193 - Ftrace is enabled before
 194
 195 Details of enable_trace script
 196 ------------------------------
 197
 198 - CPU coremask is calculated using getcpumask()
 199 - All the required events are enabled by,
 200    echoing "1" to $TRACEDIR/events/event_name/enable file
 201
 202 Example,
 203
 204 .. code:: bash
 205
 206    $TRACEDIR = /sys/kernel/debug/tracing/
 207    sudo bash -c "echo 1 > $TRACEDIR/events/irq/enable"
 208    sudo bash -c "echo 1 > $TRACEDIR/events/task/enable"
 209    sudo bash -c "echo 1 > $TRACEDIR/events/syscalls/enable"
 210
 211 The set_event file contains all the enabled events list
 212
 213 - Function tracer is selected. May be changed to other avaliable tracers based on requirement
 214
 215 .. code:: bash
 216
 217    sudo bash -c "echo function > $TRACEDIR/current_tracer
 218
 219 - 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.
 220
 221 .. code:: bash
 222
 223     To Stop/Pause,
 224     echo 0 >tracing_on;
 225
 226     To Start/Restart,
 227     echo 1 >tracing_on;
 228
 229 - Once tracing is diabled, disable_trace.sh script is triggered.
 230
 231 Details of disable_trace Script
 232 -------------------------------
 233 In disable trace script the following are done:
 234
 235 - The trace file is copied and moved to /tmp folder based on timestamp
 236 - The current tracer file is set to ``nop``
 237 - The set_event file is cleared i.e., all the enabled events are disabled
 238 - Kernel Ftrace is disabled/unmounted
 239
 240
 241 Publishing Ftrace logs:
 242 -----------------------
 243 The generated trace log is pushed to `artifacts`_ by kvmfornfv-upload-artifact.sh
 244 script available in releng which will be triggered as a part of kvmfornfv daily job.
 245 The `trigger`_ in the script is.,
 246
 247 .. code:: bash
 248
 249    echo "Uploading artifacts for future debugging needs...."
 250    gsutil cp -r $WORKSPACE/build_output/log-*.tar.gz $GS_LOG_LOCATION > $WORKSPACE/gsutil.log 2>&1
 251
 252 .. _artifacts: https://artifacts.opnfv.org/
 253
 254 .. _trigger: https://gerrit.opnfv.org/gerrit/gitweb?p=releng.git;a=blob;f=jjb/kvmfornfv/kvmfornfv-upload-artifact.sh;h=56fb4f9c18a83c689a916dc6c85f9e3ddf2479b2;hb=HEAD#l53