chiark / gitweb /
man: add sd_event_add_child(3)
[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                 <cmdsynopsis>
99                         <command>systemd-analyze</command>
100                         <arg choice="opt" rep="repeat">OPTIONS</arg>
101                         <arg choice="plain">verify</arg>
102                         <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg>
103                 </cmdsynopsis>
104         </refsynopsisdiv>
105
106         <refsect1>
107                 <title>Description</title>
108
109                 <para><command>systemd-analyze</command> may be used
110                 to determine system boot-up performance statistics and
111                 retrieve other state and tracing information from the
112                 system and service manager, and to verify the
113                 correctness of unit files.</para>
114
115                 <para><command>systemd-analyze time</command>
116                 prints the time spent in the kernel before
117                 userspace has been reached, the time spent in the
118                 initial RAM disk (initrd) before normal system
119                 userspace has been reached, and the time normal system
120                 userspace took to initialize. Note that these
121                 measurements simply measure the time passed up to the
122                 point where all system services have been spawned, but
123                 not necessarily until they fully finished
124                 initialization or the disk is idle.</para>
125
126                 <para><command>systemd-analyze blame</command> prints
127                 a list of all running units, ordered by the time they
128                 took to initialize. This information may be used to
129                 optimize boot-up times. Note that the output might be
130                 misleading as the initialization of one service might
131                 be slow simply because it waits for the initialization
132                 of another service to complete.</para>
133
134                 <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command>
135                 prints a tree of the time-critical chain of units
136                 (for each of the specified <replaceable>UNIT</replaceable>s
137                 or for the default target otherwise).
138                 The time after the unit is active or started is printed
139                 after the "@" character. The time the unit takes to
140                 start is printed after the "+" character.
141                 Note that the output might be misleading as the
142                 initialization of one service might depend on socket
143                 activation and because of the parallel execution
144                 of units.</para>
145
146                 <para><command>systemd-analyze plot</command> prints
147                 an SVG graphic detailing which system services have
148                 been started at what time, highlighting the time they
149                 spent on initialization.</para>
150
151                 <para><command>systemd-analyze dot</command> generates
152                 textual dependency graph description in dot format for
153                 further processing with the GraphViz
154                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
155                 tool. Use a command line like <command>systemd-analyze
156                 dot | dot -Tsvg > systemd.svg</command> to generate a
157                 graphical dependency tree. Unless
158                 <option>--order</option> or <option>--require</option>
159                 is passed, the generated graph will show both ordering
160                 and requirement dependencies. Optional pattern
161                 globbing style specifications
162                 (e.g. <filename>*.target</filename>) may be given at
163                 the end. A unit dependency is included in the graph if
164                 any of these patterns match either the origin or
165                 destination node.</para>
166
167                 <para><command>systemd-analyze dump</command> outputs
168                 a (usually very long) human-readable serialization of
169                 the complete server state. Its format is subject to
170                 change without notice and should not be parsed by
171                 applications.</para>
172
173                 <para><command>systemd-analyze set-log-level
174                 <replaceable>LEVEL</replaceable></command> changes the
175                 current log level of the <command>systemd</command>
176                 daemon to <replaceable>LEVEL</replaceable> (accepts
177                 the same values as <option>--log-level=</option>
178                 described in
179                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
180
181                 <para><command>systemd-analyze verify</command> will
182                 load unit files and print warnings if any errors are
183                 detected. Files specified on the command line will be
184                 loaded, but also any other units referenced by
185                 them. This command works by prepending the directories
186                 for all command line arguments at the beginning of the
187                 unit load path, which means that all units files found
188                 in those directories will be used in preference to the
189                 unit files found in the standard locations, even if
190                 not listed explicitly.</para>
191
192                 <para>If no command is passed, <command>systemd-analyze
193                 time</command> is implied.</para>
194
195         </refsect1>
196
197         <refsect1>
198                 <title>Options</title>
199
200                 <para>The following options are understood:</para>
201
202                 <variablelist>
203                         <varlistentry>
204                                 <term><option>--user</option></term>
205
206                                 <listitem><para>Operates on the user
207                                 systemd instance.</para></listitem>
208                         </varlistentry>
209
210                         <varlistentry>
211                                 <term><option>--system</option></term>
212
213                                 <listitem><para>Operates on the system
214                                 systemd instance. This is the implied
215                                 default.</para></listitem>
216                         </varlistentry>
217
218                         <varlistentry>
219                                 <term><option>--order</option></term>
220                                 <term><option>--require</option></term>
221
222                                 <listitem><para>When used in
223                                 conjunction with the
224                                 <command>dot</command> command (see
225                                 above), selects which dependencies are
226                                 shown in the dependency graph. If
227                                 <option>--order</option> is passed,
228                                 only dependencies of type
229                                 <varname>After=</varname> or
230                                 <varname>Before=</varname> are
231                                 shown. If <option>--require</option>
232                                 is passed, only dependencies of type
233                                 <varname>Requires=</varname>,
234                                 <varname>RequiresOverridable=</varname>,
235                                 <varname>Requisite=</varname>,
236                                 <varname>RequisiteOverridable=</varname>,
237                                 <varname>Wants=</varname> and
238                                 <varname>Conflicts=</varname> are
239                                 shown. If neither is passed, this shows
240                                 dependencies of all these
241                                 types.</para></listitem>
242                         </varlistentry>
243
244                         <varlistentry>
245                                 <term><option>--from-pattern=</option></term>
246                                 <term><option>--to-pattern=</option></term>
247
248                                 <listitem><para>When used in
249                                 conjunction with the
250                                 <command>dot</command> command (see
251                                 above), this selects which relationships
252                                 are shown in the dependency graph.
253                                 They both require
254                                 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
255                                 patterns as arguments, which are
256                                 matched against left-hand and
257                                 right-hand, respectively, nodes of a
258                                 relationship. Each of these can be
259                                 used more than once, which means a
260                                 unit name must match one of the given
261                                 values.</para></listitem>
262                         </varlistentry>
263
264                         <varlistentry>
265                                 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
266
267                                 <listitem><para>When used in conjunction
268                                 with the <command>critical-chain</command>
269                                 command (see above), also show units, which
270                                 finished <replaceable>timespan</replaceable> earlier, than the
271                                 latest unit in the same level. The unit of
272                                 <replaceable>timespan</replaceable> is seconds
273                                 unless specified with a different unit,
274                                 e.g. "50ms".</para></listitem>
275                         </varlistentry>
276
277                         <varlistentry>
278                                 <term><option>--no-man</option></term>
279
280                                 <listitem><para>Do not invoke man to verify the existence
281                                 of man pages listen in <varname>Documentation=</varname>.
282                                 </para></listitem>
283                         </varlistentry>
284
285                         <xi:include href="user-system-options.xml" xpointer="host" />
286                         <xi:include href="user-system-options.xml" xpointer="machine" />
287
288                         <xi:include href="standard-options.xml" xpointer="help" />
289                         <xi:include href="standard-options.xml" xpointer="version" />
290                         <xi:include href="standard-options.xml" xpointer="no-pager" />
291                 </variablelist>
292
293         </refsect1>
294
295         <refsect1>
296                 <title>Exit status</title>
297
298                 <para>On success, 0 is returned, a non-zero failure
299                 code otherwise.</para>
300         </refsect1>
301
302         <refsect1>
303                 <title>Examples for <command>dot</command></title>
304
305                 <example>
306                         <title>Plots all dependencies of any unit whose
307                         name starts with <literal>avahi-daemon</literal></title>
308
309                         <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
310                         $ eog avahi.svg</programlisting>
311                 </example>
312
313                 <example>
314                         <title>Plots the dependencies between all known target units</title>
315
316                         <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
317 $ eog targets.svg</programlisting>
318                 </example>
319         </refsect1>
320
321         <refsect1>
322                 <title>Examples for <command>verify</command></title>
323
324                 <para>The following errors are currently detected:</para>
325                 <itemizedlist>
326                         <listitem><para>unknown sections and
327                         directives, </para></listitem>
328
329                         <listitem><para>missing dependencies which are
330                         required to start the given unit,
331                         </para></listitem>
332
333                         <listitem><para>man pages listed in
334                         <varname>Documentation=</varname> which are
335                         not found in the system,</para></listitem>
336
337                         <listitem><para>commands listed in
338                         <varname>ExecStart=</varname> and similar
339                         which are not found in the system or not
340                         executable.</para></listitem>
341                 </itemizedlist>
342
343                 <example>
344                         <title>Misspelt directives</title>
345
346                         <programlisting>$ cat ./user.slice
347 [Unit]
348 WhatIsThis=11
349 Documentation=man:nosuchfile(1)
350 Requires=different.service
351
352 [Service]
353 Desription=x
354
355 $ systemd-verify ./user.slice
356 [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit'
357 [./user.slice:13] Unknown section 'Service'. Ignoring.
358 Error: org.freedesktop.systemd1.LoadFailed:
359          Unit different.service failed to load:
360          No such file or directory.
361 Failed to create user.slice/start: Invalid argument
362 user.slice: man nosuchfile(1) command failed with code 16
363                         </programlisting>
364                 </example>
365
366                 <example>
367                         <title>Missing service units</title>
368
369                         <programlisting>$ tail ./a.socket ./b.socket
370 ==> ./a.socket &lt;==
371 [Socket]
372 ListenStream=100
373
374 ==> ./b.socket &lt;==
375 [Socket]
376 ListenStream=100
377 Accept=yes
378
379 $ systemd-verify ./a.socket ./b.socket
380 Service a.service not loaded, a.socket cannot be started.
381 Service b@0.service not loaded, b.socket cannot be started.
382                         </programlisting>
383                 </example>
384         </refsect1>
385
386         <xi:include href="less-variables.xml" />
387
388         <refsect1>
389                 <title>See Also</title>
390                 <para>
391                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
392                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
393                 </para>
394         </refsect1>
395
396 </refentry>