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
  26         <refentryinfo>
  27                 <title>systemd-analyze</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                         <author>
  38                                 <contrib>Developer</contrib>
  39                                 <firstname>Harald</firstname>
  40                                 <surname>Hoyer</surname>
  41                                 <email>harald@redhat.com</email>
  42                         </author>
  43                 </authorgroup>
  44         </refentryinfo>
  45
  46         <refmeta>
  47                 <refentrytitle>systemd-analyze</refentrytitle>
  48                 <manvolnum>1</manvolnum>
  49         </refmeta>
  50
  51         <refnamediv>
  52                 <refname>systemd-analyze</refname>
  53                 <refpurpose>Analyze system boot-up performance</refpurpose>
  54         </refnamediv>
  55
  56         <refsynopsisdiv>
  57                 <cmdsynopsis>
  58                         <command>systemd-analyze</command>
  59                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  60                         <arg>time</arg>
  61                 </cmdsynopsis>
  62                 <cmdsynopsis>
  63                         <command>systemd-analyze</command>
  64                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  65                         <arg choice="plain">blame</arg>
  66                 </cmdsynopsis>
  67                 <cmdsynopsis>
  68                         <command>systemd-analyze</command>
  69                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  70                         <arg choice="plain">critical-chain</arg>
  71                         <arg choice="opt" rep="repeat"><replaceable>UNIT</replaceable></arg>
  72                 </cmdsynopsis>
  73                 <cmdsynopsis>
  74                         <command>systemd-analyze</command>
  75                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  76                         <arg choice="plain">plot</arg>
  77                         <arg choice="opt">&gt; file.svg</arg>
  78                 </cmdsynopsis>
  79                 <cmdsynopsis>
  80                         <command>systemd-analyze</command>
  81                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  82                         <arg choice="plain">dot</arg>
  83                         <arg choice="opt" rep="repeat"><replaceable>PATTERN</replaceable></arg>
  84                 </cmdsynopsis>
  85                 <cmdsynopsis>
  86                         <command>systemd-analyze</command>
  87                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  88                         <arg choice="plain">dump</arg>
  89                 </cmdsynopsis>
  90         </refsynopsisdiv>
  91
  92         <refsect1>
  93                 <title>Description</title>
  94
  95                 <para><command>systemd-analyze</command> may be used
  96                 to determine system boot-up performance of the current
  97                 boot.</para>
  98
  99                 <para><command>systemd-analyze time</command>
 100                 prints the time spent in the kernel before
 101                 userspace has been reached, the time spent in the
 102                 initial RAM disk (initrd) before normal system
 103                 userspace has been reached, and the time normal system
 104                 userspace took to initialize. Note that these
 105                 measurements simply measure the time passed up to the
 106                 point where all system services have been spawned, but
 107                 not necessarily until they fully finished
 108                 initialization or the disk is idle.</para>
 109
 110                 <para><command>systemd-analyze blame</command> prints
 111                 a list of all running units, ordered by the time they
 112                 took to initialize. This information may be used to
 113                 optimize boot-up times. Note that the output might be
 114                 misleading as the initialization of one service might
 115                 be slow simply because it waits for the initialization
 116                 of another service to complete.</para>
 117
 118                 <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command>
 119                 prints a tree of the time-critical chain of units
 120                 (for each of the specified <replaceable>UNIT</replaceable>s
 121                 or for the default target otherwise).
 122                 The time after the unit is active or started is printed
 123                 after the "@" character. The time the unit takes to
 124                 start is printed after the "+" character.
 125                 Note that the output might be misleading as the
 126                 initialization of one service might depend on socket
 127                 activation and because of the parallel execution
 128                 of units.</para>
 129
 130                 <para><command>systemd-analyze plot</command> prints
 131                 an SVG graphic detailing which system services have
 132                 been started at what time, highlighting the time they
 133                 spent on initialization.</para>
 134
 135                 <para><command>systemd-analyze dot</command> generates
 136                 textual dependency graph description in dot format for
 137                 further processing with the GraphViz
 138                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 139                 tool. Use a command line like <command>systemd-analyze
 140                 dot | dot -Tsvg > systemd.svg</command> to generate a
 141                 graphical dependency tree. Unless
 142                 <option>--order</option> or <option>--require</option>
 143                 is passed, the generated graph will show both ordering
 144                 and requirement dependencies. Optional pattern
 145                 globbing style specifications
 146                 (e.g. <filename>*.target</filename>) may be given at
 147                 the end. A unit dependency is included in the graph if
 148                 any of these patterns match either the origin or
 149                 destination node.</para>
 150
 151                 <para><command>systemd-analyze dump</command> outputs
 152                 a (usually very long) human-readable serialization of
 153                 the complete server state. Its format is subject to
 154                 change without notice and should not be parsed by
 155                 applications.</para>
 156
 157                 <para>If no command is passed, <command>systemd-analyze
 158                 time</command> is implied.</para>
 159
 160         </refsect1>
 161
 162         <refsect1>
 163                 <title>Options</title>
 164
 165                 <para>The following options are understood:</para>
 166
 167                 <variablelist>
 168                         <varlistentry>
 169                                 <term><option>-h</option></term>
 170                                 <term><option>--help</option></term>
 171
 172                                 <listitem><para>Prints a short help
 173                                 text and exits.</para></listitem>
 174                         </varlistentry>
 175
 176                         <varlistentry>
 177                                 <term><option>--user</option></term>
 178
 179                                 <listitem><para>Shows performance data
 180                                 of user sessions instead of the system
 181                                 manager.</para></listitem>
 182                         </varlistentry>
 183
 184                         <varlistentry>
 185                                 <term><option>--order</option></term>
 186                                 <term><option>--require</option></term>
 187
 188                                 <listitem><para>When used in
 189                                 conjunction with the
 190                                 <command>dot</command> command (see
 191                                 above), selects which dependencies are
 192                                 shown in the dependency graph. If
 193                                 <option>--order</option> is passed
 194                                 only dependencies of type
 195                                 <varname>After=</varname> or
 196                                 <varname>Before=</varname> are
 197                                 shown. If <option>--require</option>
 198                                 is passed only dependencies of type
 199                                 <varname>Requires=</varname>,
 200                                 <varname>RequiresOverridable=</varname>,
 201                                 <varname>Requisite=</varname>,
 202                                 <varname>RequisiteOverridable=</varname>,
 203                                 <varname>Wants=</varname> and
 204                                 <varname>Conflicts=</varname> are
 205                                 shown. If neither is passed, this shows
 206                                 dependencies of all these
 207                                 types.</para></listitem>
 208                         </varlistentry>
 209
 210                         <varlistentry>
 211                                 <term><option>--from-pattern=</option></term>
 212                                 <term><option>--to-pattern=</option></term>
 213
 214                                 <listitem><para>When used in
 215                                 conjunction with the
 216                                 <command>dot</command> command (see
 217                                 above), this selects which relationships
 218                                 are shown in the dependency graph.
 219                                 They both require
 220                                 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 221                                 patterns as arguments, which are
 222                                 matched against left-hand and
 223                                 right-hand, respectively, nodes of a
 224                                 relationship. Each of these can be
 225                                 used more than once, which means a
 226                                 unit name must match one of the given
 227                                 values.</para></listitem>
 228                         </varlistentry>
 229
 230                         <varlistentry>
 231                                 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
 232
 233                                 <listitem><para>When used in conjunction
 234                                 with the <command>critical-chain</command>
 235                                 command (see above), also show units, which
 236                                 finished <replaceable>timespan</replaceable> earlier, than the
 237                                 latest unit in the same level. The unit of
 238                                 <replaceable>timespan</replaceable> is seconds
 239                                 unless specified with a different unit,
 240                                 e.g. "50ms".</para></listitem>
 241                         </varlistentry>
 242
 243                         <varlistentry>
 244                                 <term><option>--no-pager</option></term>
 245
 246                                 <listitem>
 247                                         <para>Do not pipe output into a pager.</para>
 248                                 </listitem>
 249                         </varlistentry>
 250                 </variablelist>
 251
 252         </refsect1>
 253
 254         <refsect1>
 255                 <title>Exit status</title>
 256
 257                 <para>On success 0 is returned, a non-zero failure
 258                 code otherwise.</para>
 259         </refsect1>
 260
 261         <refsect1>
 262                 <title>Examples</title>
 263
 264                 <para>This plots all dependencies of any unit whose
 265                 name starts with <literal>avahi-daemon.</literal>:</para>
 266
 267                 <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
 268 $ eog avahi.svg</programlisting>
 269
 270                 <para>This plots the dependencies between all known target units:</para>
 271
 272                 <programlisting>systemd-analyze dot --to-pattern='*.target' --from-patter='*.target' | dot -Tsvg > targets.svg
 273 $ eog targets.svg</programlisting>
 274
 275
 276         </refsect1>
 277
 278         <refsect1>
 279                 <title>Environment</title>
 280
 281                 <variablelist class='environment-variables'>
 282                         <varlistentry>
 283                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 284
 285                                 <listitem>
 286                                         <para>Pager to use when <option>--no-pager</option> is not
 287                                         given; overrides <varname>$PAGER</varname>.  Setting this to
 288                                         an empty string or the value <literal>cat</literal> is
 289                                         equivalent to passing
 290                                         <option>--no-pager</option>.</para>
 291                                 </listitem>
 292                         </varlistentry>
 293                 </variablelist>
 294         </refsect1>
 295
 296         <refsect1>
 297                 <title>See Also</title>
 298                 <para>
 299                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 300                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 301                 </para>
 302         </refsect1>
 303
 304 </refentry>