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