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