1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2012 Intel Corporation
11 Auke Kok <auke-jan.h.kok@intel.com>
12 William Giokas <1007380@gmail.com>
14 systemd is free software; you can redistribute it and/or modify it
15 under the terms of the GNU Lesser General Public License as published by
16 the Free Software Foundation; either version 2.1 of the License, or
17 (at your option) any later version.
19 systemd is distributed in the hope that it will be useful, but
20 WITHOUT ANY WARRANTY; without even the implied warranty of
21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 Lesser General Public License for more details.
24 You should have received a copy of the GNU Lesser General Public License
25 along with systemd; If not, see <http://www.gnu.org/licenses/>.
28 <refentry id="systemd-bootchart" conditional='ENABLE_BOOTCHART'
29 xmlns:xi="http://www.w3.org/2001/XInclude">
32 <title>systemd-bootchart</title>
33 <productname>systemd</productname>
37 <contrib>Developer</contrib>
38 <firstname>Auke</firstname>
39 <surname>Kok</surname>
40 <email>auke-jan.h.kok@intel.com</email>
46 <refentrytitle>systemd-bootchart</refentrytitle>
47 <manvolnum>1</manvolnum>
51 <refname>systemd-bootchart</refname>
52 <refpurpose>Boot performance graphing tool</refpurpose>
56 <title>Description</title>
58 <command>systemd-bootchart</command> is a tool, usually run at
59 system startup, that collects the CPU load, disk load, memory
60 usage, as well as per-process information from a running system.
61 Collected results are output as an SVG graph. Normally,
62 systemd-bootchart is invoked by the kernel by passing
63 <option>init=<filename>/usr/lib/systemd/systemd-bootchart</filename></option>
64 on the kernel command line. systemd-bootchart will then fork the
65 real init off to resume normal system startup, while monitoring
66 and logging startup information in the background.
69 After collecting a certain amount of data (usually 15-30
70 seconds, default 20 s) the logging stops and a graph is
71 generated from the logged information. This graph contains vital
72 clues as to which resources are being used, in which order, and
73 where possible problems exist in the startup sequence of the
74 system. It is essentially a more detailed version of the
75 <command>systemd-analyze plot</command> function.
78 Of course, bootchart can also be used at any moment in time to
79 collect and graph some data for an amount of time. It is
80 recommended to use the <option>--rel</option> switch in this
84 Bootchart does not require root privileges, and will happily run
88 Bootchart graphs are by default written time-stamped in
89 <filename>/run/log</filename> and saved to the journal with
90 <varname>MESSAGE_ID=9f26aa562cf440c2b16c773d0479b518</varname>.
91 Journal field <varname>BOOTCHART=</varname> contains the
92 bootchart in SVG format.
98 <title>Invocation</title>
100 <para><command>systemd-bootchart</command> can be invoked in several different ways:</para>
105 <term><emphasis>Kernel invocation</emphasis></term>
106 <listitem><para>The kernel can invoke
107 <command>systemd-bootchart</command> instead of the init
108 process. In turn, <command>systemd-bootchart</command> will
109 invoke <command>/usr/lib/systemd/systemd</command>.
114 <term><emphasis>Started as a standalone program</emphasis></term>
115 <listitem><para>One can execute
116 <command>systemd-bootchart</command> as normal application
117 from the command line. In this mode it is highly recommended
118 to pass the <option>-r</option> flag in order to not graph the
119 time elapsed since boot and before systemd-bootchart was
120 started, as it may result in extremely large graphs. The time
121 elapsed since boot might also include any time that the system
122 was suspended.</para></listitem>
128 <title>Options</title>
130 <para>These options can also be set in the
131 <filename>/etc/systemd/bootchart.conf</filename> file. See
132 <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
136 <xi:include href="standard-options.xml" xpointer="help" />
139 <term><option>-n</option></term>
140 <term><option>--sample <replaceable>N</replaceable></option></term>
141 <listitem><para>Specify the number of samples,
142 <replaceable>N</replaceable>, to record. Samples will be
143 recorded at intervals defined with <option>--freq</option>.
148 <term><option>-f</option></term>
149 <term><option>--freq <replaceable>f</replaceable></option></term>
150 <listitem><para>Specify the sample log frequency, a positive
151 real <replaceable>f</replaceable>, in Hz. Most systems can
152 cope with values up to 25-50 without creating too much
153 overhead.</para></listitem>
157 <term><option>-r</option></term>
158 <term><option>--rel</option></term>
159 <listitem><para>Use relative times instead of absolute times.
160 This is useful for using bootchart at post-boot time to
161 profile an already booted system. Without this option the
162 graph would become extremely large. If set, the horizontal
163 axis starts at the first recorded sample instead of time
164 0.0.</para></listitem>
168 <term><option>-F</option></term>
169 <term><option>--no-filter</option></term>
170 <listitem><para>Disable filtering of tasks that did not
171 contribute significantly to the boot. Processes that are too
172 short-lived (only seen in one sample) or that do not consume
173 any significant CPU time (less than 0.001 s) will not be
174 displayed in the output graph. </para></listitem>
178 <term><option>-C</option></term>
179 <term><option>--cmdline</option></term>
180 <listitem><para>Display the full command line with arguments
181 of processes, instead of only the process name.
186 <term><option>-g</option></term>
187 <term><option>--control-group</option></term>
188 <listitem><para>Display process control group
193 <term><option>-o</option></term>
194 <term><option>--output <replaceable>path</replaceable></option></term>
195 <listitem><para>Specify the output directory for the graphs.
196 By default, bootchart writes the graphs to
197 <filename>/run/log</filename>.</para></listitem>
201 <term><option>-i</option></term>
202 <term><option>--init <replaceable>path</replaceable></option></term>
203 <listitem><para>Use this init binary. Defaults to
204 <command>/usr/lib/systemd/systemd</command>.
209 <term><option>-p</option></term>
210 <term><option>--pss</option></term>
211 <listitem><para>Enable logging and graphing of processes' PSS
212 (Proportional Set Size) memory consumption. See
213 <filename>filesystems/proc.txt</filename> in the kernel
214 documentation for an explanation of this field.
219 <term><option>-e</option></term>
220 <term><option>--entropy</option></term>
221 <listitem><para>Enable logging and graphing of the kernel
222 random entropy pool size.</para></listitem>
226 <term><option>-x</option></term>
227 <term><option>--scale-x <replaceable>N</replaceable></option></term>
228 <listitem><para>Horizontal scaling factor for all variable
229 graph components.</para></listitem>
233 <term><option>-y</option></term>
234 <term><option>--scale-y <replaceable>N</replaceable></option></term>
235 <listitem><para>Vertical scaling factor for all variable graph
236 components.</para></listitem>
245 <title>Output</title>
247 <para><command>systemd-bootchart</command> generates SVG graphs.
248 In order to render those on a graphical display any SVG capable
249 viewer can be used. It should be noted that the SVG render engines
250 in most browsers (including Chrome and Firefox) are many times
251 faster than dedicated graphical applications like Gimp and
252 Inkscape. Just point your browser at
253 <ulink url="file:///run/log/" />!
258 <title>History</title>
260 <para>This version of bootchart was implemented from scratch, but
261 is inspired by former bootchart incantations:</para>
265 <term><emphasis>Original bash</emphasis></term>
266 <listitem><para>The original bash/shell code implemented
267 bootchart. This version created a compressed tarball for
268 processing with external applications. This version did not
269 graph anything, only generated data.</para></listitem>
273 <term><emphasis>Ubuntu C Implementation</emphasis></term>
274 <listitem><para>This version replaced the shell version with a
275 fast and efficient data logger, but also did not graph the
276 data.</para></listitem>
280 <term><emphasis>Java bootchart</emphasis></term>
281 <listitem><para>This was the original graphing application for
282 charting the data, written in java.</para></listitem>
286 <term><emphasis>pybootchartgui.py</emphasis></term>
287 <listitem><para>pybootchart created a graph from the data
288 collected by either the bash or C version.</para></listitem>
292 <para>The version of bootchart you are using now combines both the
293 data collection and the charting into a single application, making
294 it more efficient and simpler. There are no longer any timing
295 issues with the data collector and the grapher, as the graphing
296 cannot be run until the data has been collected. Also, the data
297 kept in memory is reduced to the absolute minimum needed.</para>
302 <title>See Also</title>
305 <citerefentry project='man-pages'><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
312 <para>systemd-bootchart does not get the model information for the
313 hard drive unless the root device is specified with
314 <code>root=/dev/sdxY</code>. Using UUIDs or PARTUUIDs will boot
315 fine, but the hard drive model will not be added to the
317 <para>For bugs, please contact the author and current maintainer:</para>
319 <member>Auke Kok <email>auke-jan.h.kok@intel.com</email></member>