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