[thirdparty/systemd.git] / man / systemd-bootchart.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2012 Intel Corporation

  Authors:
    Auke Kok <auke-jan.h.kok@intel.com>
    William Giokas <1007380@gmail.com>

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd-bootchart" conditional='ENABLE_BOOTCHART'>
        <refentryinfo>
                <title>systemd-bootchart</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Auke</firstname>
                                <surname>Kok</surname>
                                <email>auke-jan.h.kok@intel.com</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd-bootchart</refentrytitle>
                <manvolnum>1</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd-bootchart</refname>
                <refpurpose>Boot performance graphing tool</refpurpose>
        </refnamediv>

        <refsect1>
                <title>Description</title>
                <para>
                        <command>systemd-bootchart</command> is a
                        tool, usually run at system startup, that
                        collects the CPU load, disk load, memory
                        usage, as well as per-process information from
                        a running system. Collected results are output
                        as an SVG graph. Normally, systemd-bootchart
                        is invoked by the kernel by passing
                        <option>init=<filename>/usr/lib/systemd/systemd-bootchart</filename></option>
                        on the kernel commandline. systemd-bootchart will then
                        fork the real init off to resume normal system
                        startup, while monitoring and logging startup
                        information in the background.
                </para>
                <para>
                        After collecting a certain amount of data
                        (usually 15-30 seconds, default 20 s) the
                        logging stops and a graph is generated from
                        the logged information. This graph contains
                        vital clues as to which resources are being used,
                        in which order, and where possible problems
                        exist in the startup sequence of the system.
                        It is essentially a more detailed version of
                        the <command>systemd-analyze</command>
                        <command>plot</command> function.
                </para>
                <para>
                        Of course, bootchart can also be used at any
                        moment in time to collect and graph some data
                        for an amount of time. It is
                        recommended to use the <option>--rel</option>
                        switch in this case.
                </para>
                <para>
                        Bootchart does not require root privileges,
                        and will happily run as a normal user.
                </para>
                <para>
                        Bootchart graphs are by default written
                        time-stamped in <filename>/run/log</filename>
                        and saved to the journal with
                        <varname>MESSAGE_ID=9f26aa562cf440c2b16c773d0479b518</varname>.
                        Journal field <varname>BOOTCHART=</varname> contains
                        the bootchart in SVG format.
                </para>

        </refsect1>

        <refsect1>
                <title>Invocation</title>

                <para><command>systemd-bootchart</command> can be invoked in several different ways:</para>

                <variablelist>

                        <varlistentry>
                                <term><emphasis>Kernel invocation</emphasis></term>
                                <listitem><para>The kernel can invoke
                                <command>systemd-bootchart</command>
                                instead of the init process. In turn,
                                <command>systemd-bootchart</command>
                                will invoke <command>/sbin/init</command>.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><emphasis>Started as a standalone program</emphasis></term>
                                <listitem><para>One can execute
                                <command>systemd-bootchart</command>
                                as normal application from the
                                commandline. In this mode it is highly
                                recommended to pass the
                                <option>-r</option> flag in order to
                                not graph the time elapsed since boot
                                and before systemd-bootchart was
                                started, as it may result in extremely
                                large graphs.  </para></listitem>
                        </varlistentry>
                </variablelist>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>These options can also be set in the
                <filename>/etc/systemd/bootchart.conf</filename>
                file. See
                <citerefentry><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                </para>

                <variablelist>

                        <varlistentry>
                               <term><option>-h</option></term>
                               <term><option>--help</option></term>
                               <listitem><para>Prints a short help text and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-n</option></term>
                                <term><option>--sample <replaceable>N</replaceable></option></term>
                                <listitem><para>Specify the number of
                                samples, <replaceable>N</replaceable>,
                                to record. Samples will be recorded at
                                intervals defined with <option>--freq</option>.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-f</option></term>
                                <term><option>--freq <replaceable>f</replaceable></option></term>
                                <listitem><para>Specify the sample log
                                frequency, a positive real <replaceable>f</replaceable>, in Hz.
                                Most systems can cope with values up to 25-50 without
                                creating too much overhead.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-r</option></term>
                                <term><option>--rel</option></term>
                                <listitem><para>Use relative times instead of absolute
                                times. This is useful for using bootchart at post-boot
                                time to profile an already booted system. Without this
                                option the graph would become extremely large. If set, the
                                horizontal axis starts at the first recorded sample
                                instead of time 0.0.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-F</option></term>
                                <term><option>--no-filter</option></term>
                                <listitem><para>Disable filtering of tasks that
                                did not contribute significantly to the boot. Processes
                                that are too short-lived (only seen in one sample) or
                                that do not consume any significant CPU time (less than
                                0.001 s) will not be displayed in the output graph.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-C</option></term>
                                <term><option>--cmdline</option></term>
                                <listitem><para>Display the full command line with arguments of processes,
                                instead of only the process name.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-o</option></term>
                                <term><option>--output <replaceable>path</replaceable></option></term>
                                <listitem><para>Specify the output directory for the
                                graphs. By default, bootchart writes the graphs to
                                <filename>/run/log</filename>.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-i</option></term>
                                <term><option>--init <replaceable>path</replaceable></option></term>
                                <listitem><para>Use this init binary. Defaults to
                                <command>/sbin/init</command>.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-p</option></term>
                                <term><option>--pss</option></term>
                                <listitem><para>Enable logging and graphing
                                of processes' PSS (Proportional Set Size)
                                memory consumption. See <filename>filesystems/proc.txt</filename>
                                in the kernel documentation for an
                                explanation of this field.
                                </para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-e</option></term>
                                <term><option>--entropy</option></term>
                                <listitem><para>Enable logging and graphing
                                of the kernel random entropy pool size.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-x</option></term>
                                <term><option>--scale-x <replaceable>N</replaceable></option></term>
                                <listitem><para>Horizontal scaling factor for all variable
                                graph components.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-y</option></term>
                                <term><option>--scale-y <replaceable>N</replaceable></option></term>
                                <listitem><para>Vertical scaling factor for all variable
                                graph components.</para></listitem>
                        </varlistentry>

                </variablelist>


        </refsect1>

        <refsect1>
                <title>Output</title>

                <para><command>systemd-bootchart</command> generates SVG graphs. In order to render those
                on a graphical display any SVG capable viewer can be used. It should be
                noted that the SVG render engines in most browsers (including Chrome
                and Firefox) are many times faster than dedicated graphical applications
                like Gimp and Inkscape.  Just point your browser at <ulink url="file:///run/log/" />!
                </para>
        </refsect1>

        <refsect1>
                <title>History</title>

                <para>This version of bootchart was implemented from
                scratch, but is inspired by former bootchart
                incantations:</para>

                <variablelist>
                        <varlistentry>
                                <term><emphasis>Original bash</emphasis></term>
                                <listitem><para>The original bash/shell code implemented
                                bootchart. This version created a compressed tarball for
                                processing with external applications. This version did
                                not graph anything, only generated data.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><emphasis>Ubuntu C Implementation</emphasis></term>
                                <listitem><para>This version replaced the shell version with
                                a fast and efficient data logger, but also did not graph
                                the data.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><emphasis>Java bootchart</emphasis></term>
                                <listitem><para>This was the original graphing application
                                for charting the data, written in java.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><emphasis>pybootchartgui.py</emphasis></term>
                                <listitem><para>pybootchart created a graph from the data
                                collected by either the bash or C version.</para></listitem>
                        </varlistentry>
                </variablelist>

                <para>The version of bootchart you are using now combines both the data
                collection and the charting into a single application, making it more
                efficient and simpler. There are no longer any timing issues with the data
                collector and the grapher, as the graphing cannot be run until the data
                has been collected. Also, the data kept in memory is reduced to the absolute
                minimum needed.</para>

        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                </para>
        </refsect1>

        <refsect1>
                <title>Bugs</title>
                <para>systemd-bootchart does not get the model information for the hard drive
                unless the root device is specified with <code>root=/dev/sdxY</code>. Using
                UUIDs or PARTUUIDs will boot fine, but the hard drive model will not be
                added to the chart.</para>
                <para>For bugs, please contact the author and current maintainer:</para>
                <simplelist>
                        <member>Auke Kok <email>auke-jan.h.kok@intel.com</email></member>
                </simplelist>
        </refsect1>

