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