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