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                         <arg choice="opt">&gt; file.dot</arg>
  85                 </cmdsynopsis>
  86                 <cmdsynopsis>
  87                         <command>systemd-analyze</command>
  88                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  89                         <arg choice="plain">dump</arg>
  90                 </cmdsynopsis>
  91                 <cmdsynopsis>
  92                         <command>systemd-analyze</command>
  93                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  94                         <arg choice="plain">set-log-level</arg>
  95                         <arg choice="opt"><replaceable>LEVEL</replaceable></arg>
  96                 </cmdsynopsis>
  97         </refsynopsisdiv>
  98
  99         <refsect1>
 100                 <title>Description</title>
 101
 102                 <para><command>systemd-analyze</command> may be used
 103                 to determine system boot-up performance statistics and
 104                 retrieve other state and tracing information from the
 105                 system and service manager.</para>
 106
 107                 <para><command>systemd-analyze time</command>
 108                 prints the time spent in the kernel before
 109                 userspace has been reached, the time spent in the
 110                 initial RAM disk (initrd) before normal system
 111                 userspace has been reached, and the time normal system
 112                 userspace took to initialize. Note that these
 113                 measurements simply measure the time passed up to the
 114                 point where all system services have been spawned, but
 115                 not necessarily until they fully finished
 116                 initialization or the disk is idle.</para>
 117
 118                 <para><command>systemd-analyze blame</command> prints
 119                 a list of all running units, ordered by the time they
 120                 took to initialize. This information may be used to
 121                 optimize boot-up times. Note that the output might be
 122                 misleading as the initialization of one service might
 123                 be slow simply because it waits for the initialization
 124                 of another service to complete.</para>
 125
 126                 <para><command>systemd-analyze critical-chain [<replaceable>UNIT...</replaceable>]</command>
 127                 prints a tree of the time-critical chain of units
 128                 (for each of the specified <replaceable>UNIT</replaceable>s
 129                 or for the default target otherwise).
 130                 The time after the unit is active or started is printed
 131                 after the "@" character. The time the unit takes to
 132                 start is printed after the "+" character.
 133                 Note that the output might be misleading as the
 134                 initialization of one service might depend on socket
 135                 activation and because of the parallel execution
 136                 of units.</para>
 137
 138                 <para><command>systemd-analyze plot</command> prints
 139                 an SVG graphic detailing which system services have
 140                 been started at what time, highlighting the time they
 141                 spent on initialization.</para>
 142
 143                 <para><command>systemd-analyze dot</command> generates
 144                 textual dependency graph description in dot format for
 145                 further processing with the GraphViz
 146                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 147                 tool. Use a command line like <command>systemd-analyze
 148                 dot | dot -Tsvg > systemd.svg</command> to generate a
 149                 graphical dependency tree. Unless
 150                 <option>--order</option> or <option>--require</option>
 151                 is passed, the generated graph will show both ordering
 152                 and requirement dependencies. Optional pattern
 153                 globbing style specifications
 154                 (e.g. <filename>*.target</filename>) may be given at
 155                 the end. A unit dependency is included in the graph if
 156                 any of these patterns match either the origin or
 157                 destination node.</para>
 158
 159                 <para><command>systemd-analyze dump</command> outputs
 160                 a (usually very long) human-readable serialization of
 161                 the complete server state. Its format is subject to
 162                 change without notice and should not be parsed by
 163                 applications.</para>
 164
 165                 <para><command>systemd-analyze set-log-level
 166                 <replaceable>LEVEL</replaceable></command> changes the
 167                 current log level of the <command>systemd</command>
 168                 daemon to <replaceable>LEVEL</replaceable> (accepts
 169                 the same values as <option>--log-level=</option>
 170                 described in
 171                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para>
 172
 173                 <para>If no command is passed, <command>systemd-analyze
 174                 time</command> is implied.</para>
 175
 176         </refsect1>
 177
 178         <refsect1>
 179                 <title>Options</title>
 180
 181                 <para>The following options are understood:</para>
 182
 183                 <variablelist>
 184                         <varlistentry>
 185                                 <term><option>-h</option></term>
 186                                 <term><option>--help</option></term>
 187
 188                                 <listitem><para>Prints a short help
 189                                 text and exits.</para></listitem>
 190                         </varlistentry>
 191
 192                         <varlistentry>
 193                                 <term><option>--user</option></term>
 194
 195                                 <listitem><para>Shows performance data
 196                                 of user sessions instead of the system
 197                                 manager.</para></listitem>
 198                         </varlistentry>
 199
 200                         <varlistentry>
 201                                 <term><option>--system</option></term>
 202
 203                                 <listitem><para>Shows performance data
 204                                 of the system manager. This is the
 205                                 implied default.</para></listitem>
 206                         </varlistentry>
 207
 208                         <varlistentry>
 209                                 <term><option>-H</option></term>
 210                                 <term><option>--host=</option></term>
 211
 212                                 <listitem><para>Execute the operation
 213                                 remotely. Specify a hostname, or
 214                                 username and hostname separated by
 215                                 <literal>@</literal>, to connect
 216                                 to. This will use SSH to talk to the
 217                                 remote machine manager
 218                                 instance.</para></listitem>
 219                         </varlistentry>
 220
 221                         <varlistentry>
 222                                 <term><option>-M</option></term>
 223                                 <term><option>--machine=</option></term>
 224
 225                                 <listitem><para>Execute the operation on a
 226                                 local container. Specify a container
 227                                 name to connect to.</para></listitem>
 228                         </varlistentry>
 229
 230                         <varlistentry>
 231                                 <term><option>--order</option></term>
 232                                 <term><option>--require</option></term>
 233
 234                                 <listitem><para>When used in
 235                                 conjunction with the
 236                                 <command>dot</command> command (see
 237                                 above), selects which dependencies are
 238                                 shown in the dependency graph. If
 239                                 <option>--order</option> is passed,
 240                                 only dependencies of type
 241                                 <varname>After=</varname> or
 242                                 <varname>Before=</varname> are
 243                                 shown. If <option>--require</option>
 244                                 is passed, only dependencies of type
 245                                 <varname>Requires=</varname>,
 246                                 <varname>RequiresOverridable=</varname>,
 247                                 <varname>Requisite=</varname>,
 248                                 <varname>RequisiteOverridable=</varname>,
 249                                 <varname>Wants=</varname> and
 250                                 <varname>Conflicts=</varname> are
 251                                 shown. If neither is passed, this shows
 252                                 dependencies of all these
 253                                 types.</para></listitem>
 254                         </varlistentry>
 255
 256                         <varlistentry>
 257                                 <term><option>--from-pattern=</option></term>
 258                                 <term><option>--to-pattern=</option></term>
 259
 260                                 <listitem><para>When used in
 261                                 conjunction with the
 262                                 <command>dot</command> command (see
 263                                 above), this selects which relationships
 264                                 are shown in the dependency graph.
 265                                 They both require
 266                                 <citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 267                                 patterns as arguments, which are
 268                                 matched against left-hand and
 269                                 right-hand, respectively, nodes of a
 270                                 relationship. Each of these can be
 271                                 used more than once, which means a
 272                                 unit name must match one of the given
 273                                 values.</para></listitem>
 274                         </varlistentry>
 275
 276                         <varlistentry>
 277                                 <term><option>--fuzz=</option><replaceable>timespan</replaceable></term>
 278
 279                                 <listitem><para>When used in conjunction
 280                                 with the <command>critical-chain</command>
 281                                 command (see above), also show units, which
 282                                 finished <replaceable>timespan</replaceable> earlier, than the
 283                                 latest unit in the same level. The unit of
 284                                 <replaceable>timespan</replaceable> is seconds
 285                                 unless specified with a different unit,
 286                                 e.g. "50ms".</para></listitem>
 287                         </varlistentry>
 288
 289                         <varlistentry>
 290                                 <term><option>--no-pager</option></term>
 291
 292                                 <listitem>
 293                                         <para>Do not pipe output into a pager.</para>
 294                                 </listitem>
 295                         </varlistentry>
 296                 </variablelist>
 297
 298         </refsect1>
 299
 300         <refsect1>
 301                 <title>Exit status</title>
 302
 303                 <para>On success 0 is returned, a non-zero failure
 304                 code otherwise.</para>
 305         </refsect1>
 306
 307         <refsect1>
 308                 <title>Examples</title>
 309
 310                 <para>This plots all dependencies of any unit whose
 311                 name starts with <literal>avahi-daemon.</literal>:</para>
 312
 313                 <programlisting>$ systemd-analyze dot 'avahi-daemon.*' | dot -Tsvg > avahi.svg
 314 $ eog avahi.svg</programlisting>
 315
 316                 <para>This plots the dependencies between all known target units:</para>
 317
 318                 <programlisting>systemd-analyze dot --to-pattern='*.target' --from-pattern='*.target' | dot -Tsvg > targets.svg
 319 $ eog targets.svg</programlisting>
 320
 321
 322         </refsect1>
 323
 324         <refsect1>
 325                 <title>Environment</title>
 326
 327                 <variablelist class='environment-variables'>
 328                         <varlistentry>
 329                                 <term><varname>$SYSTEMD_PAGER</varname></term>
 330
 331                                 <listitem>
 332                                         <para>Pager to use when <option>--no-pager</option> is not
 333                                         given; overrides <varname>$PAGER</varname>.  Setting this to
 334                                         an empty string or the value <literal>cat</literal> is
 335                                         equivalent to passing
 336                                         <option>--no-pager</option>.</para>
 337                                 </listitem>
 338                         </varlistentry>
 339                 </variablelist>
 340         </refsect1>
 341
 342         <refsect1>
 343                 <title>See Also</title>
 344                 <para>
 345                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 346                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 347                 </para>
 348         </refsect1>
 349
 350 </refentry>