tyler.durden
/
bottom
mirror of https://github.com/ClementTsang/bottom.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: update time-related documentation (#1222) 

* docs: update time-related documentation

* fix retention too
This commit is contained in:
Clement Tsang 2023-06-24 05:36:36 +00:00 committed by GitHub
parent cc3833289f
commit 4ac3b43260
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 73 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

84
docs/content/configuration/command-line-flags.md
View File

@ -3,45 +3,45 @@
The following flags can be provided to bottom in the command line to change the behaviour of the program. You can also The following flags can be provided to bottom in the command line to change the behaviour of the program. You can also
see information on these flags by running `btm -h`, or run `btm --help` to display more detailed information on each flag: see information on these flags by running `btm -h`, or run `btm --help` to display more detailed information on each flag:
| Flag | Behaviour | | Flag | Behaviour |
| ----------------------------------- | --------------------------------------------------------------- | | ----------------------------------- | --------------------------------------------------------------------- |
| --autohide_time | Temporarily shows the time scale in graphs. | | --autohide_time | Temporarily shows the time scale in graphs. |
| -b, --basic | Hides graphs and uses a more basic look. | | -b, --basic | Hides graphs and uses a more basic look. |
| --battery | Shows the battery widget. | | --battery | Shows the battery widget. |
| -S, --case_sensitive | Enables case sensitivity by default. | | -S, --case_sensitive | Enables case sensitivity by default. |
| -c, --celsius | Sets the temperature type to Celsius. | | -c, --celsius | Sets the temperature type to Celsius. |
| --color <COLOR SCHEME> | Use a color scheme, use --help for info. | | --color <COLOR SCHEME> | Use a color scheme, use --help for info. |
| -C, --config <CONFIG PATH> | Sets the location of the config file. | | -C, --config <CONFIG PATH> | Sets the location of the config file. |
| -u, --current_usage | Sets process CPU% to be based on current CPU%. | | -u, --current_usage | Sets process CPU% to be based on current CPU%. |
| -t, --default_time_value <TIME> | Default time value for graphs. | | -t, --default_time_value <TIME> | Default time value for graphs. |
| --default_widget_count <INT> | Sets the n'th selected widget type as the default. | | --default_widget_count <INT> | Sets the n'th selected widget type as the default. |
| --default_widget_type <WIDGET TYPE> | Sets the default widget type, use --help for info. | | --default_widget_type <WIDGET TYPE> | Sets the default widget type, use --help for info. |
| --disable_advanced_kill | Hides advanced process killing. | | --disable_advanced_kill | Hides advanced process killing. |
| --disable_click | Disables mouse clicks. | | --disable_click | Disables mouse clicks. |
| -m, --dot_marker | Uses a dot marker for graphs. | | -m, --dot_marker | Uses a dot marker for graphs. |
| --enable_cache_memory | Enable collecting and displaying cache and buffer memory. | | --enable_cache_memory | Enable collecting and displaying cache and buffer memory. |
| --enable_gpu_memory | Enable collecting and displaying GPU memory usage. | | --enable_gpu_memory | Enable collecting and displaying GPU memory usage. |
| -e, --expanded | Expand the default widget upon starting the app. | | -e, --expanded | Expand the default widget upon starting the app. |
| -f, --fahrenheit | Sets the temperature type to Fahrenheit. | | -f, --fahrenheit | Sets the temperature type to Fahrenheit. |
| -g, --group | Groups processes with the same name by default. | | -g, --group | Groups processes with the same name by default. |
| -a, --hide_avg_cpu | Hides the average CPU usage. | | -a, --hide_avg_cpu | Hides the average CPU usage. |
| --hide_table_gap | Hides spacing between table headers and entries. | | --hide_table_gap | Hides spacing between table headers and entries. |
| --hide_time | Hides the time scale. | | --hide_time | Hides the time scale. |
| -k, --kelvin | Sets the temperature type to Kelvin. | | -k, --kelvin | Sets the temperature type to Kelvin. |
| -l, --left_legend | Puts the CPU chart legend to the left side. | | -l, --left_legend | Puts the CPU chart legend to the left side. |
| --mem_as_value | Defaults to showing process memory usage by value. | | --mem_as_value | Defaults to showing process memory usage by value. |
| --network_use_binary_prefix | Displays the network widget with binary prefixes. | | --network_use_binary_prefix | Displays the network widget with binary prefixes. |
| --network_use_bytes | Displays the network widget using bytes. | | --network_use_bytes | Displays the network widget using bytes. |
| --network_use_log | Displays the network widget with a log scale. | | --network_use_log | Displays the network widget with a log scale. |
| --process_command | Show processes as their commands by default. | | --process_command | Show processes as their commands by default. |
| -r, --rate <MS> | Sets a refresh rate in ms. | | -r, --rate <TIME> | Sets the data refresh rate. |
| -R, --regex | Enables regex by default. | | -R, --regex | Enables regex by default. |
| --retention <TIME> | The timespan of data kept. | | --retention <TIME> | The timespan of data stored. |
| --show_table_scroll_position | Shows the scroll position tracker in table widgets. | | --show_table_scroll_position | Shows the scroll position tracker in table widgets. |
| -d, --time_delta <TIME> | The amount of time changed upon zooming. | | -d, --time_delta <TIME> | The amount of time changed upon zooming. |
| -T, --tree | Defaults the process widget be in tree mode. | | -T, --tree | Defaults the process widget be in tree mode. |
| -n, --unnormalized_cpu | Show process CPU% without normalizing over the number of cores. | | -n, --unnormalized_cpu | Show process CPU% usage without normalizing over the number of cores. |
| --use_old_network_legend | DEPRECATED - uses a separate network legend. | | --use_old_network_legend | DEPRECATED - uses a separate network legend. |
| -V, --version | Prints version information. | | -V, --version | Prints version information. |
| -W, --whole_word | Enables whole-word matching by default. | | -W, --whole_word | Enables whole-word matching by default. |
| -h, --help | Print help (see more with '--help') | | -h, --help | Print help (see more with '--help') |

