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