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