X-Git-Url: http://git.iain.cx/?a=blobdiff_plain;f=README.md;h=aa431a86117dbd562b9807a22c45f805b1fc0434;hb=19895ca8d31deea9680395e11e889d4b32a58bd4;hp=9985f22f72a08e3002eab8112760e4d3649b06b9;hpb=6e1a36f58c73ec770b55701bd8ae26d06ef4f8a5;p=pstop.git diff --git a/README.md b/README.md index 9985f22..aa431a8 100644 --- a/README.md +++ b/README.md @@ -10,34 +10,51 @@ update or delete activity. User activity is now shown showing the number of different hosts that connect with the same username and the actiity of those users. -This program was started as a simple project to allow me to learn -go, which I'd been following for a while, but hadn't used in earnest. -This probably shows in the code so suggestions on improvement are -most welcome. - ### Installation Install and update this go package with `go get -u github.com/sjmudd/pstop` +### Dependencies + +The following Non-core Go dependencies are: +* github.com/sjmudd/mysql_defaults_file for connecting to MySQL via +a defaults file. +* github.com/nsf/termbox-go a library for creating cross-platform +text-based interfaces. + ### Configuration -Access to MySQL is currently via a defaults-file which is assumed -to be ~/.my.cnf. This should probably be made more configurable. -If you see a need for this please let me know. +Access to MySQL can be made by one of the following methods: +* Default: use a defaults-file named `~/.my.cnf`. +* use an explicit defaults-file with `--defaults-file=/path/to/.my.cnf`. +* connect to a host with `--host=somehost --port=999 --user=someuser --password=somepass`, or +* connect via a socket with `--socket=/path/to/mysql.sock --user=someuser --password=somepass` + +The user if not specified will default to the contents of `$USER`. +The port if not specified will default to 3306. ### Grants -Do not forget to ensure that the MySQL user you configure has access -to the performance_schema tables. +`pstop` needs `SELECT` access to `performance_schema` tables. It +will not run if access to the required tables is not available. ### Screens -pstop has 5 different screens: +pstop has 5 different screens which get updated by default every second. * Latency mode: order table activity by the time waiting to perform operations on them. * Ops (operations) mode: order table activity by the number of operations MySQL performs on them. * I/O mode: show where MySQL is spending it's time in file I/O. * Locks mode: show order based on table locks -* User mode: show ordering based on how long users are running queries, or the number of connections they have to MySQL. +* User mode: show ordering based on how long users are running +queries, or the number of connections they have to MySQL. This is +really missing a feature in MySQL (see: http://bugs.mysql.com/75156) +to provide higher resolution query times than seconds. It gives +some info but if the queries are very short then the integer runtime +in seconds makes the output far less interesting. Total idle time is also +shown as this gives an indication of perhaps overly long idle queries, +and the sum of the values here if there's a pile up may be interesting. + +You can change the polling interval and switch between modes (see below). ### Keys @@ -55,13 +72,33 @@ The following keys allow you to navigate around the different pstop displays or ### See also -See also BUGS and NEW_FEATURES which describe things that probably -need looking at and screen_samples.txt which provides some sample -output from my own system. +See also: +* [BUGS](https://github.com/sjmudd/pstop/blob/master/BUGS) currently known issues +* [NEW_FEATURES](https://github.com/sjmudd/pstop/blob/master/NEW_FEATURES) which describe things that probably need looking at +* [screen_samples.txt](https://github.com/sjmudd/pstop/blob/master/screen_samples.txt) provides some sample output from my own system. + +### Contributing + +This program was started as a simple project to allow me (Simon) to learn +go, which I'd been following for a while, but hadn't used in earnest. +This probably shows in the code so suggestions on improvement are +most welcome. + +You may find "Contributing to Open Source Git Repositories in Go" +by Katrina Owen to be useful: +https://blog.splice.com/contributing-open-source-git-repositories-go/ + +### Licensing + +BSD 2-Clause License ### Feedback -Feedback and patches welcome. +Feedback and patches welcome. I am especially interested in hearing +from you if you are using pstop, or if you have ideas of how I can +better use other information from the performance_schema tables to +provide a more complete vision of what MySQL is doing or where it's +busy. Simon J Mudd