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