chiark / gitweb /
machined: optionally, allow registration of pre-existing units (scopes
[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                         <arg choice="opt">&gt; file.dot</arg>
85                 </cmdsynopsis>
86                 <cmdsynopsis>
87                         <command>systemd-analyze</command>
88                         <arg choice="opt" rep="repeat">OPTIONS</arg>
89                         <arg choice="plain">dump</arg>
90                 </cmdsynopsis>
91                 <cmdsynopsis>
92                         <command>systemd-analyze</command>
93                         <arg choice="opt" rep="repeat">OPTIONS</arg>
94                         <arg choice="plain">set-log-level</arg>
95                         <arg choice="opt"><replaceable>LEVEL</replaceable></arg>
96                 </cmdsynopsis>
97         </refsynopsisdiv>
98
99         <refsect1>
100                 <title>Description</title>
101
102                 <para><command>systemd-analyze</command> may be used
103                 to determine system boot-up performance statistics and
104                 retrieve other state and tracing information from the
105                 system and service manager.</para>
106
107                 <para><command>systemd-analyze time</command>
108                 prints the time spent in the kernel before
109                 userspace has been reached, the time spent in the
110                 initial RAM disk (initrd) before normal system
111                 userspace has been reached, and the time normal system
112                 userspace took to initialize. Note that these
113                 measurements simply measure the time passed up to the
114                 point where all system services have been spawned, but
115                 not necessarily until they fully finished
116                 initialization or the disk is idle.</para>
117
118                 <para><command>systemd-analyze blame</command> prints
119                 a list of all running units, ordered by the time they
120                 took to initialize. This information may be used to
121                 optimize boot-up times. Note that the output might be
122                 misleading as the initialization of one service might
123                 be slow simply because it waits for the initialization
124                 of another service to complete.</para>
125
126                 <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command>
127                 prints a tree of the time-critical chain of units
128                 (for each of the specified <replaceable>UNIT</replaceable>s
129                 or for the default target otherwise).
130                 The time after the unit is active or started is printed
131                 after the "@" character. The time the unit takes to
132                 start is printed after the "+" character.
133                 Note that the output might be misleading as the
134                 initialization of one service might depend on socket
135                 activation and because of the parallel execution
136                 of units.</para>
137
138                 <para><command>systemd-analyze plot</command> prints
139                 an SVG graphic detailing which system services have
140                 been started at what time, highlighting the time they
141                 spent on initialization.</para>
142
143                 <para><command>systemd-analyze dot</command> generates
144                 textual dependency graph description in dot format for
145                 further processing with the GraphViz
146                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
147                 tool. Use a command line like <command>systemd-analyze
148                 dot | dot -Tsvg > systemd.svg</command> to generate a
149                 graphical dependency tree. Unless
150                 <option>--order</option> or <option>--require</option>
151                 is passed, the generated graph will show both ordering
152                 and requirement dependencies. Optional pattern
153                 globbing style specifications
154                 (e.g. <filename>*.target</filename>) may be given at
155                 the end. A unit dependency is included in the graph if
156                 any of these patterns match either the origin or
157                 destination node.</para>
158
159                 <para><command>systemd-analyze dump</command> outputs
160                 a (usually very long) human-readable serialization of
161                 the complete server state. Its format is subject to
162                 change without notice and should not be parsed by
163                 applications.</para>
164
165                 <para><command>systemd-analyze set-log-level
166                 <replaceable>LEVEL</replaceable></command> changes the
167                 current log level of the <command>systemd</command>
168                 daemon to <replaceable>LEVEL</replaceable> (accepts
169                 the same values as <option>--log-level=</option>
170                 described in
171                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
172
173                 <para>If no command is passed, <command>systemd-analyze
174                 time</command> is implied.</para>
175
176         </refsect1>
177
178         <refsect1>
179                 <title>Options</title>
180
181                 <para>The following options are understood:</para>
182
183                 <variablelist>
184                         <varlistentry>
185                                 <term><option>-h</option></term>
186                                 <term><option>--help</option></term>
187
188                                 <listitem><para>Prints a short help
189                                 text and exits.</para></listitem>
190                         </varlistentry>
191
192                         <varlistentry>
193                                 <term><option>--user</option></term>
194
195                                 <listitem><para>Shows performance data
196                                 of user sessions instead of the system
197                                 manager.</para></listitem>
198                         </varlistentry>
199
200                         <varlistentry>
201                                 <term><option>--system</option></term>
202
203                                 <listitem><para>Shows performance data
204                                 of the system manager. This is the
205                                 implied default.</para></listitem>
206                         </varlistentry>
207
208                         <varlistentry>
209                                 <term><option>-H</option></term>
210                                 <term><option>--host=</option></term>
211
212                                 <listitem><para>Execute the operation
213                                 remotely. Specify a hostname, or
214                                 username and hostname separated by
215                                 <literal>@</literal>, to connect
216                                 to. This will use SSH to talk to the
217                                 remote machine manager
218                                 instance.</para></listitem>
219                         </varlistentry>
220
221                         <varlistentry>
222                                 <term><option>-M</option></term>
223                                 <term><option>--machine=</option></term>
224
225                                 <listitem><para>Execute the operation on a
226                                 local container. Specify a container
227                                 name to connect to.</para></listitem>
228                         </varlistentry>
229
230                         <varlistentry>
231                                 <term><option>--order</option></term>
232                                 <term><option>--require</option></term>
233
234                                 <listitem><para>When used in
235                                 conjunction with the
236                                 <command>dot</command> command (see
237                                 above), selects which dependencies are
238                                 shown in the dependency graph. If
239                                 <option>--order</option> is passed,
240                                 only dependencies of type
241                                 <varname>After=</varname> or
242                                 <varname>Before=</varname> are
243                                 shown. If <option>--require</option>
244                                 is passed, only dependencies of type
245                                 <varname>Requires=</varname>,
246                                 <varname>RequiresOverridable=</varname>,
247                                 <varname>Requisite=</varname>,
248                                 <varname>RequisiteOverridable=</varname>,
249                                 <varname>Wants=</varname> and
250                                 <varname>Conflicts=</varname> are
251                                 shown. If neither is passed, this shows
252                                 dependencies of all these
253                                 types.</para></listitem>
254                         </varlistentry>
255
256                         <varlistentry>
257                                 <term><option>--from-pattern=</option></term>
258                                 <term><option>--to-pattern=</option></term>
259
260                                 <listitem><para>When used in
261                                 conjunction with the
262                                 <command>dot</command> command (see
263                                 above), this selects which relationships
264                                 are shown in the dependency graph.
265                                 They both require
266                                 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
267                                 patterns as arguments, which are
268                                 matched against left-hand and
269                                 right-hand, respectively, nodes of a
270                                 relationship. Each of these can be
271                                 used more than once, which means a
272                                 unit name must match one of the given
273                                 values.</para></listitem>
274                         </varlistentry>
275
276                         <varlistentry>
277                                 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
278
279                                 <listitem><para>When used in conjunction
280                                 with the <command>critical-chain</command>
281                                 command (see above), also show units, which
282                                 finished <replaceable>timespan</replaceable> earlier, than the
283                                 latest unit in the same level. The unit of
284                                 <replaceable>timespan</replaceable> is seconds
285                                 unless specified with a different unit,
286                                 e.g. "50ms".</para></listitem>
287                         </varlistentry>
288
289                         <varlistentry>
290                                 <term><option>--no-pager</option></term>
291
292                                 <listitem>
293                                         <para>Do not pipe output into a pager.</para>
294                                 </listitem>
295                         </varlistentry>
296                 </variablelist>
297
298         </refsect1>
299
300         <refsect1>
301                 <title>Exit status</title>
302
303                 <para>On success, 0 is returned, a non-zero failure
304                 code otherwise.</para>
305         </refsect1>
306
307         <refsect1>
308                 <title>Examples</title>
309
310                 <para>This plots all dependencies of any unit whose
311                 name starts with <literal>avahi-daemon.</literal>:</para>
312
313                 <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
314 $ eog avahi.svg</programlisting>
315
316                 <para>This plots the dependencies between all known target units:</para>
317
318                 <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
319 $ eog targets.svg</programlisting>
320
321
322         </refsect1>
323
324         <refsect1>
325                 <title>Environment</title>
326
327                 <variablelist class='environment-variables'>
328                         <varlistentry>
329                                 <term><varname>$SYSTEMD_PAGER</varname></term>
330
331                                 <listitem>
332                                         <para>Pager to use when <option>--no-pager</option> is not
333                                         given; overrides <varname>$PAGER</varname>.  Setting this to
334                                         an empty string or the value <literal>cat</literal> is
335                                         equivalent to passing
336                                         <option>--no-pager</option>.</para>
337                                 </listitem>
338                         </varlistentry>
339                 </variablelist>
340         </refsect1>
341
342         <refsect1>
343                 <title>See Also</title>
344                 <para>
345                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
346                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
347                 </para>
348         </refsect1>
349
350 </refentry>