diff --git a/below/below.1 b/below/below.1 new file mode 100644 index 00000000..b1e78178 --- /dev/null +++ b/below/below.1 @@ -0,0 +1,1721 @@ +.TH BELOW 1 "December 2024" "Version 1.0" "System Monitoring Tools" +.SH NAME +below \- interactive tool to view and record historical system data + +.SH SYNOPSIS +.B below +[\fIOPTIONS\fR] [\fISUBCOMMAND\fR] [\fISUBCOMMAND-OPTIONS\fR] + +.SH DESCRIPTION +.B below +is an interactive tool designed to view, record, and analyze historical system data. +It provides a set of subcommands to interact with live or recorded system performance metrics +and supports operations like recording, replaying, and exporting data. + +If no subcommand is specified, the tool defaults to the \fBlive\fR mode, which displays live +system data interactively. + +.SH GLOBAL OPTIONS +.TP +.B --config +Specify the configuration file. Default is /etc/below/below.conf. + +.TP +.B -d, --debug +Enable debug mode for additional logging and diagnostics. + +.TP +.B -h, --help +Print help for the tool. + +.SH SUBCOMMANDS +.TP +.B scuba +Dump data to scuba. + +.TP +.B live +Display live system data interactively. This is the default mode if no subcommand is specified. + +.TP +.B record +Record local system data in daemon mode for later analysis. + +.TP +.B replay +Replay historical data interactively. + +.TP +.B debug +Provide debugging facilities (for development purposes). + +.TP +.B dump +Dump historical data into a parseable text format. + +.TP +.B snapshot +Create a historical snapshot file for a given time range. + +.SH SUBCOMMAND DETAILS +.SS scuba +Dump data to scuba. This subcommand supports the following options: + +.TP +.B -b, --begin +Time string specifying the starting point. Examples: +.RS +.IP +Keywords: now, today, yesterday +.IP +\fI{humantime}\fR ago, e.g., "2 days 3 hr 15m 10sec ago" +.IP +short: Mixed \fI{time_digit}{time_unit_char}\fR, e.g., 10m, 3d2h, 5h30s. Case insensitive. +.IP +Absolute: "Jan 01 23:59", "01/01/1970 11:59PM", "1970-01-01 23:59:59" +.IP +Unix Epoch: 1589808367 +.RE + +.TP +.B -e, --end +Time string specifying the ending point. Follows the same format as \fB--begin\fR. + +.TP +.B --duration +Time string specifying the scuba duration. Examples: +.RS +.IP +Keywords: days, min, h, sec +.IP +Relative: \fI{humantime}\fR, e.g., "2 days 3 hr 15m 10sec" +.RE + +.TP +.B -s, --host +Supply hostname to log data from remote. + +.TP +.B --port +Override the default port to connect to remote. + +.TP +.B -r +Days adjuster. Use \fIy\fR for yesterday, repeated as needed (e.g., \fIyy\fR for 2 days ago). Examples: +.RS +.IP +Yesterday at 2 pm: \fBbelow replay -r y -t 2:00pm\fR +.IP +Adjusted date: \fBbelow replay -r yy -t "09/03/2020 17:00"\fR +.RE + +.TP +.B -c, --cgroup-filter +Only cgroups containing the specified string in their full path will be logged. Example: +.RS +.IP +\fBbelow scuba --begin "1m ago" --cgroup-filter /system.slice\fR +.RE + +.SS live +Display live system data interactively. This subcommand supports the following options: + +.TP +.B -i, --interval-s +Set the refresh interval in seconds. Default is 5 seconds. + +.TP +.B -s, --host +Supply hostname to activate remote viewing. + +.TP +.B --port +Override the default port to connect remote viewing to. + +.SS record +Record local system data in daemon mode for later analysis. This subcommand supports the following options: + +.TP +.B -i, --interval-s +Set the data collection interval in seconds. Default is 5 seconds. + +.TP +.B --retain-for-s +Specify retention period in seconds. Data is stored in 24-hour shards. Shards older than \fIRETAIN_FOR_S + 24 hours\fR are discarded. +.RS +.IP +Note: If \fB--store-size-limit\fR is set, data may be discarded earlier. +.RE + +.TP +.B --store-size-limit +Set the maximum storage size in bytes. Data is stored in 24-hour shards, and the oldest shards are deleted first. +.RS +.IP +Note: The size limit may be exceeded by the active shard. +.RE + +.TP +.B --collect-io-stat +Enable collection of \fBio.stat\fR for cgroups. This may be resource-intensive. + +.TP +.B --port +Override the default port for the remote viewing server. + +.TP +.B --skew-detection-threshold-ms +Set the threshold (in milliseconds) for detecting skew in data collection. Default is 500ms. + +.TP +.B --disable-disk-stat +Disable collection of disk statistics. + +.TP +.B --disable-exitstats +Disable eBPF-based exit statistics. + +.TP +.B --compress +Enable zstd compression for data files. Expect approximately 10x smaller files. + +.TP +.B --dict-compress-chunk-size +Specify chunk size for zstd dictionary compression. Must be a power of 2, between 2 and 32768. +.RS +.IP +Example: Setting \fB--dict-compress-chunk-size 16\fR can achieve 20-30x compression ratios. +.RE + +.SS replay +Replay historical data interactively. This subcommand supports the following options: + +.TP +.B -t, --time