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 activity of those users.  There are also statistics on mutex
  12 and sql stage timings.
  13
  14 ### Installation
  15
  16 Install and update this go package with `go get -u github.com/sjmudd/pstop`.
  17
  18 Note if you are looking for binaries for pstop then look here
  19 http://gobuild.io/github.com/sjmudd/pstop as a possible location.
  20 I have not tried this service but it looks ok.
  21
  22 ### Dependencies
  23
  24 The following Non-core Go dependencies are:
  25 * github.com/sjmudd/mysql_defaults_file for connecting to MySQL via
  26 a defaults file.
  27 * github.com/nsf/termbox-go a library for creating cross-platform
  28 text-based interfaces.
  29
  30 ### Configuration
  31
  32 Access to MySQL can be made by one of the following methods:
  33 * Default: use a defaults-file named `~/.my.cnf`.
  34 * use an explicit defaults-file with `--defaults-file=/path/to/.my.cnf`.
  35 * connect to a host with `--host=somehost --port=999 --user=someuser --password=somepass`, or
  36 * connect via a socket with `--socket=/path/to/mysql.sock --user=someuser --password=somepass`
  37
  38 The user if not specified will default to the contents of `$USER`.
  39 The port if not specified will default to 3306.
  40
  41 ### Grants
  42
  43 `pstop` needs `SELECT` access to `performance_schema` tables. It
  44 will not run if access to the required tables is not available.
  45
  46 setup_instruments: To view the Mutex or Stage page pstop will try to
  47 change the configuration if needed and if you have grants to do this.
  48 If the server is --read-only or you don't have sufficient grants
  49 and the changes can not be made these pages may be empty.
  50 Pior to stopping pstop will restore the setup_instruments
  51 configuration back to its original settings if it had successfully
  52 updated the table when starting up.
  53
  54 ### Screens
  55
  56 pstop has 5 different screens which get updated by default every second.
  57 * Latency mode: order table activity by the time waiting to perform operations on them.
  58 * Ops (operations) mode: order table activity by the number of operations MySQL performs on them.
  59 * I/O mode: show where MySQL is spending it's time in file I/O.
  60 * Locks mode: show order based on table locks
  61 * User mode: show ordering based on how long users are running
  62 queries, or the number of connections they have to MySQL. This is
  63 really missing a feature in MySQL (see: http://bugs.mysql.com/75156)
  64 to provide higher resolution query times than seconds. It gives
  65 some info but if the queries are very short then the integer runtime
  66 in seconds makes the output far less interesting. Total idle time is also
  67 shown as this gives an indication of perhaps overly long idle queries,
  68 and the sum of the values here if there's a pile up may be interesting.
  69 * Mutex mode: show the ordering by mutex latency [1].
  70 * Stages mode: show the ordering by time in the different SQL query stages [1].
  71
  72 You can change the polling interval and switch between modes (see below).
  73
  74 [1] pstop will try to configure the mutex and staging settings in
  75 setup_consumers if it can, and restore them when exiting if it
  76 changes something.
  77
  78 ### Keys
  79
  80 The following keys allow you to navigate around the different pstop displays or to change it's behaviour.
  81
  82 * h - gives you a help screen.
  83 * - - reduce the poll interval by 1 second (minimum 1 second)
  84 * + - increase the poll interval by 1 second
  85 * q - quit
  86 * 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].
  87 * z - reset statistics. That is counters you see are relative to when you "reset" statistics.
  88 * <tab> - change display modes between: latency, ops, file I/O, lock, user, mutex and stage modes.
  89 * left arrow - change to previous screen
  90 * right arrow - change to next screen
  91
  92 ### See also
  93
  94 See also:
  95 * [BUGS](https://github.com/sjmudd/pstop/blob/master/BUGS) currently known issues
  96 * [NEW_FEATURES](https://github.com/sjmudd/pstop/blob/master/NEW_FEATURES) which describe things that probably need looking at
  97 * [screen_samples.txt](https://github.com/sjmudd/pstop/blob/master/screen_samples.txt) provides some sample output from my own system.
  98
  99 ### Contributing
 100
 101 This program was started as a simple project to allow me (Simon) to learn
 102 go, which I'd been following for a while, but hadn't used in earnest.
 103 This probably shows in the code so suggestions on improvement are
 104 most welcome.
 105
 106 You may find "Contributing to Open Source Git Repositories in Go"
 107 by Katrina Owen to be useful:
 108 https://blog.splice.com/contributing-open-source-git-repositories-go/
 109
 110 ### Licensing
 111
 112 BSD 2-Clause License
 113
 114 ### Feedback
 115
 116 Feedback and patches welcome. I am especially interested in hearing
 117 from you if you are using pstop, or if you have ideas of how I can
 118 better use other information from the performance_schema tables to
 119 provide a more complete vision of what MySQL is doing or where it's
 120 busy.
 121
 122 Simon J Mudd
 123 <sjmudd@pobox.com>
 124
 125 ### Code Documenton
 126 [godoc.org/github.com/sjmudd/pstop](http://godoc.org/github.com/sjmudd/pstop)