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>Requisite=</varname>,
 230         <varname>Wants=</varname> and <varname>Conflicts=</varname>
 231         are shown. If neither is passed, this shows dependencies of
 232         all these types.</para></listitem>
 233       </varlistentry>
 234
 235       <varlistentry>
 236         <term><option>--from-pattern=</option></term>
 237         <term><option>--to-pattern=</option></term>
 238
 239         <listitem><para>When used in conjunction with the
 240         <command>dot</command> command (see above), this selects which
 241         relationships are shown in the dependency graph. Both options
 242         require a
 243         <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 244         pattern as an argument, which will be matched against the
 245         left-hand and the right-hand, respectively, nodes of a
 246         relationship.</para>
 247
 248         <para>Each of these can be used more than once, in which case
 249         the unit name must match one of the values. When tests for
 250         both sides of the relation are present, a relation must pass
 251         both tests to be shown. When patterns are also specified as
 252         positional arguments, they must match at least one side of the
 253         relation. In other words, patterns specified with those two
 254         options will trim the list of edges matched by the positional
 255         arguments, if any are given, and fully determine the list of
 256         edges shown otherwise.</para></listitem>
 257       </varlistentry>
 258
 259       <varlistentry>
 260         <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
 261
 262         <listitem><para>When used in conjunction with the
 263         <command>critical-chain</command> command (see above), also
 264         show units, which finished <replaceable>timespan</replaceable>
 265         earlier, than the latest unit in the same level. The unit of
 266         <replaceable>timespan</replaceable> is seconds unless
 267         specified with a different unit, e.g.
 268         "50ms".</para></listitem>
 269       </varlistentry>
 270
 271       <varlistentry>
 272         <term><option>--no-man</option></term>
 273
 274         <listitem><para>Do not invoke man to verify the existence of
 275         man pages listed in <varname>Documentation=</varname>.
 276         </para></listitem>
 277       </varlistentry>
 278
 279       <xi:include href="user-system-options.xml" xpointer="host" />
 280       <xi:include href="user-system-options.xml" xpointer="machine" />
 281
 282       <xi:include href="standard-options.xml" xpointer="help" />
 283       <xi:include href="standard-options.xml" xpointer="version" />
 284       <xi:include href="standard-options.xml" xpointer="no-pager" />
 285     </variablelist>
 286
 287   </refsect1>
 288
 289   <refsect1>
 290     <title>Exit status</title>
 291
 292     <para>On success, 0 is returned, a non-zero failure code
 293     otherwise.</para>
 294   </refsect1>
 295
 296   <refsect1>
 297     <title>Examples for <command>dot</command></title>
 298
 299     <example>
 300       <title>Plots all dependencies of any unit whose name starts with
 301       <literal>avahi-daemon</literal></title>
 302
 303       <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
 304       $ eog avahi.svg</programlisting>
 305     </example>
 306
 307     <example>
 308       <title>Plots the dependencies between all known target units</title>
 309
 310       <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
 311 $ eog targets.svg</programlisting>
 312     </example>
 313   </refsect1>
 314
 315   <refsect1>
 316     <title>Examples for <command>verify</command></title>
 317
 318     <para>The following errors are currently detected:</para>
 319     <itemizedlist>
 320       <listitem><para>unknown sections and directives,
 321       </para></listitem>
 322
 323       <listitem><para>missing dependencies which are required to start
 324       the given unit, </para></listitem>
 325
 326       <listitem><para>man pages listed in
 327       <varname>Documentation=</varname> which are not found in the
 328       system,</para></listitem>
 329
 330       <listitem><para>commands listed in <varname>ExecStart=</varname>
 331       and similar which are not found in the system or not
 332       executable.</para></listitem>
 333     </itemizedlist>
 334
 335     <example>
 336       <title>Misspelt directives</title>
 337
 338       <programlisting>$ cat ./user.slice
 339 [Unit]
 340 WhatIsThis=11
 341 Documentation=man:nosuchfile(1)
 342 Requires=different.service
 343
 344 [Service]
 345 Desription=x
 346
 347 $ systemd-analyze verify ./user.slice
 348 [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit'
 349 [./user.slice:13] Unknown section 'Service'. Ignoring.
 350 Error: org.freedesktop.systemd1.LoadFailed:
 351    Unit different.service failed to load:
 352    No such file or directory.
 353 Failed to create user.slice/start: Invalid argument
 354 user.slice: man nosuchfile(1) command failed with code 16
 355       </programlisting>
 356     </example>
 357
 358     <example>
 359       <title>Missing service units</title>
 360
 361       <programlisting>$ tail ./a.socket ./b.socket
 362 ==> ./a.socket &lt;==
 363 [Socket]
 364 ListenStream=100
 365
 366 ==> ./b.socket &lt;==
 367 [Socket]
 368 ListenStream=100
 369 Accept=yes
 370
 371 $ systemd-analyze verify ./a.socket ./b.socket
 372 Service a.service not loaded, a.socket cannot be started.
 373 Service b@0.service not loaded, b.socket cannot be started.
 374       </programlisting>
 375     </example>
 376   </refsect1>
 377
 378   <xi:include href="less-variables.xml" />
 379
 380   <refsect1>
 381     <title>See Also</title>
 382     <para>
 383       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 384       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 385     </para>
 386   </refsect1>
 387
 388 </refentry>