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