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           xmlns:xi="http://www.w3.org/2001/XInclude">
  31
  32         <refentryinfo>
  33                 <title>systemd-bootchart</title>
  34                 <productname>systemd</productname>
  35
  36                 <authorgroup>
  37                         <author>
  38                                 <contrib>Developer</contrib>
  39                                 <firstname>Auke</firstname>
  40                                 <surname>Kok</surname>
  41                                 <email>auke-jan.h.kok@intel.com</email>
  42                         </author>
  43                 </authorgroup>
  44         </refentryinfo>
  45
  46         <refmeta>
  47                 <refentrytitle>systemd-bootchart</refentrytitle>
  48                 <manvolnum>1</manvolnum>
  49         </refmeta>
  50
  51         <refnamediv>
  52                 <refname>systemd-bootchart</refname>
  53                 <refpurpose>Boot performance graphing tool</refpurpose>
  54         </refnamediv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58                 <para>
  59                         <command>systemd-bootchart</command> is a
  60                         tool, usually run at system startup, that
  61                         collects the CPU load, disk load, memory
  62                         usage, as well as per-process information from
  63                         a running system. Collected results are output
  64                         as an SVG graph. Normally, systemd-bootchart
  65                         is invoked by the kernel by passing
  66                         <option>init=<filename>/usr/lib/systemd/systemd-bootchart</filename></option>
  67                         on the kernel command line. systemd-bootchart will then
  68                         fork the real init off to resume normal system
  69                         startup, while monitoring and logging startup
  70                         information in the background.
  71                 </para>
  72                 <para>
  73                         After collecting a certain amount of data
  74                         (usually 15-30 seconds, default 20 s) the
  75                         logging stops and a graph is generated from
  76                         the logged information. This graph contains
  77                         vital clues as to which resources are being used,
  78                         in which order, and where possible problems
  79                         exist in the startup sequence of the system.
  80                         It is essentially a more detailed version of
  81                         the <command>systemd-analyze plot</command>
  82                         function.
  83                 </para>
  84                 <para>
  85                         Of course, bootchart can also be used at any
  86                         moment in time to collect and graph some data
  87                         for an amount of time. It is
  88                         recommended to use the <option>--rel</option>
  89                         switch in this case.
  90                 </para>
  91                 <para>
  92                         Bootchart does not require root privileges,
  93                         and will happily run as a normal user.
  94                 </para>
  95                 <para>
  96                         Bootchart graphs are by default written
  97                         time-stamped in <filename>/run/log</filename>
  98                         and saved to the journal with
  99                         <varname>MESSAGE_ID=9f26aa562cf440c2b16c773d0479b518</varname>.
 100                         Journal field <varname>BOOTCHART=</varname> contains
 101                         the bootchart in SVG format.
 102                 </para>
 103
 104         </refsect1>
 105
 106         <refsect1>
 107                 <title>Invocation</title>
 108
 109                 <para><command>systemd-bootchart</command> can be invoked in several different ways:</para>
 110
 111                 <variablelist>
 112
 113                         <varlistentry>
 114                                 <term><emphasis>Kernel invocation</emphasis></term>
 115                                 <listitem><para>The kernel can invoke
 116                                 <command>systemd-bootchart</command>
 117                                 instead of the init process. In turn,
 118                                 <command>systemd-bootchart</command>
 119                                 will invoke <command>/sbin/init</command>.
 120                                 </para></listitem>
 121                         </varlistentry>
 122
 123                         <varlistentry>
 124                                 <term><emphasis>Started as a standalone program</emphasis></term>
 125                                 <listitem><para>One can execute
 126                                 <command>systemd-bootchart</command>
 127                                 as normal application from the
 128                                 command line. In this mode it is highly
 129                                 recommended to pass the
 130                                 <option>-r</option> flag in order to
 131                                 not graph the time elapsed since boot
 132                                 and before systemd-bootchart was
 133                                 started, as it may result in extremely
 134                                 large graphs. The time elapsed since boot
 135                                 might also include any time that the system
 136                                 was suspended.</para></listitem>
 137                         </varlistentry>
 138                 </variablelist>
 139         </refsect1>
 140
 141         <refsect1>
 142                 <title>Options</title>
 143
 144                 <para>These options can also be set in the
 145                 <filename>/etc/systemd/bootchart.conf</filename>
 146                 file. See
 147                 <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 148                 </para>
 149
 150                 <variablelist>
 151                         <xi:include href="standard-options.xml" xpointer="help" />
 152
 153                         <varlistentry>
 154                                 <term><option>-n</option></term>
 155                                 <term><option>--sample <replaceable>N</replaceable></option></term>
 156                                 <listitem><para>Specify the number of
 157                                 samples, <replaceable>N</replaceable>,
 158                                 to record. Samples will be recorded at
 159                                 intervals defined with <option>--freq</option>.
 160                                 </para></listitem>
 161                         </varlistentry>
 162
 163                         <varlistentry>
 164                                 <term><option>-f</option></term>
 165                                 <term><option>--freq <replaceable>f</replaceable></option></term>
 166                                 <listitem><para>Specify the sample log
 167                                 frequency, a positive real <replaceable>f</replaceable>, in Hz.
 168                                 Most systems can cope with values up to 25-50 without
 169                                 creating too much overhead.</para></listitem>
 170                         </varlistentry>
 171
 172                         <varlistentry>
 173                                 <term><option>-r</option></term>
 174                                 <term><option>--rel</option></term>
 175                                 <listitem><para>Use relative times instead of absolute
 176                                 times. This is useful for using bootchart at post-boot
 177                                 time to profile an already booted system. Without this
 178                                 option the graph would become extremely large. If set, the
 179                                 horizontal axis starts at the first recorded sample
 180                                 instead of time 0.0.</para></listitem>
 181                         </varlistentry>
 182
 183                         <varlistentry>
 184                                 <term><option>-F</option></term>
 185                                 <term><option>--no-filter</option></term>
 186                                 <listitem><para>Disable filtering of tasks that
 187                                 did not contribute significantly to the boot. Processes
 188                                 that are too short-lived (only seen in one sample) or
 189                                 that do not consume any significant CPU time (less than
 190                                 0.001 s) will not be displayed in the output graph.
 191                                 </para></listitem>
 192                         </varlistentry>
 193
 194                         <varlistentry>
 195                                 <term><option>-C</option></term>
 196                                 <term><option>--cmdline</option></term>
 197                                 <listitem><para>Display the full command line with arguments of processes,
 198                                 instead of only the process name.
 199                                 </para></listitem>
 200                         </varlistentry>
 201
 202                         <varlistentry>
 203                                 <term><option>-g</option></term>
 204                                 <term><option>--control-group</option></term>
 205                                 <listitem><para>Display process control group
 206                                 </para></listitem>
 207                         </varlistentry>
 208
 209                         <varlistentry>
 210                                 <term><option>-o</option></term>
 211                                 <term><option>--output <replaceable>path</replaceable></option></term>
 212                                 <listitem><para>Specify the output directory for the
 213                                 graphs. By default, bootchart writes the graphs to
 214                                 <filename>/run/log</filename>.</para></listitem>
 215                         </varlistentry>
 216
 217                         <varlistentry>
 218                                 <term><option>-i</option></term>
 219                                 <term><option>--init <replaceable>path</replaceable></option></term>
 220                                 <listitem><para>Use this init binary. Defaults to
 221                                 <command>/sbin/init</command>.
 222                                 </para></listitem>
 223                         </varlistentry>
 224
 225                         <varlistentry>
 226                                 <term><option>-p</option></term>
 227                                 <term><option>--pss</option></term>
 228                                 <listitem><para>Enable logging and graphing
 229                                 of processes' PSS (Proportional Set Size)
 230                                 memory consumption. See <filename>filesystems/proc.txt</filename>
 231                                 in the kernel documentation for an
 232                                 explanation of this field.
 233                                 </para></listitem>
 234                         </varlistentry>
 235
 236                         <varlistentry>
 237                                 <term><option>-e</option></term>
 238                                 <term><option>--entropy</option></term>
 239                                 <listitem><para>Enable logging and graphing
 240                                 of the kernel random entropy pool size.</para></listitem>
 241                         </varlistentry>
 242
 243                         <varlistentry>
 244                                 <term><option>-x</option></term>
 245                                 <term><option>--scale-x <replaceable>N</replaceable></option></term>
 246                                 <listitem><para>Horizontal scaling factor for all variable
 247                                 graph components.</para></listitem>
 248                         </varlistentry>
 249
 250                         <varlistentry>
 251                                 <term><option>-y</option></term>
 252                                 <term><option>--scale-y <replaceable>N</replaceable></option></term>
 253                                 <listitem><para>Vertical scaling factor for all variable
 254                                 graph components.</para></listitem>
 255                         </varlistentry>
 256
 257                 </variablelist>
 258
 259
 260         </refsect1>
 261
 262         <refsect1>
 263                 <title>Output</title>
 264
 265                 <para><command>systemd-bootchart</command> generates SVG graphs. In order to render those
 266                 on a graphical display any SVG capable viewer can be used. It should be
 267                 noted that the SVG render engines in most browsers (including Chrome
 268                 and Firefox) are many times faster than dedicated graphical applications
 269                 like Gimp and Inkscape.  Just point your browser at <ulink url="file:///run/log/" />!
 270                 </para>
 271         </refsect1>
 272
 273         <refsect1>
 274                 <title>History</title>
 275
 276                 <para>This version of bootchart was implemented from
 277                 scratch, but is inspired by former bootchart
 278                 incantations:</para>
 279
 280                 <variablelist>
 281                         <varlistentry>
 282                                 <term><emphasis>Original bash</emphasis></term>
 283                                 <listitem><para>The original bash/shell code implemented
 284                                 bootchart. This version created a compressed tarball for
 285                                 processing with external applications. This version did
 286                                 not graph anything, only generated data.</para></listitem>
 287                         </varlistentry>
 288
 289                         <varlistentry>
 290                                 <term><emphasis>Ubuntu C Implementation</emphasis></term>
 291                                 <listitem><para>This version replaced the shell version with
 292                                 a fast and efficient data logger, but also did not graph
 293                                 the data.</para></listitem>
 294                         </varlistentry>
 295
 296                         <varlistentry>
 297                                 <term><emphasis>Java bootchart</emphasis></term>
 298                                 <listitem><para>This was the original graphing application
 299                                 for charting the data, written in java.</para></listitem>
 300                         </varlistentry>
 301
 302                         <varlistentry>
 303                                 <term><emphasis>pybootchartgui.py</emphasis></term>
 304                                 <listitem><para>pybootchart created a graph from the data
 305                                 collected by either the bash or C version.</para></listitem>
 306                         </varlistentry>
 307                 </variablelist>
 308
 309                 <para>The version of bootchart you are using now combines both the data
 310                 collection and the charting into a single application, making it more
 311                 efficient and simpler. There are no longer any timing issues with the data
 312                 collector and the grapher, as the graphing cannot be run until the data
 313                 has been collected. Also, the data kept in memory is reduced to the absolute
 314                 minimum needed.</para>
 315
 316         </refsect1>
 317
 318         <refsect1>
 319                 <title>See Also</title>
 320                 <para>
 321                         <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 322                 </para>
 323         </refsect1>
 324
 325         <refsect1>
 326                 <title>Bugs</title>
 327                 <para>systemd-bootchart does not get the model information for the hard drive
 328                 unless the root device is specified with <code>root=/dev/sdxY</code>. Using
 329                 UUIDs or PARTUUIDs will boot fine, but the hard drive model will not be
 330                 added to the chart.</para>
 331                 <para>For bugs, please contact the author and current maintainer:</para>
 332                 <simplelist>
 333                         <member>Auke Kok <email>auke-jan.h.kok@intel.com</email></member>
 334                 </simplelist>
 335         </refsect1>
 336
 337 </refentry>