</refentry>
Commit	Line	Data
83fdc450 AK	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>
57976066	13	William Giokas <1007380@gmail.com>
83fdc450 AK	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
56ba3c78	29	<refentry id="systemd-bootchart" conditional='ENABLE_BOOTCHART'>
83fdc450 AK	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>
f1c24fea	51	<refpurpose>Boot performance graphing tool</refpurpose>
83fdc450 AK	52	</refnamediv>
	53
	54	<refsect1>
	55	<title>Description</title>
f1c24fea ZJS	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
e7ecdfc1 ZJS	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.
f1c24fea	100	</para>
83fdc450 AK	101
	102	</refsect1>
	103
	104	<refsect1>
	105	<title>Invocation</title>
	106
f1c24fea	107	<para><command>systemd-bootchart</command> can be invoked in several different ways:</para>
83fdc450	108
ccc9a4f9	109	<variablelist>
83fdc450 AK	110
83fdc450 AK	111	<varlistentry>
c3fec671	112	<term><emphasis>Kernel invocation</emphasis></term>
f1c24fea ZJS	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>
83fdc450 AK	119	</varlistentry>
	120
	121	<varlistentry>
c3fec671	122	<term><emphasis>Started as a standalone program</emphasis></term>
f1c24fea ZJS	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>
83fdc450 AK	133	</varlistentry>
	134	</variablelist>
	135	</refsect1>
	136
	137	<refsect1>
	138	<title>Options</title>
	139
