README.md

   1 ## pstop
   2
   3 pstop - a top-like program for MySQL
   4
   5 pstop is a program which collects information from MySQL 5.6+'s
   6 performance_schema database and uses this information to display
   7 server load in real-time. Data is shown by table or filename and
   8 the metrics also show how this is split between select, insert,
   9 update or delete activity.  User activity is now shown showing the
  10 number of different hosts that connect with the same username and
  11 the actiity of those users.
  12
  13 ### Installation
  14
  15 Install and update this go package with `go get -u github.com/sjmudd/pstop`
  16
  17 ### Dependencies
  18
  19 The following Non-core Go dependencies are:
  20 * github.com/sjmudd/mysql_defaults_file for connecting to MySQL via
  21 a defaults file.
  22 * github.com/nsf/termbox-go a library for creating cross-platform
  23 text-based interfaces.
  24
  25 ### Configuration
  26
  27 Access to MySQL can be made by one of the following methods:
  28 * Default: use a defaults-file named `~/.my.cnf`.
  29 * use an explicit defaults-file with `--defaults-file=/path/to/.my.cnf`.
  30 * connect to a host with `--host=somehost --port=999 --user=someuser --password=somepass`, or
  31 * connect via a socket with `--socket=/path/to/mysql.sock --user=someuser --password=somepass`
  32
  33 The user if not specified will default to the contents of `$USER`.
  34 The port if not specified will default to 3306.
  35
  36 ### Grants
  37
  38 `pstop` needs `SELECT` access to `performance_schema` tables. It
  39 will not run if access to the required tables is not available.
  40
  41 ### Screens
  42
  43 pstop has 5 different screens which get updated by default every second.
  44 * Latency mode: order table activity by the time waiting to perform operations on them.
  45 * Ops (operations) mode: order table activity by the number of operations MySQL performs on them.
  46 * I/O mode: show where MySQL is spending it's time in file I/O.
  47 * Locks mode: show order based on table locks
  48 * User mode: show ordering based on how long users are running
  49 queries, or the number of connections they have to MySQL. This is
  50 really missing a feature in MySQL (see: http://bugs.mysql.com/75156)
  51 to provide higher resolution query times than seconds. It gives
  52 some info but if the queries are very short then the integer runtime
  53 in seconds makes the output far less interesting. Total idle time is also
  54 shown as this gives an indication of perhaps overly long idle queries,
  55 and the sum of the values here if there's a pile up may be interesting.
  56
  57 You can change the polling interval and switch between modes (see below).
  58
  59 ### Keys
  60
  61 The following keys allow you to navigate around the different pstop displays or to change it's behaviour.
  62
  63 * h - gives you a help screen.
  64 * - - reduce the poll interval by 1 second (minimum 1 second)
  65 * + - increase the poll interval by 1 second
  66 * q - quit
  67 * t - toggle between showing the statistics since resetting pstop started or you explicitly reset them (with 'z') [REL] or showing the statistics as collected from MySQL [ABS].
  68 * z - reset statistics. That is counters you see are relative to when you "reset" statistics.
  69 * <tab> - change display modes between: latency, ops, file I/O, lock modes and user modes.
  70 * left arrow - change to previous screen
  71 * right arrow - change to next screen
  72
  73 ### See also
  74
  75 See also:
  76 * [BUGS](https://github.com/sjmudd/pstop/blob/master/BUGS) currently known issues
  77 * [NEW_FEATURES](https://github.com/sjmudd/pstop/blob/master/NEW_FEATURES) which describe things that probably need looking at
  78 * [screen_samples.txt](https://github.com/sjmudd/pstop/blob/master/screen_samples.txt) provides some sample output from my own system.
  79
  80 ### Contributing
  81
  82 This program was started as a simple project to allow me (Simon) to learn
  83 go, which I'd been following for a while, but hadn't used in earnest.
  84 This probably shows in the code so suggestions on improvement are
  85 most welcome.
  86
  87 You may find "Contributing to Open Source Git Repositories in Go"
  88 by Katrina Owen to be useful:
  89 https://blog.splice.com/contributing-open-source-git-repositories-go/
  90
  91 ### Licensing
  92
  93 BSD 2-Clause License
  94
  95 ### Feedback
  96
  97 Feedback and patches welcome. I am especially interested in hearing
  98 from you if you are using pstop, or if you have ideas of how I can
  99 better use other information from the performance_schema tables to
 100 provide a more complete vision of what MySQL is doing or where it's
 101 busy.
 102
 103 Simon J Mudd
 104 <sjmudd@pobox.com>
 105
 106 ### Code Documenton
 107 [godoc.org/github.com/sjmudd/pstop](http://godoc.org/github.com/sjmudd/pstop)