development: add boottime graph howto

docs/contributing/development.rst

@@ -683,31 +683,23 @@ passed as kernel boot parameters.
 Kernel boot parameters
 ----------------------
 
-``vyos-debug``
+* ``vyos-debug`` - Adding the parameter to the linux boot line will produce
-^^^^^^^^^^^^^^
+  timing results for the execution of scripts during commit. If one is seeing
-
+  an unexpected delay during manual or boot commit, this may be useful in
-Adding the parameter ``vyos-debug`` to the linux boot line will produce
+  identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found
-timing results for the execution of scripts during commit. If one is seeing
+  in vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``.
-an unexpected delay during manual or boot commit, this may be useful in
-identifying bottlenecks. The internal flag is ``VYOS_DEBUG``, and is found in
-vyatta-cfg_. Output is directed to ``/var/log/vyatta/cfg-stdout.log``.
-
-``vyos-config-debug``
-^^^^^^^^^^^^^^^^^^^^^
-
-During development, coding errors can lead to a commit failure on boot,
-possibly resulting in a failed initialization of the CLI. In this
-circumstance, the kernel boot parameter ``vyos-config-debug`` will ensure
-access to the system as user ``vyos``, and will log a Python stack trace to
-``/tmp/boot-config-trace``.
 
+* ``vyos-config-debug`` - During development, coding errors can lead to a
+  commit failure on boot, possibly resulting in a failed initialization of the
+  CLI. In this circumstance, the kernel boot parameter ``vyos-config-debug``
+  will ensure access to the system as user ``vyos``, and will log a Python
+  stack trace to the file ``/tmp/boot-config-trace``.
 
 Debugging features
 ------------------
 
 A number of flags can be set up to change the behaviour of VyOS at runtime.
-These flags can be toggled using either environment variables or creating
+These flags can be toggled using either environment variables or creating files.
-files.
 
 For each feature, a file called ``vyos.feature.debug`` can be created to toggle
 the feature on. If a parameter is required it can be placed inside the file as
@@ -725,35 +717,22 @@ In that case, the name will be (in uppercase) VYOS_FEATURE_DEBUG.
 for example running, ``export VYOS_IFCONFIG_DEBUG=""`` on your vash, will have
 the same effect as ``touch /tmp/vyos.ifconfig.debug``.
 
-``ifconfig``
+* ``ifconfig`` - Once set, all commands used, and their responses received from
-^^^^^^^^^^^^
+  the OS, will be presented on the screen for inspection.
 
-Once set, all commands used, and their responses received from the OS, will be
+* ``command`` - Once set, all commands used, and their responses received from
-presented on the screen for inspection.
+  the OS, will be presented on the screen for inspection.
 
-``command``
+* ``developer`` - Should a command fail, instead of printing a message to the
-^^^^^^^^^^^
+  user explaining how to report issues, the python interpreter will start a PBD
+  post-mortem session to allow the developer to debug the issue. As the debugger
+  will wait from input from the developer, it has the capacity to prevent a
+  router to boot and therefore should only be permanently set up on production
+  if you are ready to see the OS fail to boot.
 
-Once set, all commands used, and their responses received from the OS, will be 
+* ``log`` - In some rare cases, it may be useful to see what the OS is doing,
-presented on the screen for inspection.
+  including during boot. This option sends all commands used by VyOS to a file.
-
+  The default file is ``/tmp/full-log`` but it can be changed.
-``developer``
-^^^^^^^^^^^^^
-
-Should a command fail, instead of printing a message to the user explaining how
-to report issues, the python interpreter will start a PBD post-mortem session
-to allow the developer to debug the issue.
-
-As the debugger will wait from input from the developer, it has the capacity to
-prevent a router to boot and therefore should only be permanently set up on 
-production if you are ready to see the OS fail to boot.
-
-``log``
-^^^^^^^
-
-In some rare cases, it may be useful to see what the OS is doing, including
-during boot. This option sends all commands used by VyOS to a file. 
-The default file is ``/tmp/full-log`` but it can be changed.
 
 Config Migration
 ----------------
@@ -780,6 +759,23 @@ own by:
 
   vyos@vyos:~$ /usr/libexec/vyos/run-config-migration.py --virtual --set-vintage vyos /tmp/config.boot
 
+Boot Timing
+-----------
+
+During the migration and extensive rewrite of functionality from Perl into
+Python a significant increase in the overall system boottime was noticed. The
+system boot time can be analysed and a graph can be generated in the end which
+shows in detail who called whom during the system startup phase.
+
+This is done by utilizing the ``systemd-bootchart`` package which is now
+installed by default on the VyOS 1.3 (equuleus) branch. The configuration is
+also versioned so we get comparable results. ``systemd-bootchart`` is configured
+using this file: bootchart.conf_
+
+To enable boot time graphing change the Kernel commandline and add the folowing
+string: ``init=/usr/lib/systemd/systemd-bootchart``
+
+This can also be done permanently by changing ``/boot/grub/grub.cfg``.
 
 Priorities
 ==========
@@ -823,5 +819,6 @@ http://dev.packages.vyos.net/repositories/.
 .. _`VLAN (VIF)`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/vif.xml.i
 .. _`MAC address`: https://github.com/vyos/vyos-1x/tree/current/interface-definitions/include/interface-mac.xml.i
 .. _vyatta-cfg: https://github.com/vyos/vyatta-cfg
+.. _bootchart.conf: https://github.com/vyos/vyos-build/blob/current/data/live-build-config/includes.chroot/etc/systemd/bootchart.conf
 
 .. include:: ../common-references.rst