f1c24fea ZJS	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>
c3fec671 WG	145
c3fec671 WG	146	<variablelist>
57976066	147
83688684 NC	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
57976066 WG	154	<varlistentry>
57976066 WG	155	<term><option>-n</option></term>
f1c24fea ZJS	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>
57976066 WG	162	</varlistentry>
	163
	164	<varlistentry>
	165	<term><option>-f</option></term>
f1c24fea ZJS	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
c3fec671	170	creating too much overhead.</para></listitem>
57976066 WG	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
f1c24fea ZJS	178	time to profile an already booted system. Without this
f1c24fea ZJS	179	option the graph would become extremely large. If set, the
57976066	180	horizontal axis starts at the first recorded sample
f1c24fea	181	instead of time 0.0.</para></listitem>
57976066 WG	182	</varlistentry>
	183
	184	<varlistentry>
	185	<term><option>-F</option></term>
6d267991	186	<term><option>--no-filter</option></term>
f1c24fea	187	<listitem><para>Disable filtering of tasks that
57976066 WG	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
f1c24fea	191	0.001 s) will not be displayed in the output graph.
57976066 WG	192	</para></listitem>
	193	</varlistentry>
	194
78da2cd9 HH	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
57976066 WG	203	<varlistentry>
57976066 WG	204	<term><option>-o</option></term>
f1c24fea	205	<term><option>--output <replaceable>path</replaceable></option></term>
fbce1139	206	<listitem><para>Specify the output directory for the
f1c24fea	207	graphs. By default, bootchart writes the graphs to
895aeb27	208	<filename>/run/log</filename>.</para></listitem>
57976066 WG	209	</varlistentry>
	210
	211	<varlistentry>
	212	<term><option>-i</option></term>
f1c24fea ZJS	213	<term><option>--init <replaceable>path</replaceable></option></term>
	214	<listitem><para>Use this init binary. Defaults to
	215	<command>/sbin/init</command>.
57976066 WG	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
f1c24fea ZJS	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>
57976066 WG	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>
f1c24fea	239	<term><option>--scale-x <replaceable>N</replaceable></option></term>
57976066 WG	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>
f1c24fea	246	<term><option>--scale-y <replaceable>N</replaceable></option></term>
57976066 WG	247	<listitem><para>Vertical scaling factor for all variable
	248	graph components.</para></listitem>
	249	</varlistentry>
	250
	251	</variablelist>
	252
	253
83fdc450 AK	254	</refsect1>
	255
	256	<refsect1>
	257	<title>Output</title>
	258
f1c24fea	259	<para><command>systemd-bootchart</command> generates SVG graphs. In order to render those
1959c6ce	260	on a graphical display any SVG capable viewer can be used. It should be
83fdc450 AK	261	noted that the SVG render engines in most browsers (including Chrome
83fdc450 AK	262	and Firefox) are many times faster than dedicated graphical applications
f1c24fea	263	like Gimp and Inkscape. Just point your browser at <ulink url="file:///run/log/" />!
c3fec671 WG	264	</para>
	265	</refsect1>
	266
	267	<refsect1>
	268	<title>History</title>
	269
f1c24fea ZJS	270	<para>This version of bootchart was implemented from
	271	scratch, but is inspired by former bootchart
	272	incantations:</para>
c3fec671 WG	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
c3fec671 WG	310	</refsect1>
	311
	312	<refsect1>
	313	<title>See Also</title>
	314	<para>
	315	<citerefentry><refentrytitle>bootchart.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
83fdc450 AK	316	</para>
	317	</refsect1>
	318
	319	<refsect1>
c3fec671	320	<title>Bugs</title>
1e447e0a WG	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>
f1c24fea ZJS	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>
83fdc450 AK	329	</refsect1>
	330
	331	</refentry>