man/systemd-bootchart.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2012 Intel Corporation
  10
  11   Authors:
  12     Auke Kok <auke-jan.h.kok@intel.com>
  13     William Giokas <1007380@gmail.com>
  14
  15   systemd is free software; you can redistribute it and/or modify it
  16   under the terms of the GNU Lesser General Public License as published by
  17   the Free Software Foundation; either version 2.1 of the License, or
  18   (at your option) any later version.
  19
  20   systemd is distributed in the hope that it will be useful, but
  21   WITHOUT ANY WARRANTY; without even the implied warranty of
  22   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  23   Lesser General Public License for more details.
  24
  25   You should have received a copy of the GNU Lesser General Public License
  26   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  27 -->
  28
  29 <refentry id="systemd-bootchart" conditional='ENABLE_BOOTCHART'>
  30         <refentryinfo>
  31                 <title>systemd-bootchart</title>
  32                 <productname>systemd</productname>
  33
  34                 <authorgroup>
  35                         <author>
  36                                 <contrib>Developer</contrib>
  37                                 <firstname>Auke</firstname>
  38                                 <surname>Kok</surname>
  39                                 <email>auke-jan.h.kok@intel.com</email>
  40                         </author>
  41                 </authorgroup>
  42         </refentryinfo>
  43
  44         <refmeta>
  45                 <refentrytitle>systemd-bootchart</refentrytitle>
  46                 <manvolnum>1</manvolnum>
  47         </refmeta>
  48
  49         <refnamediv>
  50                 <refname>systemd-bootchart</refname>
  51                 <refpurpose>Boot performance graphing tool</refpurpose>
  52         </refnamediv>
  53
  54         <refsect1>
  55                 <title>Description</title>
  56                 <para>
  57                         <command>systemd-bootchart</command> is a
  58                         tool, usually run at system startup, that
  59                         collects the CPU load, disk load, memory
  60                         usage, as well as per-process information from
  61                         a running system. Collected results are output
  62                         as an SVG graph. Normally, systemd-bootchart
  63                         is invoked by the kernel by passing
  64                         <option>init=<filename>/usr/lib/systemd/systemd-bootchart</filename></option>
  65                         on the kernel commandline. systemd-bootchart will then
  66                         fork the real init off to resume normal system
  67                         startup, while monitoring and logging startup
  68                         information in the background.
  69                 </para>
  70                 <para>
  71                         After collecting a certain amount of data
  72                         (usually 15-30 seconds, default 20 s) the
  73                         logging stops and a graph is generated from
  74                         the logged information. This graph contains
  75                         vital clues as to which resources are being used,
  76                         in which order, and where possible problems
  77                         exist in the startup sequence of the system.
  78                         It is essentially a more detailed version of
  79                         the <command>systemd-analyze</command>
  80                         <command>plot</command> function.
  81                 </para>
  82                 <para>
  83                         Of course, bootchart can also be used at any
  84                         moment in time to collect and graph some data
  85                         for an amount of time. It is
  86                         recommended to use the <option>--rel</option>
  87                         switch in this case.
  88                 </para>
  89                 <para>
  90                         Bootchart does not require root privileges,
  91                         and will happily run as a normal user.
  92                 </para>
  93                 <para>
  94                         Bootchart graphs are by default written
  95                         time-stamped in <filename>/run/log</filename>.
  96                 </para>
  97
  98         </refsect1>
  99
 100         <refsect1>
 101                 <title>Invocation</title>
 102
 103                 <para><command>systemd-bootchart</command> can be invoked in several different ways:</para>
 104
 105                 <variablelist>
 106
 107                         <varlistentry>
 108                                 <term><emphasis>Kernel invocation</emphasis></term>
 109                                 <listitem><para>The kernel can invoke
 110                                 <command>systemd-bootchart</command>
 111                                 instead of the init process. In turn,
 112                                 <command>systemd-bootchart</command>
 113                                 will invoke <command>/sbin/init</command>.
 114                                 </para></listitem>
 115                         </varlistentry>
 116
 117                         <varlistentry>
 118                                 <term><emphasis>Started as a standalone program</emphasis></term>
 119                                 <listitem><para>One can execute
 120                                 <command>systemd-bootchart</command>
 121                                 as normal application from the
 122                                 commandline. In this mode it is highly
 123                                 recommended to pass the
 124                                 <option>-r</option> flag in order to
 125                                 not graph the time elapsed since boot
 126                                 and before systemd-bootchart was
 127                                 started, as it may result in extremely
 128                                 large graphs.  </para></listitem>
 129                         </varlistentry>
 130                 </variablelist>
 131         </refsect1>
 132
 133         <refsect1>
 134                 <title>Options</title>
 135
 136                 <para>These options can also be set in the
 137                 <filename>/etc/systemd/bootchart.conf</filename>
 138                 file. See
 139                 <citerefentry><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 140                 </para>
 141
 142                 <variablelist>
 143
 144                         <varlistentry>
 145                                 <term><option>-n</option></term>
 146                                 <term><option>--sample <replaceable>N</replaceable></option></term>
 147                                 <listitem><para>Specify the number of
 148                                 samples, <replaceable>N</replaceable>,
 149                                 to record. Samples will be recorded at
 150                                 intervals defined with <option>--freq</option>.
 151                                 </para></listitem>
 152                         </varlistentry>
 153
 154                         <varlistentry>
 155                                 <term><option>-f</option></term>
 156                                 <term><option>--freq <replaceable>f</replaceable></option></term>
 157                                 <listitem><para>Specify the sample log
 158                                 frequency, a positive real <replaceable>f</replaceable>, in Hz.
 159                                 Most systems can cope with values up to 25-50 without
 160                                 creating too much overhead.</para></listitem>
 161                         </varlistentry>
 162
 163                         <varlistentry>
 164                                 <term><option>-r</option></term>
 165                                 <term><option>--rel</option></term>
 166                                 <listitem><para>Use relative times instead of absolute
 167                                 times. This is useful for using bootchart at post-boot
 168                                 time to profile an already booted system. Without this
 169                                 option the graph would become extremely large. If set, the
 170                                 horizontal axis starts at the first recorded sample
 171                                 instead of time 0.0.</para></listitem>
 172                         </varlistentry>
 173
 174                         <varlistentry>
 175                                 <term><option>-F</option></term>
 176                                 <term><option>--filter</option></term>
 177                                 <listitem><para>Disable filtering of tasks that
 178                                 did not contribute significantly to the boot. Processes
 179                                 that are too short-lived (only seen in one sample) or
 180                                 that do not consume any significant CPU time (less than
 181                                 0.001 s) will not be displayed in the output graph.
 182                                 </para></listitem>
 183                         </varlistentry>
 184
 185                         <varlistentry>
 186                                 <term><option>-o</option></term>
 187                                 <term><option>--output <replaceable>path</replaceable></option></term>
 188                                 <listitem><para>Specify the output folder for the
 189                                 graphs. By default, bootchart writes the graphs to
 190                                 <filename>/run/log</filename>.</para></listitem>
 191                         </varlistentry>
 192
 193                         <varlistentry>
 194                                 <term><option>-i</option></term>
 195                                 <term><option>--init <replaceable>path</replaceable></option></term>
 196                                 <listitem><para>Use this init binary. Defaults to
 197                                 <command>/sbin/init</command>.
 198                                 </para></listitem>
 199                         </varlistentry>
 200
 201                         <varlistentry>
 202                                 <term><option>-p</option></term>
 203                                 <term><option>--pss</option></term>
 204                                 <listitem><para>Enable logging and graphing
 205                                 of processes' PSS (Proportional Set Size)
 206                                 memory consumption. See <filename>filesystems/proc.txt</filename>
 207                                 in the kernel documentation for an
 208                                 explanation of this field.
 209                                 </para></listitem>
 210                         </varlistentry>
 211
 212                         <varlistentry>
 213                                 <term><option>-e</option></term>
 214                                 <term><option>--entropy</option></term>
 215                                 <listitem><para>Enable logging and graphing
 216                                 of the kernel random entropy pool size.</para></listitem>
 217                         </varlistentry>
 218
 219                         <varlistentry>
 220                                 <term><option>-x</option></term>
 221                                 <term><option>--scale-x <replaceable>N</replaceable></option></term>
 222                                 <listitem><para>Horizontal scaling factor for all variable
 223                                 graph components.</para></listitem>
 224                         </varlistentry>
 225
 226                         <varlistentry>
 227                                 <term><option>-y</option></term>
 228                                 <term><option>--scale-y <replaceable>N</replaceable></option></term>
 229                                 <listitem><para>Vertical scaling factor for all variable
 230                                 graph components.</para></listitem>
 231                         </varlistentry>
 232
 233                 </variablelist>
 234
 235
 236         </refsect1>
 237
 238         <refsect1>
 239                 <title>Output</title>
 240
 241                 <para><command>systemd-bootchart</command> generates SVG graphs. In order to render those
 242                 on a graphical display any SVG capable viewer can be used. It should be
 243                 noted that the SVG render engines in most browsers (including Chrome
 244                 and Firefox) are many times faster than dedicated graphical applications
 245                 like Gimp and Inkscape.  Just point your browser at <ulink url="file:///run/log/" />!
 246                 </para>
 247         </refsect1>
 248
 249         <refsect1>
 250                 <title>History</title>
 251
 252                 <para>This version of bootchart was implemented from
 253                 scratch, but is inspired by former bootchart
 254                 incantations:</para>
 255
 256                 <variablelist>
 257                         <varlistentry>
 258                                 <term><emphasis>Original bash</emphasis></term>
 259                                 <listitem><para>The original bash/shell code implemented
 260                                 bootchart. This version created a compressed tarball for
 261                                 processing with external applications. This version did
 262                                 not graph anything, only generated data.</para></listitem>
 263                         </varlistentry>
 264
 265                         <varlistentry>
 266                                 <term><emphasis>Ubuntu C Implementation</emphasis></term>
 267                                 <listitem><para>This version replaced the shell version with
 268                                 a fast and efficient data logger, but also did not graph
 269                                 the data.</para></listitem>
 270                         </varlistentry>
 271
 272                         <varlistentry>
 273                                 <term><emphasis>Java bootchart</emphasis></term>
 274                                 <listitem><para>This was the original graphing application
 275                                 for charting the data, written in java.</para></listitem>
 276                         </varlistentry>
 277
 278                         <varlistentry>
 279                                 <term><emphasis>pybootchartgui.py</emphasis></term>
 280                                 <listitem><para>pybootchart created a graph from the data
 281                                 collected by either the bash or C version.</para></listitem>
 282                         </varlistentry>
 283                 </variablelist>
 284
 285                 <para>The version of bootchart you are using now combines both the data
 286                 collection and the charting into a single application, making it more
 287                 efficient and simpler. There are no longer any timing issues with the data
 288                 collector and the grapher, as the graphing cannot be run until the data
 289                 has been collected. Also, the data kept in memory is reduced to the absolute
 290                 minimum needed.</para>
 291
 292         </refsect1>
 293
 294         <refsect1>
 295                 <title>See Also</title>
 296                 <para>
 297                         <citerefentry><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 298                 </para>
 299         </refsect1>
 300
 301         <refsect1>
 302                 <title>Bugs</title>
 303                 <para>For bugs, please contact the author and current maintainer:</para>
 304                 <simplelist>
 305                         <member>Auke Kok <email>auke-jan.h.kok@intel.com</email></member>
 306                 </simplelist>
 307         </refsect1>
 308
 309 </refentry>