From 6809c82eb3b08d4d22e10f094630837c42d512e8 Mon Sep 17 00:00:00 2001 From: "Sean E. Russell" Date: Tue, 20 Jul 2021 13:37:03 -0500 Subject: [PATCH] Documentation prep for release; remote monitoring docs cleanup. --- CHANGELOG.md | 15 +++++++-- README.md | 26 ++++++++++------ docs/remote-extension.md | 64 --------------------------------------- docs/remote-monitoring.md | 14 ++++----- 4 files changed, 34 insertions(+), 85 deletions(-) delete mode 100644 docs/remote-extension.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 56f8bf6..7883ae9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,25 +13,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 > - **Fixed**: for any bug fixes. > - **Security**: in case of vulnerabilities. -## [4.1.2] +## [4.1.2] 2021-07-20 ### Added +- Several folks contributed to building on new Apple silicon (@clandmeter, + @areese, and @nickcorin). This took a distressingly long time for me to merge; + it required updating and testing a newer cross-compiling CGO, and I'm timid + when it comes to releasing stuff I can't test. - French and Russion translations (thank you @lourkeur and @talentlessguy!) - nvidia support merged in from extension - remote support merged in from extension +- Spanish translation (thanks to @donPatino & @lourkeur) +- There's a link to the github project in the help text now ### Changed - Upgrade to Go 1.16. This eliminates go:generate for the language files, which - means gotop no longer builds with Go < 1.16. + means gotop no longer builds with Go < 1.16. It does make things easier for + translators and merging. +- The [remote monitoring documentation](https://github.com/xxxserxxx/gotop/blob/master/docs/remote-monitoring.md) is a little better. ### Fixed -- German translation corrected (thanks @plgruener!) - Extra spaces in help text (#167) - Crash with German translation (#166) - Bad error message for missing layouts (#164) +- @JonathanReeve, @joinemm, and @plgruener contributed typo and mis-translation fixes +- The remote extension was ignoring config-file settings (no ticket #) ## [4.1.1] 2021-02-03 diff --git a/README.md b/README.md index 6abde81..c76f1a7 100644 --- a/README.md +++ b/README.md @@ -35,12 +35,9 @@ If you install gotop by hand, or you download or create new layouts or colorsche ``` - **OSX**: gotop is in *homebrew-core*. `brew install gotop`. Make sure to uninstall and untap any previous installations or taps. - **Prebuilt binaries**: Binaries for most systems can be downloaded from [the github releases page](https://github.com/xxxserxxx/gotop/releases). RPM and DEB packages are also provided. -- **Prebuild binaries with extensions**: - - [NVidia GPU support](https://github.com/xxxserxxx/gotop-nvidia/releases) - - [Remote gotop support](https://github.com/xxxserxxx/gotop-remote/releases) -- **Source**: This requires Go >= 1.16. `go get -u github.com/xxxserxxx/gotop/v4/cmd/gotop` +- **Source**: This requires Go >= 1.16. `go install github.com/xxxserxxx/gotop/v4/cmd/gotop` -### Extension builds +### Extensions update Extensions have proven problematic; go plugins are not usable in real-world cases, and the solution I had running for a while was hacky, at best. Consequently, extensions have been moved into the main code base for now. @@ -98,12 +95,21 @@ In addition to the key bindings, the mouse can be used to control the process li For more information on other topics, see: -- [Layouts](docs/layouts.md) -- [Configuration](docs/configuration.md) -- [Color schemes](docs/colorschemes.md) -- [Device filtering](docs/devices.md) -- [Extensions](docs/extensions.md) +- [Layouts](https://github.com/xxxserxxx/gotop/blob/master/docs/layouts.md) +- [Configuration](https://github.com/xxxserxxx/gotop/blob/master/docs/configuration.md) +- [Color schemes](https://github.com/xxxserxxx/gotop/blob/master/docs/colorschemes.md) +- [Device filtering](https://github.com/xxxserxxx/gotop/blob/master/docs/devices.md) +- [Extensions](https://github.com/xxxserxxx/gotop/blob/master/docs/extensions.md) +Monitoring remote machines +-------------------------- + +gotop can monitor gotops running on remote machines and display (some of the) +metrics within a single instance. gotop expects to be behind a proxy, or within +a secure intranet, so while it's not exactly hard to set up, it's also not +trivial. An example set-up is explained in the +[Remote Monitoring](https://github.com/xxxserxxx/gotop/blob/master/docs/remote-monitoring.md) +document. ## More screen shots diff --git a/docs/remote-extension.md b/docs/remote-extension.md deleted file mode 100644 index edafbf6..0000000 --- a/docs/remote-extension.md +++ /dev/null @@ -1,64 +0,0 @@ -# Remote monitoring extension for gotop - - -Show data from gotop running on remote servers in a locally-running gotop. This allows gotop to be used as a simple terminal dashboard for remote servers. - -![Screenshot](/screenshots/fourby.png) - - -## Configuration - -gotop exports metrics on a local port if it is run with the `--export ` argument. This is a simple, read-only interface with the expectation that it will be run behind some proxy that provides security. A gotop built with this extension can read this data and render it as if the devices being monitored were on the local machine. - -On the local side, gotop gets the remote information from a config file; it is not possible to pass this in on the command line. The recommended approach is to create a remote-specific config file, and then run gotop with the `-C ` option (or just add the options to the normal `gotop.config` file). Two options are available for each remote server; one of these, the connection URL, is required. - -The format of the configuration keys are: `remote-SERVERNAME-url` and `remote-SERVERNAME-refresh`; `SERVERNAME` can be anything -- it doesn't have to reflect any real attribute of the server, but it will be used in widget labels for data from that server. For example, CPU data from `remote-Jerry-url` will show up as `Jerry-CPU0`, `Jerry-CPU1`, and so on; memory data will be labeled `Jerry-Main` and `Jerry-Swap`. If the refresh rate option is omitted, it defaults to 1 second. - - -### An example - -One way to set this up is to run gotop behind [Caddy](https://caddyserver.com). The `Caddyfile` would have something like this in it: - -``` -gotop.myserver.net { - basicauth / gotopusername supersecretpassword - proxy / http://localhost:8089 -} -``` - -Then, gotop would be run in a persistent terminal session such as [tmux](https://github.com/tmux/tmux) with the following command: - -``` -gotop -x :8089 -``` - -A future release of gotop will include a `--headless` option to avoid the need to run gotop in a persistent `screen` or `tmux` terminal. - -Then, on a local laptop, create a config file named `myserver.conf` with the following lines: - -``` -remote-myserver-url=https://gotopusername:supersecretpassword@gotop.myserver.net/metrics -remote-myserver-refresh=2 -``` - -Note the `/metrics` at the end -- don't omit that, and don't strip it in Caddy. The refresh value is in seconds. Run gotop with: - -``` -gotop -C myserver.conf -``` - -and you should see your remote server sensors as if it were running on your local machine. - -You can add as many remote servers as you like in the config file; just follow the naming pattern. - -## Why - -This can combine multiple servers into one view, which makes it more practical to use a terminal-based monitor when you have more than a couple of servers, or when you don't want to dedicate an entire wide-screen monitor to a bunch of gotop instances. It's simple to set up, configure, and run, and reasonably resource efficient. - -## How - -Since v3.5.2, gotop's been able to export its sensor data as [Prometheus](https://prometheus.io/) metrics using the `--export` flag. Prometheus has the advantages of being simple to integrate into clients, and a nice on-demand design that depends on the *aggregator* pulling data from monitors, rather than the clients pushing data to a server. In essence, it inverts the client/server relationship for monitoring/aggregating servers and the things it's monitoring. In gotop's case, it means you can turn on `-x` and not have it impact your gotop instance at all, until you actively poll it. It puts the control on measurement frequency in a single place -- your local gotop. It means you can simply stop your local gotop instance (e.g., when you go to bed) and the demand on the servers you were monitoring drops to 0. - -On the client (local) side, sensors are abstracted as devices that are read by widgets, and we've simply implemented virtual devices that poll data from remote Prometheus instances. At a finer grain, there's a single process spawned for each remote server that periodically polls that server and collects the information. When the widget updates and asks the virtual device for data, the device consults the cached data and provides it as the measurement. - -The next iteration will optimize the metrics transfer protocol; while it'll likely remain HTTP, optimizations may include HTTP/2.0 streams to reduce the HTTP connection overhead, and a binary payload format for the metrics -- although HTTP/2.0 compression may eliminate any benefit of doing that. diff --git a/docs/remote-monitoring.md b/docs/remote-monitoring.md index 48fd0a8..6558d50 100644 --- a/docs/remote-monitoring.md +++ b/docs/remote-monitoring.md @@ -10,9 +10,9 @@ Show data from gotop running on remote servers in a locally-running gotop. This gotop exports metrics on a local port with the `--export ` argument. This is a simple, read-only interface with the expectation that it will be run behind some proxy that provides security. A gotop built with this extension can read this data and render it as if the devices being monitored were on the local machine. -On the local side, gotop gets the remote information from a config file; it is not possible to pass this in on the command line. The recommended approach is to create a remote-specific config file, and then run gotop with the `-C ` option. Two options are available for each remote server; one of these, the connection URL, is required. +On the local side, gotop gets the remote information from a config file; if all you have is a single remote machine to monitor, the parameters can be passed on the command line. For more than one remote, a config file is needed. The recommended approach is to create a remote-specific config file, and then run gotop with the `-C ` option. The plan is to add two functions that will enhance this feature: disabling the UI on the remote machine (allowing gotop to be forked into the background); and disabling local metrics to focus a gotop instance on remote machines. Also planned are a data transfer optimization and increasing the metrics that can be monitored. -The format of the configuration keys are: `remote-SERVERNAME-url` and `remote-SERVERNAME-refresh`; `SERVERNAME` can be anything -- it doesn't have to reflect any real attribute of the server, but it will be used in widget labels for data from that server. For example, CPU data from `remote-Jerry-url` will show up as `Jerry-CPU0`, `Jerry-CPU1`, and so on; memory data will be labeled `Jerry-Main` and `Jerry-Swap`. If the refresh rate option is omitted, it defaults to 1 second. +Two options are available for each remote server; one of these, the connection URL, is required. The format of the configuration keys are: `remote-SERVERNAME-url` and `remote-SERVERNAME-refresh`; `SERVERNAME` can be anything -- it doesn't have to reflect any real attribute of the server, but it will be used in widget labels for data from that server. For example, CPU data from `remote-Jerry-url` will show up as `Jerry-CPU0`, `Jerry-CPU1`, and so on; memory data will be labeled `Jerry-Main` and `Jerry-Swap`. If the refresh rate option is omitted, it defaults to 1 second. ### An example @@ -22,17 +22,17 @@ One way to set this up is to run gotop behind [Caddy](https://caddyserver.com). ``` gotop.myserver.net { basicauth / gotopusername supersecretpassword - proxy / http://localhost:8089 + reverse-proxy / http://localhost:8089 } -``` +``` -Then, gotop would be run in a persistent terminal session such as [tmux](https://github.com/tmux/tmux) with the following command: +Caddy would then be responsible for authentication and encrypting the traffic. Then, on the same machine run gotop in a persistent terminal session such as [tmux](https://github.com/tmux/tmux) with the following command: ``` gotop -x :8089 ``` -Then, on a local laptop, create a config file named `myserver.conf` with the following lines: +On a local machine, create a config file named `myserver.conf` with the following lines: ``` remote-myserver-url=https://gotopusername:supersecretpassword@gotop.myserver.net/metrics @@ -58,5 +58,3 @@ This can combine multiple servers into one view, which makes it more practical t Since v3.5.2, gotop's been able to export its sensor data as [Prometheus](https://prometheus.io/) metrics using the `--export` flag. Prometheus has the advantages of being simple to integrate into clients, and a nice on-demand design that depends on the *aggregator* pulling data from monitors, rather than the clients pushing data to a server. In essence, it inverts the client/server relationship for monitoring/aggregating servers and the things it's monitoring. In gotop's case, it means you can turn on `-x` and not have it impact your gotop instance at all, until you actively poll it. It puts the control on measurement frequency in a single place -- your local gotop. It means you can simply stop your local gotop instance (e.g., when you go to bed) and the demand on the servers you were monitoring drops to 0. On the client (local) side, sensors are abstracted as devices that are read by widgets, and we've simply implemented virtual devices that poll data from remote Prometheus instances. At a finer grain, there's a single process spawned for each remote server that periodically polls that server and collects the information. When the widget updates and asks the virtual device for data, the device consults the cached data and provides it as the measurement. - -The next iteration will optimize the metrics transfer protocol; while it'll likely remain HTTP, optimizations may include HTTP/2.0 streams to reduce the HTTP connection overhead, and a binary payload format for the metrics -- although HTTP/2.0 compression may eliminate any benefit of doing that.