--- name: "mtop" section: "1p" platform: "linux" package: "mtop" version: "0.6.6-1.2" release: "Debian 5.0 (Lenny)" platforms: ["linux"] url: "https://new.carta.tech/mtop/1p" --- # mtop(1p) Shows top mysql threads ## NAME **mtop** - Shows top mysql threads ## SYNOPSIS ``` mtop [--host={mysql_host}] [--dbuser={mysql_user}] [--password={mysqluser_pw}] [--seconds={refresh}] [--[no]idle] [--filter-user={regex}] [--filter-host={regex}] [--filter-db={regex}] [--filter-command={regex}] [--filter-state={regex}] [--filter-info={{regex}}] [--fold-select-columns] [--user={user}] [--manualrefresh] [--slow={seconds}] [--vs|veryslow={seconds}] [--vvs|veryveryslow={seconds}] ``` ``` mtop --help ``` ``` mtop --version ``` ## DESCRIPTION Shows the MySQL commands consuming the greatest time. By default, only non-sleeping threads are shown, the **--idle** option shows idle threads. While running several keys will affect the operation of **mtop**. Hitting **h** or **?** will show the available options. Normally, run as a console program this will allow you to see errant or badly optimized queries as they will stay on the screen for a while. However, if you are hunting for short lived queries, running in the **manualrefresh** mode with a short refresh time will allow you to catch short lived queries as well. The following keys are active while **mtop** is running: ``` q - quit ? - help ``` ``` Filtering/display ``` ``` s - change the number of seconds to delay between updates m - toggle manual refresh mode on/off d - filter display with regular expression (user/host/db/command/state/info) F - fold/unfold column names in select statement display h - display process for only one host u - display process for only one user i - toggle all/non-Sleeping process display o - reverse the sort order ``` ``` Control/Detail ``` ``` k - kill processes; send a kill to a list of ids e - explain a process; show query optimizer info z - zoom in on a process; show sql statement detail f - flush stats (reset show status variables) t - show mysqld stats (show status/mysqladmin ext) T - show short/important status v - show mysqld variables (show variables/mysqladmin vars) r - show replication status for master/slaves ``` **Main Screen** The main query screen shows the following information as well as the currently active queries (explanations are from the MySQL online manual and references refer to the section in the manual where the explanation came from): - n Threads: running, cached The **n** Threads represents how many threads the mysqld has allocated. One thread is allocated for each user connection. Additional threads are allocated for replication. - Queries/slow: Total queries / Total SLOW QUERIES The first number is the total number of queries sent to the server since the last 'flush status' or since server start. The second number is the number of queries that have taken more than long\_query\_time. See section 4.9.5 The Slow Query Log. - Cache Hit: Cache hit ratio This is the percentage of times a key read is handled from the key buffer cache. See section 4.5.7.4 **SHOW VARIABLES** of the MySQL manual for more information. - Opened tables: tables opened MySQL has a cache for open tables. If 'opened tables' is high, your cache may be too small. Look at the MySQL manual section: **5.4.7 How MySQL Opens** **and Closes Tables** for further information. - RRN: Handler\_read\_rnd\_next Number of requests to read the next row in the datafile. This will be high if you are doing a lot of table scans. Generally this suggests that your tables are not properly indexed or that your queries are not written to take advantage of the indexes you have. (4.5.7.3) - TLW: Table\_locks\_waited Number of times a table lock could not be acquired immediately and a wait was needed. If this is high, and you have performance problems, you should first optimise your queries, and then either split your table(s) or use replication. Available after 3.23.33. (4.5.7.3) - SFJ: Select\_full\_join Number of joins without keys (If this is not 0, you should carefully check the indexes of your tables). (4.5.7.3) - SMP: Sort\_merge\_passes Number of merges passes the sort algoritm have had to do. If this value is large you should consider increasing sort\_buffer. (4.5.7.3) - QPS: Questions per second The total number of sql commands handled by the MySQL server since startup or the last **flush status** command. **Statistics/Variables** When viewing the *stats* screen (**t**), the screen will refresh until a key is pressed at which point you will return to the main screen. The bottom of the *stats* screen is denoted with a line containing **---**. If you do not see that line, resize your screen until you do. The statistics screen has the following format: ``` Stat: total [avg per sec / instant per sec ] ``` For example: ``` Questions: 720,672 [30/12] ``` The *short/important* status screen is a list of recommendations from the MySQL manual. The first number is the total since startup or the last 'flush status'. The second number is the number per second since startup or flush. The last is the number per second since the last screen refresh. The *variables* screen only shows the information once and returns to the main screen as the variables do not change after server startup. **Replication** The replication monitor screen looks for a master or slave server running on the currently monitored mysqld. If a master server is found, it then tries to connect to each slave connected to the master. Replication is shown for all masters and slaves found. Offsets from the master for each of the slaves is shown. Note: the offset may be less than zero because the slave position is checked after the master position. The offset shown is the number of queries in the binlog that the slave has to process before being caught up with the master. ## OPTIONS All options can be abbreviated by their shortest unique abbreviation. - \-?, --help Show the help screen and exit. - \-v, --version Show the version number and exit. - \-h {mysql\_host}, --host={mysql\_host} By default, the mysqld on localhost is monitored. Specify an alternate host with this option. - \-dbu {mysql\_user}, --dbuser={mysql\_user} By default, the user 'mysqltop' is used to connect to the database. Specify an alternate user with this option. - \-p {mysqluser\_pw}, --password={mysqluser\_pw} By default, there is no password associated with the mysqltop user, specify a password with this option. - \-se {refresh}, --seconds={refresh} The default screen refresh is 5 seconds. - \-sl {seconds}, --slow={seconds} The number of seconds before a slow query is highlighted. The default is the server's long\_query configuration variable. - \-vs {seconds}, --veryslow={seconds} The number of seconds before a very slow query is highlighted. The default is the the --slow option \* 2. - \-vvs {seconds}, --veryveryslow={seconds} The number of seconds before a very very slow query is highlighted. The default is the the --slow option \* 4. - \-i, --\[no\]idle By default, processes in the **Sleep** command state are not shown. This option turns on display of idle threads. - \-u {user}, --user={user} Show only threads owned by this user. - \-fu {regex\_pattern}, --filter-user={regex\_pattern} - \-fh {regex\_pattern}, --filter-host={regex\_pattern} - \-fd {regex\_pattern}, --filter-db={regex\_pattern} - \-fs {regex\_pattern}, --filter-state={regex\_pattern} - \-fc {regex\_pattern}, --filter-command={regex\_pattern} - \-fi {regex\_pattern}, --filter-info={regex\_pattern} Filter the display based on the **regex\_pattern** provided. The **regex\_pattern** is a perl regular expression. The regular expression match is done with case insensitivity. For example, to only show **select** statements on the **user** table, use the following: ``` --filter-info='select from user' ``` or, to be more forgiving for mutil-table joins and extra spaces, use: ``` --filter-info='select\s+from\s+.*\buser\b.*where' ``` These same regular expression filters can be used with the interactive **d** command. Be careful to escape any special shell characters in the regex. - \-m, --manualrefresh In this mode, the screen only refreshes when the user hits a key on the keyboard. The screen will refresh automatically until a query is seen and then wait for further input. An uppercase M will appear in the top right hand corner of the screen to indicate that you are in this mode. All options can be stored in initialization files. Command line options override options stored in the initialization file(s). The following files are checked for arguments: current direcotry .mtoprc, home directory .mtoprc, /usr/local/etc/mtoprc, /etc/mtoprc. Options in the former files override options in the later files. The format of the initialization file is one option per line. Options are specified just as they would be on the command line. They can be abbreviated and use the one or two hyphen syntax. Comments and blank lines are ignored. The following is an exmple .mtoprc file which sets a user filter to user1 and sets the refresh rate to one second: ``` # Only look at 'user1' -fu user1 --seconds=1 # refresh every one seconds ``` ## SETUP The most convenient way to setup your system to use **mtop** is to create a database user called **mysqltop** which has no password. For security purposes, this user should have all privileges set to **N** except **Process\_priv** which must be set to **Y**. To grant these privileges, execute the following from the MySQL command prompt For mysql 4.0.2 and greater: ``` mysql> grant super, reload, process on *.* to mysqltop; mysql> grant super, reload, process on *.* to mysqltop@localhost; mysql> flush privileges; ``` For mysql 3.x and 4.0.1: ``` mysql> grant reload, process on *.* to mysqltop; mysql> grant reload, process on *.* to mysqltop@localhost; mysql> flush privileges; ``` Notes: - • GRANT only works in MySQL 3.22.11 or later, for earlier versions add the user manually and fix the permissions as noted above. - • The GRANT to mysqltop and mysqltop@localhost may be modified depending upon which hosts you want to grant access from. In general, you probably want to limit it to the hosts in your domain. - • The **reload** privilege is not required for **mtop** to do basic monitoring. It is only needed if you wish to issue **flush** commands from **mtop**. The **super** privilege is needed if you wish to kill queries in mysql 4.0.2 versions and above. In 3.x, the **process** privilege allows a user to terminate a query. Initially, **mtop** does not connect to a specific database. Most commands this program issues are non-database specific (SHOW FULL PROCESSLIST, SHOW VARIABLES, KILL id). However, when database-specific commands are needed, **mtop** will try to connect to the the required database and prompt for a username/password if the default one fails. To install **mtop**, run the following shell commands: ``` perl Makefile.PL make make install ``` The default {install\_prefix} is /usr/local which means that **mtop** is installed in /usr/local/bin/. To change this, run: ``` perl Makefile.PL --prefix={install_prefix} ``` or modify the PREFIX line in Makefile.PL. Requires the following perl modules: ``` Module Available At ------------ -------------------------------------------------------- Curses http://www.cpan.org/authors/id/WPS DBI Distributed as Bundle::DBI: http://www.cpan.org/authors/id/TIMB DBD::mysql http://www.cpan.org/authors/id/JWIED Getopt::Long (Distributed with Perl 5) Net::Domain Part of libnet: http://www.cpan.org/authors/id/GBARR/ ``` ## AUTHOR Marc Prewitt, Chelsea Networks \ Copyright (C) 2002 Marc Prewitt/Chelsea Networks, under the GNU GPL. mtop comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions; see the COPYING file for details. ## KNOWN BUGS The cache hit ratio may look very low if your server receives more than 4 billion key\_read\_requests. This is due to a roll-over condition. If that number exceeds 4 billion and change, it rolls over to 1. The cache hit ratio is calculated as: 100 - (key\_reads/key\_read\_requests) \* 100. If you are really trying to focus on the cache hit ratio, flush the status variables with the **mtop** **f** command to reset both the key\_reads and key\_read\_requests. Win2K telnet.exe - If you are using the Windows 2000 telnet program, it defaults to ansi mode which doesn't work well with curses (in my testing on Solaris 8). To work around this, set the terminal type to vt100. To do this, issue the following command from the telnet prompt before connecting to a host: ``` set term vt100 ``` Alternatively, you can manually set your TERM environment variable to vt100 after you are logged in. ## TODO Offer sorts by other columns For the 'More:' paging, it would be nice to support 'Less' behaviour. Add 'n' command and properly calculate number of lines on screen. ``` $Id: mtop.PL,v 1.61 2004/09/12 22:22:03 mdprewitt Exp $ ```