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