2
docs/content/configuration/config-file/flags.md
View File

@ -20,7 +20,7 @@ each time:
| `basic` | Boolean | Hides graphs and uses a more basic look. | | `basic` | Boolean | Hides graphs and uses a more basic look. |
| `use_old_network_legend` | Boolean | DEPRECATED - uses the older network legend. | | `use_old_network_legend` | Boolean | DEPRECATED - uses the older network legend. |
| `battery` | Boolean | Shows the battery widget. | | `battery` | Boolean | Shows the battery widget. |
| `rate` | Unsigned Int (represents milliseconds) | Sets a refresh rate in ms. | | `rate` | Unsigned Int (represents milliseconds) or String (represents human time) | Sets a refresh rate in ms. |
| `default_time_value` | Unsigned Int (represents milliseconds) or String (represents human time) | Default time value for graphs in ms. | | `default_time_value` | Unsigned Int (represents milliseconds) or String (represents human time) | Default time value for graphs in ms. |
| `time_delta` | Unsigned Int (represents milliseconds) or String (represents human time) | The amount in ms changed upon zooming. | | `time_delta` | Unsigned Int (represents milliseconds) or String (represents human time) | The amount in ms changed upon zooming. |
| `hide_time` | Boolean | Hides the time scale. | | `hide_time` | Boolean | Hides the time scale. |

2
sample_configs/default_config.toml
View File

@ -12,7 +12,7 @@
# Whether to use dot markers rather than braille. # Whether to use dot markers rather than braille.
#dot_marker = false #dot_marker = false
# The update rate of the application. # The update rate of the application.
#rate = 1000 #rate = "1s"
# Whether to put the CPU legend to the left. # Whether to put the CPU legend to the left.
#left_legend = false #left_legend = false
# Whether to set CPU% on a process to be based on the total CPU or just current usage. # Whether to set CPU% on a process to be based on the total CPU or just current usage.

16
src/args.rs
View File

