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