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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2012 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="systemd-analyze"
  27     xmlns:xi="http://www.w3.org/2001/XInclude">
  28
  29   <refentryinfo>
  30     <title>systemd-analyze</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40       <author>
  41         <contrib>Developer</contrib>
  42         <firstname>Harald</firstname>
  43         <surname>Hoyer</surname>
  44         <email>harald@redhat.com</email>
  45       </author>
  46     </authorgroup>
  47   </refentryinfo>
  48
  49   <refmeta>
  50     <refentrytitle>systemd-analyze</refentrytitle>
  51     <manvolnum>1</manvolnum>
  52   </refmeta>
  53
  54   <refnamediv>
  55     <refname>systemd-analyze</refname>
  56     <refpurpose>Analyze system boot-up performance</refpurpose>
  57   </refnamediv>
  58
  59   <refsynopsisdiv>
  60     <cmdsynopsis>
  61       <command>systemd-analyze</command>
  62       <arg choice="opt" rep="repeat">OPTIONS</arg>
  63       <arg>time</arg>
  64     </cmdsynopsis>
  65     <cmdsynopsis>
  66       <command>systemd-analyze</command>
  67       <arg choice="opt" rep="repeat">OPTIONS</arg>
  68       <arg choice="plain">blame</arg>
  69     </cmdsynopsis>
  70     <cmdsynopsis>
  71       <command>systemd-analyze</command>
  72       <arg choice="opt" rep="repeat">OPTIONS</arg>
  73       <arg choice="plain">critical-chain</arg>
  74       <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
  75     </cmdsynopsis>
  76     <cmdsynopsis>
  77       <command>systemd-analyze</command>
  78       <arg choice="opt" rep="repeat">OPTIONS</arg>
  79       <arg choice="plain">plot</arg>
  80       <arg choice="opt">&gt; file.svg</arg>
  81     </cmdsynopsis>
  82     <cmdsynopsis>
  83       <command>systemd-analyze</command>
  84       <arg choice="opt" rep="repeat">OPTIONS</arg>
  85       <arg choice="plain">dot</arg>
  86       <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
  87       <arg choice="opt">&gt; file.dot</arg>
  88     </cmdsynopsis>
  89     <cmdsynopsis>
  90       <command>systemd-analyze</command>
  91       <arg choice="opt" rep="repeat">OPTIONS</arg>
  92       <arg choice="plain">dump</arg>
  93     </cmdsynopsis>
  94     <cmdsynopsis>
  95       <command>systemd-analyze</command>
  96       <arg choice="opt" rep="repeat">OPTIONS</arg>
  97       <arg choice="plain">set-log-level</arg>
  98       <arg choice="plain"><replaceable>LEVEL</replaceable></arg>
  99     </cmdsynopsis>
 100     <cmdsynopsis>
 101       <command>systemd-analyze</command>
 102       <arg choice="opt" rep="repeat">OPTIONS</arg>
 103       <arg choice="plain">set-log-target</arg>
 104       <arg choice="plain"><replaceable>TARGET</replaceable></arg>
 105     </cmdsynopsis>
 106     <cmdsynopsis>
 107       <command>systemd-analyze</command>
 108       <arg choice="opt" rep="repeat">OPTIONS</arg>
 109       <arg choice="plain">get-log-level</arg>
 110     </cmdsynopsis>
 111     <cmdsynopsis>
 112       <command>systemd-analyze</command>
 113       <arg choice="opt" rep="repeat">OPTIONS</arg>
 114       <arg choice="plain">get-log-target</arg>
 115     </cmdsynopsis>
 116     <cmdsynopsis>
 117       <command>systemd-analyze</command>
 118       <arg choice="opt" rep="repeat">OPTIONS</arg>
 119       <arg choice="plain">syscall-filter</arg>
 120       <arg choice="opt"><replaceable>SET</replaceable>…</arg>
 121     </cmdsynopsis>
 122     <cmdsynopsis>
 123       <command>systemd-analyze</command>
 124       <arg choice="opt" rep="repeat">OPTIONS</arg>
 125       <arg choice="plain">verify</arg>
 126       <arg choice="opt" rep="repeat"><replaceable>FILES</replaceable></arg>
 127     </cmdsynopsis>
 128     <cmdsynopsis>
 129       <command>systemd-analyze</command>
 130       <arg choice="opt" rep="repeat">OPTIONS</arg>
 131       <arg choice="plain">calendar</arg>
 132       <arg choice="plain" rep="repeat"><replaceable>SPECS</replaceable></arg>
 133     </cmdsynopsis>
 134   </refsynopsisdiv>
 135
 136   <refsect1>
 137     <title>Description</title>
 138
 139     <para><command>systemd-analyze</command> may be used to determine
 140     system boot-up performance statistics and retrieve other state and
 141     tracing information from the system and service manager, and to
 142     verify the correctness of unit files.</para>
 143
 144     <para><command>systemd-analyze time</command> prints the time
 145     spent in the kernel before userspace has been reached, the time
 146     spent in the initial RAM disk (initrd) before normal system
 147     userspace has been reached, and the time normal system userspace
 148     took to initialize. Note that these measurements simply measure
 149     the time passed up to the point where all system services have
 150     been spawned, but not necessarily until they fully finished
 151     initialization or the disk is idle.</para>
 152
 153     <para><command>systemd-analyze blame</command> prints a list of
 154     all running units, ordered by the time they took to initialize.
 155     This information may be used to optimize boot-up times. Note that
 156     the output might be misleading as the initialization of one
 157     service might be slow simply because it waits for the
 158     initialization of another service to complete.</para>
 159
 160     <para><command>systemd-analyze critical-chain
 161     [<replaceable>UNIT…</replaceable>]</command> prints a tree of
 162     the time-critical chain of units (for each of the specified
 163     <replaceable>UNIT</replaceable>s or for the default target
 164     otherwise). The time after the unit is active or started is
 165     printed after the "@" character. The time the unit takes to start
 166     is printed after the "+" character. Note that the output might be
 167     misleading as the initialization of one service might depend on
 168     socket activation and because of the parallel execution of
 169     units.</para>
 170
 171     <para><command>systemd-analyze plot</command> prints an SVG
 172     graphic detailing which system services have been started at what
 173     time, highlighting the time they spent on initialization.</para>
 174
 175     <para><command>systemd-analyze dot</command> generates textual
 176     dependency graph description in dot format for further processing
 177     with the GraphViz
 178     <citerefentry project='die-net'><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 179     tool. Use a command line like <command>systemd-analyze dot | dot
 180     -Tsvg > systemd.svg</command> to generate a graphical dependency
 181     tree. Unless <option>--order</option> or
 182     <option>--require</option> is passed, the generated graph will
 183     show both ordering and requirement dependencies. Optional pattern
 184     globbing style specifications (e.g. <filename>*.target</filename>)
 185     may be given at the end. A unit dependency is included in the
 186     graph if any of these patterns match either the origin or
 187     destination node.</para>
 188
 189     <para><command>systemd-analyze dump</command> outputs a (usually
 190     very long) human-readable serialization of the complete server
 191     state. Its format is subject to change without notice and should
 192     not be parsed by applications.</para>
 193
 194     <para><command>systemd-analyze set-log-level
 195     <replaceable>LEVEL</replaceable></command> changes the current log
 196     level of the <command>systemd</command> daemon to
 197     <replaceable>LEVEL</replaceable> (accepts the same values as
 198     <option>--log-level=</option> described in
 199     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 200
 201     <para><command>systemd-analyze set-log-target
 202     <replaceable>TARGET</replaceable></command> changes the current log
 203     target of the <command>systemd</command> daemon to
 204     <replaceable>TARGET</replaceable> (accepts the same values as
 205     <option>--log-target=</option>, described in
 206     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 207
 208     <para><command>systemd-analyze get-log-level</command>
 209     prints the current log level of the <command>systemd</command> daemon.</para>
 210
 211     <para><command>systemd-analyze get-log-target</command>
 212     prints the current log target of the <command>systemd</command> daemon.</para>
 213
 214     <para><command>systemd-analyze syscall-filter <optional><replaceable>SET</replaceable>…</optional></command>
 215     will list system calls contained in the specified system call set <replaceable>SET</replaceable>,
 216     or all known sets if no sets are specified. Argument <replaceable>SET</replaceable> must include
 217     the <literal>@</literal> prefix.</para>
 218
 219     <para><command>systemd-analyze verify</command> will load unit files and print
 220     warnings if any errors are detected. Files specified on the command line will be
 221     loaded, but also any other units referenced by them. The full unit search path is
 222     formed by combining the directories for all command line arguments, and the usual unit
 223     load paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be
 224     used to replace or augment the compiled in set of unit load paths; see
 225     <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
 226     All units files present in the directories containing the command line arguments will
 227     be used in preference to the other paths.</para>
 228
 229     <para><command>systemd-analyze calendar</command> will parse and normalize repetitive calendar time events, and
 230     will calculate when they will elapse next. This takes the same input as the <varname>OnCalendar=</varname> setting
 231     in <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>, following the
 232     syntax described in
 233     <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
 234
 235     <para>If no command is passed, <command>systemd-analyze
 236     time</command> is implied.</para>
 237
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>Options</title>
 242
 243     <para>The following options are understood:</para>
 244
 245     <variablelist>
 246       <varlistentry>
 247         <term><option>--user</option></term>
 248
 249         <listitem><para>Operates on the user systemd
 250         instance.</para></listitem>
 251       </varlistentry>
 252
 253       <varlistentry>
 254         <term><option>--system</option></term>
 255
 256         <listitem><para>Operates on the system systemd instance. This
 257         is the implied default.</para></listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><option>--order</option></term>
 262         <term><option>--require</option></term>
 263
 264         <listitem><para>When used in conjunction with the
 265         <command>dot</command> command (see above), selects which
 266         dependencies are shown in the dependency graph. If
 267         <option>--order</option> is passed, only dependencies of type
 268         <varname>After=</varname> or <varname>Before=</varname> are
 269         shown. If <option>--require</option> is passed, only
 270         dependencies of type <varname>Requires=</varname>,
 271         <varname>Requisite=</varname>,
 272         <varname>Wants=</varname> and <varname>Conflicts=</varname>
 273         are shown. If neither is passed, this shows dependencies of
 274         all these types.</para></listitem>
 275       </varlistentry>
 276
 277       <varlistentry>
 278         <term><option>--from-pattern=</option></term>
 279         <term><option>--to-pattern=</option></term>
 280
 281         <listitem><para>When used in conjunction with the
 282         <command>dot</command> command (see above), this selects which
 283         relationships are shown in the dependency graph. Both options
 284         require a
 285         <citerefentry project='die-net'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 286         pattern as an argument, which will be matched against the
 287         left-hand and the right-hand, respectively, nodes of a
 288         relationship.</para>
 289
 290         <para>Each of these can be used more than once, in which case
 291         the unit name must match one of the values. When tests for
 292         both sides of the relation are present, a relation must pass
 293         both tests to be shown. When patterns are also specified as
 294         positional arguments, they must match at least one side of the
 295         relation. In other words, patterns specified with those two
 296         options will trim the list of edges matched by the positional
 297         arguments, if any are given, and fully determine the list of
 298         edges shown otherwise.</para></listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
 303
 304         <listitem><para>When used in conjunction with the
 305         <command>critical-chain</command> command (see above), also
 306         show units, which finished <replaceable>timespan</replaceable>
 307         earlier, than the latest unit in the same level. The unit of
 308         <replaceable>timespan</replaceable> is seconds unless
 309         specified with a different unit, e.g.
 310         "50ms".</para></listitem>
 311       </varlistentry>
 312
 313       <varlistentry>
 314         <term><option>--man=no</option></term>
 315
 316         <listitem><para>Do not invoke man to verify the existence of
 317         man pages listed in <varname>Documentation=</varname>.
 318         </para></listitem>
 319       </varlistentry>
 320
 321       <varlistentry>
 322         <term><option>--generators</option></term>
 323
 324         <listitem><para>Invoke unit generators, see
 325         <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 326         Some generators require root privileges. When run under a
 327         normal users, enabling generators will generally result in
 328         some warnings.</para></listitem>
 329       </varlistentry>
 330
 331       <xi:include href="user-system-options.xml" xpointer="host" />
 332       <xi:include href="user-system-options.xml" xpointer="machine" />
 333
 334       <xi:include href="standard-options.xml" xpointer="help" />
 335       <xi:include href="standard-options.xml" xpointer="version" />
 336       <xi:include href="standard-options.xml" xpointer="no-pager" />
 337     </variablelist>
 338
 339   </refsect1>
 340
 341   <refsect1>
 342     <title>Exit status</title>
 343
 344     <para>On success, 0 is returned, a non-zero failure code
 345     otherwise.</para>
 346   </refsect1>
 347
 348   <refsect1>
 349     <title>Examples for <command>dot</command></title>
 350
 351     <example>
 352       <title>Plots all dependencies of any unit whose name starts with
 353       <literal>avahi-daemon</literal></title>
 354
 355       <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
 356 $ eog avahi.svg</programlisting>
 357     </example>
 358
 359     <example>
 360       <title>Plots the dependencies between all known target units</title>
 361
 362       <programlisting>$ systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
 363 $ eog targets.svg</programlisting>
 364     </example>
 365   </refsect1>
 366
 367   <refsect1>
 368     <title>Examples for <command>verify</command></title>
 369
 370     <para>The following errors are currently detected:</para>
 371     <itemizedlist>
 372       <listitem><para>unknown sections and directives,
 373       </para></listitem>
 374
 375       <listitem><para>missing dependencies which are required to start
 376       the given unit,</para></listitem>
 377
 378       <listitem><para>man pages listed in
 379       <varname>Documentation=</varname> which are not found in the
 380       system,</para></listitem>
 381
 382       <listitem><para>commands listed in <varname>ExecStart=</varname>
 383       and similar which are not found in the system or not
 384       executable.</para></listitem>
 385     </itemizedlist>
 386
 387     <example>
 388       <title>Misspelt directives</title>
 389
 390       <programlisting>$ cat ./user.slice
 391 [Unit]
 392 WhatIsThis=11
 393 Documentation=man:nosuchfile(1)
 394 Requires=different.service
 395
 396 [Service]
 397 Description=x
 398
 399 $ systemd-analyze verify ./user.slice
 400 [./user.slice:9] Unknown lvalue 'WhatIsThis' in section 'Unit'
 401 [./user.slice:13] Unknown section 'Service'. Ignoring.
 402 Error: org.freedesktop.systemd1.LoadFailed:
 403    Unit different.service failed to load:
 404    No such file or directory.
 405 Failed to create user.slice/start: Invalid argument
 406 user.slice: man nosuchfile(1) command failed with code 16
 407       </programlisting>
 408     </example>
 409
 410     <example>
 411       <title>Missing service units</title>
 412
 413       <programlisting>$ tail ./a.socket ./b.socket
 414 ==> ./a.socket &lt;==
 415 [Socket]
 416 ListenStream=100
 417
 418 ==> ./b.socket &lt;==
 419 [Socket]
 420 ListenStream=100
 421 Accept=yes
 422
 423 $ systemd-analyze verify ./a.socket ./b.socket
 424 Service a.service not loaded, a.socket cannot be started.
 425 Service b@0.service not loaded, b.socket cannot be started.
 426       </programlisting>
 427     </example>
 428   </refsect1>
 429
 430   <xi:include href="less-variables.xml" />
 431
 432   <refsect1>
 433     <title>See Also</title>
 434     <para>
 435       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 436       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 437     </para>
 438   </refsect1>
 439
 440 </refentry>