chiark / gitweb /
man: improve grammar and word formatting in numerous man pages
[elogind.git] / man / systemd-analyze.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd-analyze">
25
26         <refentryinfo>
27                 <title>systemd-analyze</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                         <author>
38                                 <contrib>Developer</contrib>
39                                 <firstname>Harald</firstname>
40                                 <surname>Hoyer</surname>
41                                 <email>harald@redhat.com</email>
42                         </author>
43                 </authorgroup>
44         </refentryinfo>
45
46         <refmeta>
47                 <refentrytitle>systemd-analyze</refentrytitle>
48                 <manvolnum>1</manvolnum>
49         </refmeta>
50
51         <refnamediv>
52                 <refname>systemd-analyze</refname>
53                 <refpurpose>Analyze system boot-up performance</refpurpose>
54         </refnamediv>
55
56         <refsynopsisdiv>
57                 <cmdsynopsis>
58                         <command>systemd-analyze</command>
59                         <arg choice="opt" rep="repeat">OPTIONS</arg>
60                         <arg>time</arg>
61                 </cmdsynopsis>
62                 <cmdsynopsis>
63                         <command>systemd-analyze</command>
64                         <arg choice="opt" rep="repeat">OPTIONS</arg>
65                         <arg choice="plain">blame</arg>
66                 </cmdsynopsis>
67                 <cmdsynopsis>
68                         <command>systemd-analyze</command>
69                         <arg choice="opt" rep="repeat">OPTIONS</arg>
70                         <arg choice="plain">critical-chain</arg>
71                         <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
72                 </cmdsynopsis>
73                 <cmdsynopsis>
74                         <command>systemd-analyze</command>
75                         <arg choice="opt" rep="repeat">OPTIONS</arg>
76                         <arg choice="plain">plot</arg>
77                         <arg choice="opt">&gt; file.svg</arg>
78                 </cmdsynopsis>
79                 <cmdsynopsis>
80                         <command>systemd-analyze</command>
81                         <arg choice="opt" rep="repeat">OPTIONS</arg>
82                         <arg choice="plain">dot</arg>
83                         <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
84                 </cmdsynopsis>
85         </refsynopsisdiv>
86
87         <refsect1>
88                 <title>Description</title>
89
90                 <para><command>systemd-analyze</command> may be used
91                 to determine system boot-up performance of the current
92                 boot.</para>
93
94                 <para><command>systemd-analyze time</command>
95                 prints the time spent in the kernel before
96                 userspace has been reached, the time spent in the
97                 initial RAM disk (initrd) before normal system
98                 userspace has been reached, and the time normal system
99                 userspace took to initialize. Note that these
100                 measurements simply measure the time passed up to the
101                 point where all system services have been spawned, but
102                 not necessarily until they fully finished
103                 initialization or the disk is idle.</para>
104
105                 <para><command>systemd-analyze blame</command> prints
106                 a list of all running units, ordered by the time they
107                 took to initialize. This information may be used to
108                 optimize boot-up times. Note that the output might be
109                 misleading as the initialization of one service might
110                 be slow simply because it waits for the initialization
111                 of another service to complete.</para>
112
113                 <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command>
114                 prints a tree of the time-critical chain of units
115                 (for each of the specified <replaceable>UNIT</replaceable>s
116                 or for the default target otherwise).
117                 The time after the unit is active or started is printed
118                 after the "@" character. The time the unit takes to
119                 start is printed after the "+" character.
120                 Note that the output might be misleading as the
121                 initialization of one service might depend on socket
122                 activation and because of the parallel execution
123                 of units.</para>
124
125                 <para><command>systemd-analyze plot</command> prints
126                 an SVG graphic detailing which system services have
127                 been started at what time, highlighting the time they
128                 spent on initialization.</para>
129
130                 <para><command>systemd-analyze dot</command> Generate
131                 textual dependency graph description in dot format for
132                 further processing with the GraphViz
133                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
134                 tool. Use a command line like <command>systemd-analyze
135                 dot | dot -Tsvg > systemd.svg</command> to generate a
136                 graphical dependency tree. Unless
137                 <option>--order</option> or <option>--require</option>
138                 is passed, the generated graph will show both ordering
139                 and requirement dependencies. Optional pattern
140                 globbing style specifications
141                 (e.g. <filename>*.target</filename>) may be given at
142                 the end. A unit dependency is included in the graph if
143                 any of these patterns match either the origin or
144                 destination node.</para>
145
146                 <para>If no command is passed, <command>systemd-analyze
147                 time</command> is implied.</para>
148
149         </refsect1>
150
151         <refsect1>
152                 <title>Options</title>
153
154                 <para>The following options are understood:</para>
155
156                 <variablelist>
157                         <varlistentry>
158                                 <term><option>-h</option></term>
159                                 <term><option>--help</option></term>
160
161                                 <listitem><para>Prints a short help
162                                 text and exits.</para></listitem>
163                         </varlistentry>
164
165                         <varlistentry>
166                                 <term><option>--user</option></term>
167
168                                 <listitem><para>Shows performance data
169                                 of user sessions instead of the system
170                                 manager.</para></listitem>
171                         </varlistentry>
172
173                         <varlistentry>
174                                 <term><option>--order</option></term>
175                                 <term><option>--require</option></term>
176
177                                 <listitem><para>When used in
178                                 conjunction with the
179                                 <command>dot</command> command (see
180                                 above), selects which dependencies are
181                                 shown in the dependency graph. If
182                                 <option>--order</option> is passed
183                                 only dependencies of type
184                                 <varname>After=</varname> or
185                                 <varname>Before=</varname> are
186                                 shown. If <option>--require</option>
187                                 is passed only dependencies of type
188                                 <varname>Requires=</varname>,
189                                 <varname>RequiresOverridable=</varname>,
190                                 <varname>Requisite=</varname>,
191                                 <varname>RequisiteOverridable=</varname>,
192                                 <varname>Wants=</varname> and
193                                 <varname>Conflicts=</varname> are
194                                 shown. If neither is passed, this shows
195                                 dependencies of all these
196                                 types.</para></listitem>
197                         </varlistentry>
198
199                         <varlistentry>
200                                 <term><option>--from-pattern=</option></term>
201                                 <term><option>--to-pattern=</option></term>
202
203                                 <listitem><para>When used in
204                                 conjunction with the
205                                 <command>dot</command> command (see
206                                 above), this selects which relationships
207                                 are shown in the dependency graph.
208                                 They both require
209                                 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
210                                 patterns as arguments, which are
211                                 matched against left-hand and
212                                 right-hand, respectively, nodes of a
213                                 relationship. Each of these can be
214                                 used more than once, which means a
215                                 unit name must match one of the given
216                                 values.</para></listitem>
217                         </varlistentry>
218
219                         <varlistentry>
220                                 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
221
222                                 <listitem><para>When used in conjunction
223                                 with the <command>critical-chain</command>
224                                 command (see above), also show units, which
225                                 finished <replaceable>timespan</replaceable> earlier, than the
226                                 latest unit in the same level. The unit of
227                                 <replaceable>timespan</replaceable> is seconds
228                                 unless specified with a different unit,
229                                 e.g. "50ms".</para></listitem>
230                         </varlistentry>
231                 </variablelist>
232
233         </refsect1>
234
235         <refsect1>
236                 <title>Exit status</title>
237
238                 <para>On success 0 is returned, a non-zero failure
239                 code otherwise.</para>
240         </refsect1>
241
242         <refsect1>
243                 <title>Examples</title>
244
245                 <para>This plots all dependencies of any unit whose
246                 name starts with <literal>avahi-daemon.</literal>:</para>
247
248                 <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
249 $ eog avahi.svg</programlisting>
250
251                 <para>This plots the dependencies between all known target units:</para>
252
253                 <programlisting>systemd-analyze dot --to-pattern='*.target' --from-patter='*.target' | dot -Tsvg > targets.svg
254 $ eog targets.svg</programlisting>
255
256
257         </refsect1>
258
259         <refsect1>
260                 <title>See Also</title>
261                 <para>
262                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
263                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
264                 </para>
265         </refsect1>
266
267 </refentry>