chiark / gitweb /
update TODO
[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           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>systemd-analyze</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                         <author>
39                                 <contrib>Developer</contrib>
40                                 <firstname>Harald</firstname>
41                                 <surname>Hoyer</surname>
42                                 <email>harald@redhat.com</email>
43                         </author>
44                 </authorgroup>
45         </refentryinfo>
46
47         <refmeta>
48                 <refentrytitle>systemd-analyze</refentrytitle>
49                 <manvolnum>1</manvolnum>
50         </refmeta>
51
52         <refnamediv>
53                 <refname>systemd-analyze</refname>
54                 <refpurpose>Analyze system boot-up performance</refpurpose>
55         </refnamediv>
56
57         <refsynopsisdiv>
58                 <cmdsynopsis>
59                         <command>systemd-analyze</command>
60                         <arg choice="opt" rep="repeat">OPTIONS</arg>
61                         <arg>time</arg>
62                 </cmdsynopsis>
63                 <cmdsynopsis>
64                         <command>systemd-analyze</command>
65                         <arg choice="opt" rep="repeat">OPTIONS</arg>
66                         <arg choice="plain">blame</arg>
67                 </cmdsynopsis>
68                 <cmdsynopsis>
69                         <command>systemd-analyze</command>
70                         <arg choice="opt" rep="repeat">OPTIONS</arg>
71                         <arg choice="plain">critical-chain</arg>
72                         <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
73                 </cmdsynopsis>
74                 <cmdsynopsis>
75                         <command>systemd-analyze</command>
76                         <arg choice="opt" rep="repeat">OPTIONS</arg>
77                         <arg choice="plain">plot</arg>
78                         <arg choice="opt">&gt; file.svg</arg>
79                 </cmdsynopsis>
80                 <cmdsynopsis>
81                         <command>systemd-analyze</command>
82                         <arg choice="opt" rep="repeat">OPTIONS</arg>
83                         <arg choice="plain">dot</arg>
84                         <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
85                         <arg choice="opt">&gt; file.dot</arg>
86                 </cmdsynopsis>
87                 <cmdsynopsis>
88                         <command>systemd-analyze</command>
89                         <arg choice="opt" rep="repeat">OPTIONS</arg>
90                         <arg choice="plain">dump</arg>
91                 </cmdsynopsis>
92                 <cmdsynopsis>
93                         <command>systemd-analyze</command>
94                         <arg choice="opt" rep="repeat">OPTIONS</arg>
95                         <arg choice="plain">set-log-level</arg>
96                         <arg choice="opt"><replaceable>LEVEL</replaceable></arg>
97                 </cmdsynopsis>
98         </refsynopsisdiv>
99
100         <refsect1>
101                 <title>Description</title>
102
103                 <para><command>systemd-analyze</command> may be used
104                 to determine system boot-up performance statistics and
105                 retrieve other state and tracing information from the
106                 system and service manager.</para>
107
108                 <para><command>systemd-analyze time</command>
109                 prints the time spent in the kernel before
110                 userspace has been reached, the time spent in the
111                 initial RAM disk (initrd) before normal system
112                 userspace has been reached, and the time normal system
113                 userspace took to initialize. Note that these
114                 measurements simply measure the time passed up to the
115                 point where all system services have been spawned, but
116                 not necessarily until they fully finished
117                 initialization or the disk is idle.</para>
118
119                 <para><command>systemd-analyze blame</command> prints
120                 a list of all running units, ordered by the time they
121                 took to initialize. This information may be used to
122                 optimize boot-up times. Note that the output might be
123                 misleading as the initialization of one service might
124                 be slow simply because it waits for the initialization
125                 of another service to complete.</para>
126
127                 <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command>
128                 prints a tree of the time-critical chain of units
129                 (for each of the specified <replaceable>UNIT</replaceable>s
130                 or for the default target otherwise).
131                 The time after the unit is active or started is printed
132                 after the "@" character. The time the unit takes to
133                 start is printed after the "+" character.
134                 Note that the output might be misleading as the
135                 initialization of one service might depend on socket
136                 activation and because of the parallel execution
137                 of units.</para>
138
139                 <para><command>systemd-analyze plot</command> prints
140                 an SVG graphic detailing which system services have
141                 been started at what time, highlighting the time they
142                 spent on initialization.</para>
143
144                 <para><command>systemd-analyze dot</command> generates
145                 textual dependency graph description in dot format for
146                 further processing with the GraphViz
147                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
148                 tool. Use a command line like <command>systemd-analyze
149                 dot | dot -Tsvg > systemd.svg</command> to generate a
150                 graphical dependency tree. Unless
151                 <option>--order</option> or <option>--require</option>
152                 is passed, the generated graph will show both ordering
153                 and requirement dependencies. Optional pattern
154                 globbing style specifications
155                 (e.g. <filename>*.target</filename>) may be given at
156                 the end. A unit dependency is included in the graph if
157                 any of these patterns match either the origin or
158                 destination node.</para>
159
160                 <para><command>systemd-analyze dump</command> outputs
161                 a (usually very long) human-readable serialization of
162                 the complete server state. Its format is subject to
163                 change without notice and should not be parsed by
164                 applications.</para>
165
166                 <para><command>systemd-analyze set-log-level
167                 <replaceable>LEVEL</replaceable></command> changes the
168                 current log level of the <command>systemd</command>
169                 daemon to <replaceable>LEVEL</replaceable> (accepts
170                 the same values as <option>--log-level=</option>
171                 described in
172                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
173
174                 <para>If no command is passed, <command>systemd-analyze
175                 time</command> is implied.</para>
176
177         </refsect1>
178
179         <refsect1>
180                 <title>Options</title>
181
182                 <para>The following options are understood:</para>
183
184                 <variablelist>
185                         <varlistentry>
186                                 <term><option>--user</option></term>
187
188                                 <listitem><para>Shows performance data
189                                 of user sessions instead of the system
190                                 manager.</para></listitem>
191                         </varlistentry>
192
193                         <varlistentry>
194                                 <term><option>--system</option></term>
195
196                                 <listitem><para>Shows performance data
197                                 of the system manager. This is the
198                                 implied default.</para></listitem>
199                         </varlistentry>
200
201                         <varlistentry>
202                                 <term><option>--order</option></term>
203                                 <term><option>--require</option></term>
204
205                                 <listitem><para>When used in
206                                 conjunction with the
207                                 <command>dot</command> command (see
208                                 above), selects which dependencies are
209                                 shown in the dependency graph. If
210                                 <option>--order</option> is passed,
211                                 only dependencies of type
212                                 <varname>After=</varname> or
213                                 <varname>Before=</varname> are
214                                 shown. If <option>--require</option>
215                                 is passed, only dependencies of type
216                                 <varname>Requires=</varname>,
217                                 <varname>RequiresOverridable=</varname>,
218                                 <varname>Requisite=</varname>,
219                                 <varname>RequisiteOverridable=</varname>,
220                                 <varname>Wants=</varname> and
221                                 <varname>Conflicts=</varname> are
222                                 shown. If neither is passed, this shows
223                                 dependencies of all these
224                                 types.</para></listitem>
225                         </varlistentry>
226
227                         <varlistentry>
228                                 <term><option>--from-pattern=</option></term>
229                                 <term><option>--to-pattern=</option></term>
230
231                                 <listitem><para>When used in
232                                 conjunction with the
233                                 <command>dot</command> command (see
234                                 above), this selects which relationships
235                                 are shown in the dependency graph.
236                                 They both require
237                                 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
238                                 patterns as arguments, which are
239                                 matched against left-hand and
240                                 right-hand, respectively, nodes of a
241                                 relationship. Each of these can be
242                                 used more than once, which means a
243                                 unit name must match one of the given
244                                 values.</para></listitem>
245                         </varlistentry>
246
247                         <varlistentry>
248                                 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
249
250                                 <listitem><para>When used in conjunction
251                                 with the <command>critical-chain</command>
252                                 command (see above), also show units, which
253                                 finished <replaceable>timespan</replaceable> earlier, than the
254                                 latest unit in the same level. The unit of
255                                 <replaceable>timespan</replaceable> is seconds
256                                 unless specified with a different unit,
257                                 e.g. "50ms".</para></listitem>
258                         </varlistentry>
259
260                         <xi:include href="user-system-options.xml" xpointer="host" />
261                         <xi:include href="user-system-options.xml" xpointer="machine" />
262
263                         <xi:include href="standard-options.xml" xpointer="help" />
264                         <xi:include href="standard-options.xml" xpointer="version" />
265                         <xi:include href="standard-options.xml" xpointer="no-pager" />
266                 </variablelist>
267
268         </refsect1>
269
270         <refsect1>
271                 <title>Exit status</title>
272
273                 <para>On success, 0 is returned, a non-zero failure
274                 code otherwise.</para>
275         </refsect1>
276
277         <refsect1>
278                 <title>Examples</title>
279
280                 <para>This plots all dependencies of any unit whose
281                 name starts with <literal>avahi-daemon.</literal>:</para>
282
283                 <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
284 $ eog avahi.svg</programlisting>
285
286                 <para>This plots the dependencies between all known target units:</para>
287
288                 <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
289 $ eog targets.svg</programlisting>
290
291
292         </refsect1>
293
294         <xi:include href="less-variables.xml" />
295
296         <refsect1>
297                 <title>See Also</title>
298                 <para>
299                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
300                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
301                 </para>
302         </refsect1>
303
304 </refentry>