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