@ -149,9 +149,9 @@ pub fn build_app() -> Command {
.short('n') .short('n')
.long("unnormalized_cpu") .long("unnormalized_cpu")
.action(ArgAction::SetTrue) .action(ArgAction::SetTrue)
.help("Show process CPU% without normalizing over the number of cores.") .help("Show process CPU% usage without normalizing over the number of cores.")
.long_help( .long_help(
"Shows process CPU usage without averaging over the number of CPU cores in the system.", "Shows all process CPU% usage without averaging over the number of CPU cores in the system.",
); );
let disable_click = Arg::new("disable_click") let disable_click = Arg::new("disable_click")
@ -304,7 +304,7 @@ Defaults to \"default\".
.value_name("TIME") .value_name("TIME")
.help("Default time value for graphs.") .help("Default time value for graphs.")
.long_help( .long_help(
"Default time value for graphs. The minimum time is 30s, and the default is 60s.", "Default time value for graphs. Takes a number in milliseconds or a human duration (e.g. 60s). The minimum time is 30s, and the default is 60s.",
); );
// TODO: Charts are broken in the manpage // TODO: Charts are broken in the manpage
@ -352,9 +352,9 @@ use CPU (3) as the default instead.
.short('r') .short('r')
.long("rate") .long("rate")
.action(ArgAction::Set) .action(ArgAction::Set)
.value_name("MS") .value_name("TIME")
.help("Sets the data refresh rate.") .help("Sets the data refresh rate.")
.long_help("Sets the data refresh rate. The minimum is 250ms, and defaults to 1000ms. Smaller values may take more computer resources."); .long_help("Sets the data refresh rate. Takes a number in milliseconds or a human duration (e.g. 5s). The minimum is 250ms, and defaults to 1000ms. Smaller values may take more computer resources.");
let time_delta = Arg::new("time_delta") let time_delta = Arg::new("time_delta")
.short('d') .short('d')
@ -362,7 +362,7 @@ use CPU (3) as the default instead.
.action(ArgAction::Set) .action(ArgAction::Set)
.value_name("TIME") .value_name("TIME")
.help("The amount of time changed upon zooming.") .help("The amount of time changed upon zooming.")
.long_help("The amount of time changed when zooming in/out. The minimum is 1s, and defaults to 15s."); .long_help("The amount of time changed when zooming in/out. Takes a number in milliseconds or a human duration (e.g. 30s). The minimum is 1s, and defaults to 15s.");
let tree = Arg::new("tree") let tree = Arg::new("tree")
.short('T') .short('T')
@ -395,8 +395,8 @@ use CPU (3) as the default instead.
.long("retention") .long("retention")
.action(ArgAction::Set) .action(ArgAction::Set)
.value_name("TIME") .value_name("TIME")
.help("The timespan of data kept.") .help("The timespan of data stored.")
.long_help("How much data is stored at once in terms of time. Takes in human-readable time spans (e.g. 10m, 1h), with a minimum of 1 minute. Note higher values will take up more memory. Defaults to 10 minutes."); .long_help("How much data is stored at once in terms of time. Takes a number in milliseconds or a human duration (e.g. 20m), with a minimum of 1 minute. Note higher values will take up more memory. Defaults to 10 minutes.");
let version = Arg::new("version") let version = Arg::new("version")
.short('V') .short('V')

32
src/options.rs
View File

@ -102,9 +102,7 @@ pub struct ConfigFlags {
network_use_binary_prefix: Option<bool>, network_use_binary_prefix: Option<bool>,
enable_gpu_memory: Option<bool>, enable_gpu_memory: Option<bool>,
enable_cache_memory: Option<bool>, enable_cache_memory: Option<bool>,
#[serde(with = "humantime_serde")] retention: Option<StringOrNum>,
#[serde(default)]
retention: Option<Duration>,
} }
#[derive(Clone, Debug, Default, Deserialize, Serialize)] #[derive(Clone, Debug, Default, Deserialize, Serialize)]
@ -200,7 +198,7 @@ pub fn build_app(
let config = &config; let config = &config;
let retention_ms = let retention_ms =
get_retention_ms(matches, config).context("Update `retention` in your config file.")?; get_retention(matches, config).context("Update `retention` in your config file.")?;
let autohide_time = is_flag_enabled!(autohide_time, matches, config); let autohide_time = is_flag_enabled!(autohide_time, matches, config);
let default_time_value = get_default_time_value(matches, config, retention_ms) let default_time_value = get_default_time_value(matches, config, retention_ms)
.context("Update 'default_time_value' in your config file.")?; .context("Update 'default_time_value' in your config file.")?;
@ -887,16 +885,17 @@ fn get_network_scale_type(matches: &ArgMatches, config: &Config) -> AxisScaling
AxisScaling::Linear AxisScaling::Linear
} }
fn get_retention_ms(matches: &ArgMatches, config: &Config) -> error::Result<u64> { fn get_retention(matches: &ArgMatches, config: &Config) -> error::Result<u64> {
const DEFAULT_RETENTION_MS: u64 = 600 * 1000; // Keep 10 minutes of data. const DEFAULT_RETENTION_MS: u64 = 600 * 1000; // Keep 10 minutes of data.
if let Some(retention) = matches.get_one::<String>("retention") { if let Some(retention) = matches.get_one::<String>("retention") {
humantime::parse_duration(retention) try_parse_ms(retention)
.map(|dur| dur.as_millis() as u64)
.map_err(|err| BottomError::ConfigError(format!("invalid retention duration: {err:?}")))
} else if let Some(flags) = &config.flags { } else if let Some(flags) = &config.flags {
if let Some(retention) = flags.retention { if let Some(retention) = &flags.retention {
Ok(retention.as_millis() as u64) Ok(match retention {
StringOrNum::String(s) => try_parse_ms(s)?,
StringOrNum::Num(n) => *n,
})
} else { } else {
Ok(DEFAULT_RETENTION_MS) Ok(DEFAULT_RETENTION_MS)
} }
@ -913,7 +912,9 @@ mod test {
use crate::{ use crate::{
app::App, app::App,
canvas::canvas_styling::CanvasStyling, canvas::canvas_styling::CanvasStyling,
options::{get_default_time_value, get_update_rate, try_parse_ms, ConfigFlags}, options::{
get_default_time_value, get_retention, get_update_rate, try_parse_ms, ConfigFlags,
},
}; };
#[test] #[test]
@ -999,6 +1000,7 @@ mod test {
time_delta: Some("2 min".to_string().into()), time_delta: Some("2 min".to_string().into()),
default_time_value: Some("300s".to_string().into()), default_time_value: Some("300s".to_string().into()),
rate: Some("1s".to_string().into()), rate: Some("1s".to_string().into()),
retention: Some("10m".to_string().into()),
..Default::default() ..Default::default()
}; };
@ -1015,6 +1017,8 @@ mod test {
); );
assert_eq!(get_update_rate(&matches, &config), Ok(1000)); assert_eq!(get_update_rate(&matches, &config), Ok(1000));
assert_eq!(get_retention(&matches, &config), Ok(600000));
} }
#[test] #[test]
@ -1027,6 +1031,7 @@ mod test {
time_delta: Some("120000".to_string().into()), time_delta: Some("120000".to_string().into()),
default_time_value: Some("300000".to_string().into()), default_time_value: Some("300000".to_string().into()),
rate: Some("1000".to_string().into()), rate: Some("1000".to_string().into()),
retention: Some("600000".to_string().into()),
..Default::default() ..Default::default()
}; };
@ -1043,6 +1048,8 @@ mod test {
); );
assert_eq!(get_update_rate(&matches, &config), Ok(1000)); assert_eq!(get_update_rate(&matches, &config), Ok(1000));
assert_eq!(get_retention(&matches, &config), Ok(600000));
} }
#[test] #[test]
@ -1055,6 +1062,7 @@ mod test {
time_delta: Some(120000.into()), time_delta: Some(120000.into()),
default_time_value: Some(300000.into()), default_time_value: Some(300000.into()),
rate: Some(1000.into()), rate: Some(1000.into()),
retention: Some(600000.into()),
..Default::default() ..Default::default()
}; };
@ -1071,6 +1079,8 @@ mod test {
); );
assert_eq!(get_update_rate(&matches, &config), Ok(1000)); assert_eq!(get_update_rate(&matches, &config), Ok(1000));
assert_eq!(get_retention(&matches, &config), Ok(600000));
} }
fn create_app(config: Config, matches: ArgMatches) -> App { fn create_app(config: Config, matches: ArgMatches) -> App {