Imported Upstream version 219

[systemd.git] / man / systemd-bootchart.1

'\" t
.TH "SYSTEMD\-BOOTCHART" "1" "" "systemd 219" "systemd-bootchart"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd-bootchart \- Boot performance graphing tool
.SH "DESCRIPTION"
.PP
\fBsystemd\-bootchart\fR
is a tool, usually run at system startup, that collects the CPU load, disk load, memory usage, as well as per\-process information from a running system\&. Collected results are output as an SVG graph\&. Normally, systemd\-bootchart is invoked by the kernel by passing
\fBinit=\fR\fB/usr/lib/systemd/systemd\-bootchart\fR
on the kernel command line\&. systemd\-bootchart will then fork the real init off to resume normal system startup, while monitoring and logging startup information in the background\&.
.PP
After collecting a certain amount of data (usually 15\-30 seconds, default 20 s) the logging stops and a graph is generated from the logged information\&. This graph contains vital clues as to which resources are being used, in which order, and where possible problems exist in the startup sequence of the system\&. It is essentially a more detailed version of the
\fBsystemd\-analyze plot\fR
function\&.
.PP
Of course, bootchart can also be used at any moment in time to collect and graph some data for an amount of time\&. It is recommended to use the
\fB\-\-rel\fR
switch in this case\&.
.PP
Bootchart does not require root privileges, and will happily run as a normal user\&.
.PP
Bootchart graphs are by default written time\-stamped in
/run/log
and saved to the journal with
\fIMESSAGE_ID=9f26aa562cf440c2b16c773d0479b518\fR\&. Journal field
\fIBOOTCHART=\fR
contains the bootchart in SVG format\&.
.SH "INVOCATION"
.PP
\fBsystemd\-bootchart\fR
can be invoked in several different ways:
.PP
\fIKernel invocation\fR
.RS 4
The kernel can invoke
\fBsystemd\-bootchart\fR
instead of the init process\&. In turn,
\fBsystemd\-bootchart\fR
will invoke
\fB/usr/lib/systemd/systemd\fR\&.
.RE
.PP
\fIStarted as a standalone program\fR
.RS 4
One can execute
\fBsystemd\-bootchart\fR
as normal application from the command line\&. In this mode it is highly recommended to pass the
\fB\-r\fR
flag in order to not graph the time elapsed since boot and before systemd\-bootchart was started, as it may result in extremely large graphs\&. The time elapsed since boot might also include any time that the system was suspended\&.
.RE
.SH "OPTIONS"
.PP
These options can also be set in the
/etc/systemd/bootchart\&.conf
file\&. See
\fBbootchart.conf\fR(5)\&.
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Print a short help text and exit\&.
.RE
.PP
\fB\-n\fR, \fB\-\-sample \fR\fB\fIN\fR\fR
.RS 4
Specify the number of samples,
\fIN\fR, to record\&. Samples will be recorded at intervals defined with
\fB\-\-freq\fR\&.
.RE
.PP
\fB\-f\fR, \fB\-\-freq \fR\fB\fIf\fR\fR
.RS 4
Specify the sample log frequency, a positive real
\fIf\fR, in Hz\&. Most systems can cope with values up to 25\-50 without creating too much overhead\&.
.RE
.PP
\fB\-r\fR, \fB\-\-rel\fR
.RS 4
Use relative times instead of absolute times\&. This is useful for using bootchart at post\-boot time to profile an already booted system\&. Without this option the graph would become extremely large\&. If set, the horizontal axis starts at the first recorded sample instead of time 0\&.0\&.
.RE
.PP
\fB\-F\fR, \fB\-\-no\-filter\fR
.RS 4
Disable filtering of tasks that did not contribute significantly to the boot\&. Processes that are too short\-lived (only seen in one sample) or that do not consume any significant CPU time (less than 0\&.001 s) will not be displayed in the output graph\&.
.RE
.PP
\fB\-C\fR, \fB\-\-cmdline\fR
.RS 4
Display the full command line with arguments of processes, instead of only the process name\&.
.RE
.PP
\fB\-g\fR, \fB\-\-control\-group\fR
.RS 4
Display process control group
.RE
.PP
\fB\-o\fR, \fB\-\-output \fR\fB\fIpath\fR\fR
.RS 4
Specify the output directory for the graphs\&. By default, bootchart writes the graphs to
/run/log\&.
.RE
.PP
\fB\-i\fR, \fB\-\-init \fR\fB\fIpath\fR\fR
.RS 4
Use this init binary\&. Defaults to
\fB/usr/lib/systemd/systemd\fR\&.
.RE
.PP
\fB\-p\fR, \fB\-\-pss\fR
.RS 4
Enable logging and graphing of processes\*(Aq PSS (Proportional Set Size) memory consumption\&. See
filesystems/proc\&.txt
in the kernel documentation for an explanation of this field\&.
.RE
.PP
\fB\-e\fR, \fB\-\-entropy\fR
.RS 4
Enable logging and graphing of the kernel random entropy pool size\&.
.RE
.PP
\fB\-x\fR, \fB\-\-scale\-x \fR\fB\fIN\fR\fR
.RS 4
Horizontal scaling factor for all variable graph components\&.
.RE
.PP
\fB\-y\fR, \fB\-\-scale\-y \fR\fB\fIN\fR\fR
.RS 4
Vertical scaling factor for all variable graph components\&.
.RE
.SH "OUTPUT"
.PP
\fBsystemd\-bootchart\fR
generates SVG graphs\&. In order to render those on a graphical display any SVG capable viewer can be used\&. It should be noted that the SVG render engines in most browsers (including Chrome and Firefox) are many times faster than dedicated graphical applications like Gimp and Inkscape\&. Just point your browser at
\m[blue]\fB\%file:///run/log/\fR\m[]!
.SH "HISTORY"
.PP
This version of bootchart was implemented from scratch, but is inspired by former bootchart incantations:
.PP
\fIOriginal bash\fR
.RS 4
The original bash/shell code implemented bootchart\&. This version created a compressed tarball for processing with external applications\&. This version did not graph anything, only generated data\&.
.RE
.PP
\fIUbuntu C Implementation\fR
.RS 4
This version replaced the shell version with a fast and efficient data logger, but also did not graph the data\&.
.RE
.PP
\fIJava bootchart\fR
.RS 4
This was the original graphing application for charting the data, written in java\&.
.RE
.PP
\fIpybootchartgui\&.py\fR
.RS 4
pybootchart created a graph from the data collected by either the bash or C version\&.
.RE
.PP
The version of bootchart you are using now combines both the data collection and the charting into a single application, making it more efficient and simpler\&. There are no longer any timing issues with the data collector and the grapher, as the graphing cannot be run until the data has been collected\&. Also, the data kept in memory is reduced to the absolute minimum needed\&.
.SH "SEE ALSO"
.PP
\fBbootchart.conf\fR(5)
.SH "BUGS"
.PP
systemd\-bootchart does not get the model information for the hard drive unless the root device is specified with
root=/dev/sdxY\&. Using UUIDs or PARTUUIDs will boot fine, but the hard drive model will not be added to the chart\&.
.PP
For bugs, please contact the author and current maintainer:
.RS 4
Auke Kok <auke\-jan\&.h\&.kok@intel\&.com>
.RE