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">
6 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id="systemd-analyze"
25 xmlns:xi="http://www.w3.org/2001/XInclude">
28 <title>systemd-analyze</title>
29 <productname>systemd</productname>
33 <contrib>Developer</contrib>
34 <firstname>Lennart</firstname>
35 <surname>Poettering</surname>
36 <email>lennart@poettering.net</email>
39 <contrib>Developer</contrib>
40 <firstname>Harald</firstname>
41 <surname>Hoyer</surname>
42 <email>harald@redhat.com</email>
48 <refentrytitle>systemd-analyze</refentrytitle>
49 <manvolnum>1</manvolnum>
53 <refname>systemd-analyze</refname>
54 <refpurpose>Analyze system boot-up performance</refpurpose>
59 <command>systemd-analyze</command>
60 <arg choice="opt" rep="repeat">OPTIONS</arg>
64 <command>systemd-analyze</command>
65 <arg choice="opt" rep="repeat">OPTIONS</arg>
66 <arg choice="plain">blame</arg>
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>
75 <command>systemd-analyze</command>
76 <arg choice="opt" rep="repeat">OPTIONS</arg>
77 <arg choice="plain">plot</arg>
78 <arg choice="opt">> file.svg</arg>
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">> file.dot</arg>
88 <command>systemd-analyze</command>
89 <arg choice="opt" rep="repeat">OPTIONS</arg>
90 <arg choice="plain">dump</arg>
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>
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>
107 <title>Description</title>
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>
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>
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>
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
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>
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>
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
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>
179 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
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>
192 <para>If no command is passed, <command>systemd-analyze
193 time</command> is implied.</para>
198 <title>Options</title>
200 <para>The following options are understood:</para>
204 <term><option>--user</option></term>
206 <listitem><para>Operates on the user
207 systemd instance.</para></listitem>
211 <term><option>--system</option></term>
213 <listitem><para>Operates on the system
214 systemd instance. This is the implied
215 default.</para></listitem>
219 <term><option>--order</option></term>
220 <term><option>--require</option></term>
222 <listitem><para>When used in
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>
245 <term><option>--from-pattern=</option></term>
246 <term><option>--to-pattern=</option></term>
248 <listitem><para>When used in
250 <command>dot</command> command (see
251 above), this selects which relationships
252 are shown in the dependency graph.
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>
265 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
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>
278 <term><option>--no-man</option></term>
280 <listitem><para>Do not invoke man to verify the existence
281 of man pages listen in <varname>Documentation=</varname>.
285 <xi:include href="user-system-options.xml" xpointer="host" />
286 <xi:include href="user-system-options.xml" xpointer="machine" />
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" />
296 <title>Exit status</title>
298 <para>On success, 0 is returned, a non-zero failure
299 code otherwise.</para>
303 <title>Examples for <command>dot</command></title>
306 <title>Plots all dependencies of any unit whose
307 name starts with <literal>avahi-daemon</literal></title>
309 <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
310 $ eog avahi.svg</programlisting>
314 <title>Plots the dependencies between all known target units</title>
316 <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
317 $ eog targets.svg</programlisting>
322 <title>Examples for <command>verify</command></title>
324 <para>The following errors are currently detected:</para>
326 <listitem><para>unknown sections and
327 directives, </para></listitem>
329 <listitem><para>missing dependencies which are
330 required to start the given unit,
333 <listitem><para>man pages listed in
334 <varname>Documentation=</varname> which are
335 not found in the system,</para></listitem>
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>
344 <title>Misspelt directives</title>
346 <programlisting>$ cat ./user.slice
349 Documentation=man:nosuchfile(1)
350 Requires=different.service
355 $ systemd-analyze 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
367 <title>Missing service units</title>
369 <programlisting>$ tail ./a.socket ./b.socket
370 ==> ./a.socket <==
374 ==> ./b.socket <==
379 $ systemd-analyze 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.
386 <xi:include href="less-variables.xml" />
389 <title>See Also</title>
391 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
392 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>