Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 395 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man1/sadf.1 b/upstream/debian-unstable/man1/sadf.1
new file mode 100644
index 00000000..0d7e7604
--- /dev/null
+++ b/upstream/debian-unstable/man1/sadf.1
@@ -0,0 +1,395 @@
+.\" sadf manual page - (C) 1999-2023 Sebastien Godard (sysstat <at> orange.fr)
+.TH SADF 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*-
+.SH NAME
+sadf \- Display data collected by sar in multiple formats.
+
+.SH SYNOPSIS
+.B sadf [ \-C ] [ \-c | \-d | \-g | \-j | \-l | \-p | \-r | \-x ] [ \-H ] [ \-h ] [ \-T | \-t | \-U ] [ \-V ] [ \-O
+.IB "opts " "[,...] ] [ \-P { " "cpu_list " "| ALL } ] [ \-s [ "
+.IB "start_time " "] ] ] [ \-e [ " "end_time " "] ] ]"
+.BI "[ \-\-dev=" "dev_list " "] [ \-\-fs=" "fs_list " "] [ \-\-iface=" "iface_list" "] [ \-\-int=" "int_list " "] [ \-\-"
+.IB "sar_options " "] [ " "interval " "[ " "count " "] ] [ " "datafile " "| " "\-[0\-9]+ " "]"
+
+.SH DESCRIPTION
+.RB "The " "sadf"
+command is used for displaying the contents of data files created by the
+.BR "sar" "(1) command. But unlike " "sar" ", " "sadf"
+can write its data in many different formats (CSV, XML, etc.)
+The default format is one that can
+easily be handled by pattern processing commands like
+.BR "awk " "(see option " "\-p" "). The " "sadf"
+command can also be used to draw graphs for the various activities collected by
+.B sar
+and display them as SVG (Scalable Vector Graphics) graphics in your web browser
+(see option
+.BR "\-g" ")."
+.PP
+.RB "The " "sadf"
+command extracts and writes to standard output records saved in the
+.I datafile
+file. This file must have been created by a version of
+.BR "sar " "which is compatible with that of " "sadf" ". If"
+.I datafile
+.RB "is omitted, " "sadf"
+uses the standard system activity daily data file.
+It is also possible to enter
+.BR "\-1" ", " "\-2 " "etc. as an argument to " "sadf"
+to display data of that days ago. For example,
+.B \-1
+will point at the standard system activity file of yesterday.
+.PP
+The standard system activity daily data file is named
+.IR "saDD " "or " "saYYYYMMDD" ", where"
+.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD"
+for the current day.
+.B sadf
+will look for the most recent of
+.IR "saDD " "and " "saYYYYMMDD" ","
+and use it. By default it is located in the
+.I /var/log/sysstat
+directory. Yet it is possible to specify an alternate location for it: If
+.I datafile
+is a directory (instead of a plain file) then it will be considered as
+the directory where the standard system activity daily data file is located.
+.PP
+.RI "The " "interval " "and " "count " "parameters are used to tell"
+.BR "sadf " "to select"
+.IR "count " "records at " "interval " "seconds apart. If the " "count"
+parameter is not set, then all the records saved in the data file will be displayed.
+.PP
+All the activity flags of
+.B sar
+may be entered on the command line to indicate which
+activities are to be reported. Before specifying them, put a pair of dashes
+.RB "(" "\-\-" ")"
+on the command line in order not to confuse the flags with those of
+.B sadf.
+Not specifying any flags selects only CPU activity.
+
+.SH OPTIONS
+.TP
+.B \-C
+.RB "Tell " "sadf " "to display comments present in file."
+.TP
+.B \-c
+Convert an old system activity binary datafile (version 9.1.6 and later)
+to current up-to-date format. Use the following syntax:
+
+.BI "sadf \-c " "old_datafile " "> " "new_datafile"
+
+Conversion can be controlled using option
+.BR "\-O " "(see below)."
+.TP
+.B \-d
+Print the contents of the data file in a format that can easily
+be ingested by a relational database system. The output consists
+of fields separated by a semicolon. Each record contains
+the hostname of the host where the file was created, the interval value
+(or \-1 if not applicable), the timestamp in a form easily acceptable by
+most databases, and additional semicolon separated data fields as specified by
+.IR "sar_options " "command line options."
+Note that timestamp output can be controlled by options
+.BR "\-T" ", " "\-t " "and " "\-U" "."
+.TP
+.BI "\-\-dev=" "dev_list"
+Specify the block devices for which statistics are to be displayed by
+.BR "sadf" "."
+.I dev_list
+is a list of comma-separated device names. Useful with option
+.BR "\-d " "from " "sar" "."
+.RE
+.PP
+.BI "\-e [ " "hh" ":" "mm" "[:" "ss" "] ]"
+.br
+.BI "\-e [ " "seconds_since_the_epoch " "]"
+.RS
+Set the ending time of the report. The default ending
+time is 18:00:00. Hours must be given in 24-hour format, or as the number of seconds
+since the epoch (given as a 10 digit number).
+.RE
+.TP
+.BI "\-\-fs=" "fs_list"
+Specify the filesystems for which statistics are to be displayed by
+.BR "sadf" "."
+.I fs_list
+is a list of comma-separated filesystem names or mountpoints. Useful with option
+.BR "\-F " "from " "sar" "."
+.TP
+.B \-g
+Print the contents of the data file in SVG (Scalable Vector Graphics) format.
+This option enables you to display some fancy graphs in your web browser.
+Use the following syntax:
+
+.BI "sadf \-g " "your_datafile " "[ \-\- " "sar_options " "] > " "output.svg"
+
+and open the resulting SVG file in your favorite web browser.
+Output can be controlled using option
+.BR "\-O " "(see below)."
+.TP
+.B \-H
+Display only the header of the report (when applicable). If no format has
+been specified, then the header data (metadata) of the data file are displayed.
+.TP
+.B \-h
+When used in conjunction with option
+.BR "\-d" ", all activities will be displayed horizontally on a single line."
+.TP
+.BI "\-\-iface=" "iface_list"
+Specify the network interfaces for which statistics are to be displayed by
+.BR "sadf" "."
+.I iface_list
+is a list of comma-separated interface names. Useful with options
+.BR "\-n DEV " "and " "\-n EDEV " "from " "sar" "."
+.TP
+.BI "\-\-int=" "int_list"
+Specify the interrupts names for which statistics are to be displayed by
+.BR "sadf" "."
+.I int_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0\-16,35,40\-" "). Useful with option " "\-I " "from " "sar" "."
+.TP
+.B \-j
+Print the contents of the data file in JSON (JavaScript Object Notation)
+format. Timestamps can be controlled by options
+.BR "\-T " "and " "\-t" "."
+.TP
+.B \-l
+Export the contents of the data file to a PCP (Performance Co-Pilot) archive.
+The name of the archive can be specified using the keyword
+.BR "pcparchive= " "with option " "\-O" "."
+.TP
+.BI "\-O " "opts" "[,...]"
+Use the specified options to control the output of
+.BR "sadf" "."
+The following options are used to control SVG output displayed by
+.BR "sadf \-g" ":"
+.RS
+.IP autoscale
+Draw all the graphs of a given view as large as possible based on current
+view's scale. To do this, a factor (10, 100, 1000...) is used to
+enlarge the graph drawing.
+This option may be interesting when several graphs are drawn on the same
+view, some with only very small values, and others with high ones,
+the latter making the former hardly visible.
+.IP bwcol
+Use a black and white palette to draw the graphs.
+.IP customcol
+Use a customizable color palette instead of the default one to draw
+the graphs. See environment variable
+.B S_COLORS_PALETTE
+below to know how to customize that palette.
+.IP debug
+Add helpful comments in SVG output file.
+.TP
+.RI "height=" "value"
+Set SVG canvas height to
+.IR "value" "."
+.IP oneday
+Display graphs data over a period of 24 hours. Note that hours are still
+printed in UTC by default: You should use option
+.BR "\-T " "to print them in local time"
+and get a time window starting from midnight.
+.IP packed
+Group all views from the same activity (and for the same device) on the same row.
+.IP showidle
+Also display %idle state in graphs for CPU statistics.
+.IP showinfo
+Display additional information (such as the date and the host name) on each view.
+.IP showtoc
+Add a table of contents at the beginning of the SVG output, consisting of links
+pointing at the first graph of each activity.
+.IP skipempty
+Do not display views where all graphs have only zero values.
+.RE
+.IP
+The following option may be used when converting an old system activity binary datafile
+to current up-to-date format:
+.RS
+.TP
+.RI "hz=" "value"
+Specify the number of ticks per second for the machine where the old datafile has been created.
+.RE
+.IP
+The following option may be used when data are exported to a PCP archive:
+.RS
+.TP
+.RI "pcparchive=" "name"
+Specify the name of the PCP archive to create.
+.RE
+.IP
+The following option is used to control raw output displayed by
+.BR "sadf \-r" ":"
+.RS
+.IP debug
+Display additional information, mainly useful for debugging purpose.
+.RE
+.TP
+.BI "\-P { " "cpu_list " "| ALL }"
+.RB "Tell " "sadf"
+that processor dependent statistics are to be reported only for the
+specified processor or processors.
+.I cpu_list
+is a list of comma-separated values or range of values (e.g.,
+.BR "0,2,4\-7,12\-" ")."
+Note that processor 0 is the first processor, and processor
+.BR "all " "is the global average among all processors. Specifying the " "ALL"
+keyword reports statistics for each individual processor, and globally for
+all processors.
+.TP
+.B \-p
+Print the contents of the data file in a format that can
+easily be handled by pattern processing commands like
+.BR "awk" "."
+The output consists of fields separated by a tab. Each record contains the
+hostname of the host where the file was created, the interval value
+(or \-1 if not applicable), the timestamp, the device name (or \- if not applicable),
+the field name and its value.
+Note that timestamp output can be controlled by options
+.BR "\-T" ", " "\-t " "and " "\-U" "."
+.TP
+.B \-r
+Print the raw contents of the data file. With this format, the values for
+all the counters are displayed as read from the kernel, which means e.g., that
+no average values are calculated over the elapsed time interval.
+Output can be controlled using option
+.BR "\-O " "(see above)."
+.PP
+.BI "\-s [ " "hh" ":" "mm" "[:" "ss" "] ]"
+.br
+.BI "\-s [ " "seconds_since_the_epoch " "]"
+.RS
+Set the starting time of the data, causing the
+.B sadf
+command to extract records time-tagged at, or following, the time
+specified. The default starting time is 08:00:00.
+Hours must be given in 24-hour format, or as the number of seconds
+since the epoch (given as a 10 digit number).
+.RE
+.TP
+.B \-T
+Display timestamp in local time instead of UTC (Coordinated Universal Time).
+.TP
+.B \-t
+Display timestamp in the original local time of the data file creator
+instead of UTC (Coordinated Universal Time).
+.TP
+.B \-U
+Display timestamp (UTC - Coordinated Universal Time) in seconds from the epoch.
+.TP
+.B \-V
+Print version number then exit.
+.TP
+.B \-x
+Print the contents of the data file in XML format.
+Timestamps can be controlled by options
+.BR "\-T " "and " "\-t" "."
+The corresponding DTD (Document Type Definition) and XML Schema are included
+in the sysstat source package. They are also available at
+.IR "https://sysstat.github.io/" "."
+
+.SH ENVIRONMENT
+.RB "The " "sadf"
+command takes into account the following environment variables:
+.TP
+.B S_COLORS_PALETTE
+Specify the colors used by
+.B sadf \-g
+to render the SVG output. This environment variable is taken into account
+only when the custom color palette has been selected with the option
+.BR "customcol " "(see option " "\-O" ")."
+Its value is a colon-separated list of capabilities associated
+with six-digit, three-byte
+hexadecimal numbers (hex triplets) representing colors that defaults to
+
+.B 0=000000:1=1a1aff:2=1affb2:3=b21aff:
+.br
+.B 4=1ab2ff:5=ff1a1a:6=ffb31a:7=b2ff1a:
+.br
+.B 8=efefef:9=000000:A=1a1aff:B=1affb2:
+.br
+.B C=b21aff:D=1ab2ff:E=ff1a1a:F=ffb31a:
+.br
+.B G=bebebe:H=000000:I=000000:K=ffffff:
+.br
+.B L=000000:T=000000:W=000000:X=000000
+
+Capabilities consisting of a hexadecimal digit
+.RB "(" "0 " "through " "F" ") are used to specify"
+the first sixteen colors in the palette (these colors are used to draw the graphs),
+e.g., 3=ffffff would indicate that the third color in the palette is white (0xffffff).
+.br
+Other capabilities are:
+.RS
+.TP
+.B G=
+Specify the color used to draw the grid lines.
+.TP
+.B H=
+Specify the color used to display the report header.
+.TP
+.B I=
+Specify the color used to display additional information (e.g., date, hostname...)
+.TP
+.B K=
+Specify the color used for the graphs background.
+.TP
+.B L=
+Specify the default color (which is for example used to display the table of contents).
+.TP
+.B T=
+Specify the color used to display the graphs title.
+.TP
+.B W=
+Specify the color used to display warning and error messages.
+.TP
+.B X=
+Specify the color used to draw the axes and display the graduations.
+.RE
+.TP
+.B S_TIME_DEF_TIME
+If this variable exists and its value is
+.BR "UTC " "then " "sadf"
+will use UTC time instead of local time to determine the current daily data
+file located in the
+.IR /var/log/sysstat
+directory.
+
+.SH EXAMPLES
+.TP
+.B sadf \-d /var/log/sysstat/sa21 \-\- \-r \-n DEV
+Extract memory and network statistics from system activity file
+.IR "sa21" ","
+and display them in a format that can be ingested by a database.
+.TP
+.B sadf \-p \-P 1
+Extract CPU statistics for processor 1 (the second processor) from current
+daily data file, and display them in a format that can easily be handled
+by a pattern processing command.
+
+.SH BUGS
+SVG output (as created by option
+.BR "\-g" ")"
+is fully compliant with SVG 1.1 standard.
+Graphics have been successfully displayed in various web browsers, including
+Firefox, Chrome and Opera. Yet SVG rendering is broken on Microsoft browsers
+(tested on Internet Explorer 11 and Edge 13.1): So please don't use them.
+
+.SH FILES
+.I /var/log/sysstat/saDD
+.br
+.I /var/log/sysstat/saYYYYMMDD
+.RS
+The standard system activity daily data files and their default location.
+.IR "YYYY " "stands for the current year, " "MM " "for the current month and " "DD"
+for the current day.
+.RE
+
+.SH AUTHOR
+Sebastien Godard (sysstat <at> orange.fr)
+
+.SH SEE ALSO
+.BR "sar" "(1), " "sadc" "(8), " "sa1" "(8), " "sa2" "(8), " "sysstat" "(5)"
+.PP
+.I https://github.com/sysstat/sysstat
+.br
+.I https://sysstat.github.io/