Mirrors/bottom
2
0
Fork 0
mirror of https://github.com/ClementTsang/bottom synced 2024-11-10 14:44:18 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: update time-related documentation (#1222)

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

2
sample_configs/default_config.toml
View file

@ -12,7 +12,7 @@
# Whether to use dot markers rather than braille.
#dot_marker = false
# The update rate of the application.
#rate = 1000
#rate = "1s"
# Whether to put the CPU legend to the left.
#left_legend = false
# 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')
.long("unnormalized_cpu")
.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(
"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")
@ -304,7 +304,7 @@ Defaults to \"default\".
.value_name("TIME")
.help("Default time value for graphs.")
.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
@ -352,9 +352,9 @@ use CPU (3) as the default instead.
.short('r')
.long("rate")
.action(ArgAction::Set)
.value_name("MS")
.value_name("TIME")
.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")
.short('d')
@ -362,7 +362,7 @@ use CPU (3) as the default instead.
.action(ArgAction::Set)
.value_name("TIME")
.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")
.short('T')
@ -395,8 +395,8 @@ use CPU (3) as the default instead.
.long("retention")
.action(ArgAction::Set)
.value_name("TIME")
.help("The timespan of data kept.")
.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.");
.help("The timespan of data stored.")
.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")
.short('V')

32
src/options.rs
View file

@ -102,9 +102,7 @@ pub struct ConfigFlags {
network_use_binary_prefix: Option<bool>,
enable_gpu_memory: Option<bool>,
enable_cache_memory: Option<bool>,
#[serde(with = "humantime_serde")]
#[serde(default)]
retention: Option<Duration>,
retention: Option<StringOrNum>,
}
#[derive(Clone, Debug, Default, Deserialize, Serialize)]
@ -200,7 +198,7 @@ pub fn build_app(
let config = &config;
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 default_time_value = get_default_time_value(matches, config, retention_ms)
.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
}
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.
if let Some(retention) = matches.get_one::<String>("retention") {
humantime::parse_duration(retention)
.map(|dur| dur.as_millis() as u64)
.map_err(|err| BottomError::ConfigError(format!("invalid retention duration: {err:?}")))
try_parse_ms(retention)
} else if let Some(flags) = &config.flags {
if let Some(retention) = flags.retention {
Ok(retention.as_millis() as u64)
if let Some(retention) = &flags.retention {
Ok(match retention {
StringOrNum::String(s) => try_parse_ms(s)?,
StringOrNum::Num(n) => *n,
})
} else {
Ok(DEFAULT_RETENTION_MS)
}
@ -913,7 +912,9 @@ mod test {
use crate::{
app::App,
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]
@ -999,6 +1000,7 @@ mod test {
time_delta: Some("2 min".to_string().into()),
default_time_value: Some("300s".to_string().into()),
rate: Some("1s".to_string().into()),
retention: Some("10m".to_string().into()),
..Default::default()
};
@ -1015,6 +1017,8 @@ mod test {
);
assert_eq!(get_update_rate(&matches, &config), Ok(1000));
assert_eq!(get_retention(&matches, &config), Ok(600000));
}
#[test]
@ -1027,6 +1031,7 @@ mod test {
time_delta: Some("120000".to_string().into()),
default_time_value: Some("300000".to_string().into()),
rate: Some("1000".to_string().into()),
retention: Some("600000".to_string().into()),
..Default::default()
};
@ -1043,6 +1048,8 @@ mod test {
);
assert_eq!(get_update_rate(&matches, &config), Ok(1000));
assert_eq!(get_retention(&matches, &config), Ok(600000));
}
#[test]
@ -1055,6 +1062,7 @@ mod test {
time_delta: Some(120000.into()),
default_time_value: Some(300000.into()),
rate: Some(1000.into()),
retention: Some(600000.into()),
..Default::default()
};
@ -1071,6 +1079,8 @@ mod test {
);
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 {