MYTOP(1)

📦

version 1.7 · 11 versions

💅 mytop(1)

okay so this is mytop, bestie — it's a User Contributed Perl Documentation page, and it does exactly what it sounds like: shows you your MySQL server's performance info in a live view, kinda like top but for MySQL. iconic behavior honestly.

✨ NAME ✨

mytop — display MySQL server performance info like top 🎀

🌸 SYNOPSIS 🌸

mytop [options]

like, that's it. you just run it with options. slay.

🦋 AVAILABILITY 🦋

the latest version of mytop is available from

http://jeremy.zawodny.com/mysql/mytop/

and it might also be on CPAN as well. two places, no gatekeeping. 💖

💜 REQUIREMENTS 💜

so for mytop to function properly (like, actually work), you must have the following:

Perl 5.005 or newer
Getopt::Long
DBI and DBD::mysql
Term::ReadKey from CPAN

ngl most systems probably have all of those installed already — except for Term::ReadKey, that one's the tricky one 😭 you'll need to pick that up from the CPAN yourself. you can grab Term::ReadKey right here:

http://search.cpan.org/search?dist=TermReadKey

and you obviously need access to a MySQL server (version 3.22.x or 3.23.x) with the necessary security to run the SHOW PROCESSLIST and SHOW GLOBAL STATUS commands. like, it can't do the thing if it's not allowed to do the thing, yk?

if you're a Windows user running ActiveState's Perl, you can use PPM (the Perl Package Manager) to install the MySQL and Term::ReadKey modules. convenient fr. 🫶

🎨 Optional Color Support 🎨

also — and this is the fun part — if you want a color mytop (which is recommended, lowkey it's gorgeous), install Term::ANSIColor from the CPAN:

http://search.cpan.org/search?dist=ANSIColor

once you do, mytop will automatically use it. no config needed, it just notices. ✨

but heads up: color is not yet working on Windows. patches welcome. :-) like genuinely, they said it, not me 💀

⏱️ Optional Hi-Res Timing ⏱️

if you want mytop to give you more accurate real-time queries-per-second statistics, install the Time::HiRes module from CPAN. mytop will automatically notice that you have it and use it rather than the standard timing mechanism. it literally just knows. main character energy. 👑

💻 Platforms 💻

mytop is known to work on:

Linux (2.2.x, 2.4.x)
FreeBSD (2.2, 3.x, 4.x)
Mac OS X
BSDI 4.x
Solaris 2.x
Windows NT 4.x (ActivePerl)

if you find that it works on another platform, please let them know. given that it's all Perl code, the expectation is that it's rather portable to Unix and Unix-like systems. heck, it might even work on Win32 systems. 🌀

🌸 DESCRIPTION 🌸

Okay so first things first — bestie, help is always welcome in improving this software. Fr fr. Feel free to contact the author (peep the AUTHOR section below) with bug reports, fixes, suggestions, and comments. Also, BUGS will hand you a whole list of stuff this software genuinely can't do yet. No cap.

Having said that, here are the details on how it works and what you can do with it. Buckle up. 🎀

✨ The Basics ✨

mytop was inspired by the system monitoring tool top. The author routinely uses top on Linux, FreeBSD, and Solaris, so you're lowkey gonna notice features from each of them showing up here. It's giving ✨greatest hits✨.

mytop will connect to a MySQL server and periodically run the SHOW PROCESSLIST and SHOW GLOBAL STATUS commands, then attempt to summarize the info from them in a useful format. Iconic behavior, honestly. 👑

🦋 The Display 🦋

The mytop display screen is really broken into two parts. The top 4 lines (the header) contain summary info about your MySQL server. For example, you might see something like:

MySQL on localhost (4.0.13-log)                        up 1+11:13:00
[23:29:11]
 Queries: 19.3M  qps:  160 Slow:     1.0         Se/In/Up/De(%):
 00/80/03/17
             qps now:  219 Slow qps: 0.0  Threads:    1 (   1/  16)
 00/74/00/25
 Key Efficiency: 99.3%  Bps in/out: 30.5k/162.8   Now in/out: 32.7k/
 3.3k

Let's break down what each of those lines is actually telling you, bestie 💅:

Line 1 identifies the hostname of the server (localhost) and the version of MySQL it's running. On the right hand side you get the uptime of the MySQL server process in days+hours:minutes:seconds format (much like FreeBSD's top) plus the current time. ⏰
Line 2 displays the total number of queries the server has processed, the average number of queries per second, the number of slow queries, and the percentage of Select, Insert, Update, and Delete queries.
Line 3 is your real-time values. First is the number of queries per second, then the number of slow queries, followed by query percentages (just like on the previous line).
Line 4 displays key buffer efficiency (that's how often keys are read from the buffer rather than disk) and the number of bytes that MySQL has sent and received — both over all and in the last cycle.

You can toggle the header by hitting h while running mytop. 🫶

The second part of the display lists as many threads as can fit on screen. By default they're sorted according to their idle time (least idle first). The display looks like:

    Id     User       Host      Dbase   Time      Cmd Query or State
    --     ----       ----      -----   ----      --- --------------
    61  jzawodn  localhost      music      0    Query show processlist

As you can see, the thread id, username, host from which the user is connecting, database to which the user is connected, number of seconds of idle time, the command the thread is executing, and the query info are all displayed. The whole package. 💖

Often times the query info is what you are really interested in, so it is good to run mytop in an xterm that is wider than the normal 80 columns if possible. Trust me on this one — cramped columns are not the vibe. 😭

The thread display color-codes the threads if you have installed color support. The current color scheme only works well in a window with a dark (like black) background. The colors are selected according to the Command column of the display:

Query — Yellow
Sleep — White
Connect — Green

Those are purely arbitrary and will be customizable in a future release. If they annoy you, just start mytop with the -nocolor flag or adjust your config file appropriately. 🌈

💜 Arguments 💜

mytop handles long and short command-line arguments. Not all options have both long and short formats, however — it's giving "we do what we want" energy. The long arguments can start with one or two dashes - or --. They are shown here with just one. 🎀

-u, -user username — Username to use when logging in to the MySQL server. Default: root.
-p, -pass, -password password — Password to use when logging in to the MySQL server. Default: none.
-h, -host hostname[:port] — Hostname of the MySQL server. The hostname may be followed by an optional port number. Note that the port is specified separate from the host when using a config file. Default: localhost.
-port, -P port — If you're running MySQL on a non-standard port, use this to specify the port number. Default: 3306.
-s, -delay seconds — How long between display refreshes. Default: 5.
-d, -db, -database database — Use if you'd like mytop to connect to a specific database by default. Default: test.
-b, -batch, -batchmode — In batch mode, mytop runs only once, does not clear the screen, and places no limit on the number of lines it will print. This is suitable for running periodically (perhaps from cron) to capture the info into a file for later viewing. You might use batch mode in a CGI script to occasionally display your MySQL server status on the web. Default: unset.
-S, -socket /path/to/socket — If you're running mytop on the same host as MySQL, you may wish to have it use the MySQL socket directly rather than a standard TCP/IP connection. If you do, just specify one. Note that specifying a socket will make mytop ignore any host and/or port that you might have specified. If the socket does not exist (or the file specified is not a socket), this option will be ignored and mytop will use the hostname and port number instead. Default: none.
-header, -noheader — Specify if you want the header to display or not. You can toggle this with the h key while mytop is running. Default: header.
-color, -nocolor — Specify if you want a color display. This has no effect if you don't have color support available. Default: if you have color support, mytop will try color unless you tell it not to.
-i, -idle, -noidle — Specify if you want idle (sleeping) threads to appear in the list. If sleeping threads are omitted, the default sorting order is reversed so that the longest running queries appear at the top of the list. Default: idle.
-prompt, -noprompt — Specify if you want to be prompted to type in your database password. This provides a little bit more security, since it not only prevents the password from being viewable in a process list, but also doesn't require the password to be stored in plain text in your ~/.mytop config file. You will only be prompted if a password has not been specified in your config file or through another command line option. Default: noprompt.
-resolve — If you have skip-resolve set on MySQL (to keep it from doing a reverse DNS lookup on each inbound connection), mytop can replace IP addresses with hostnames by toggling this option. Default: noresolve.

⚠️ Command-line arguments will always take precedence over config file options. That happens because the config file is read BEFORE the command-line arguments are applied. Order matters, bestie. 🧚

🍓 Config File 🍓

Instead of always using bulky command-line parameters, you can also use a config file in your home directory (~/.mytop). If present, mytop will read it automatically. It's read before any of your command-line arguments are processed, so your command-line arguments will override directives in the config file.

Here is a sample config file ~/.mytop which implements the defaults described above:

 user=root
 pass=
 host=localhost
 db=test
 delay=5
 port=3306
 socket=
 batchmode=0
 header=1
 color=1
 idle=1

Using a config file will help to ensure that your database password isn't visible to users on the command-line. Just make sure that the permissions on ~/.mytop are such that others cannot read it (unless you want them to, of course 👀).

You may have white space on either side of the = in lines of the config file. Slay, formatting freedom.

👑 Shortcut Keys 👑

The following keys perform various actions while mytop is running. Those which have not been implemented are listed as such. They're included to give the user an idea of what is coming. ✨future drop✨

? — Display help.
c — Show "command counters" based on the Com_* values in SHOW GLOBAL STATUS. This is a new feature. Feedback welcome. 🫶
d — Show only threads connected to a particular database.
f — Given a thread id, display the entire query that thread was (and still may be) running.
F — Disable all filtering (host, user, and db).
h — Only show queries from a particular host.
H — Toggle the header display. You can also specify either header=0 or header=1 in your config file to set the default behavior.
i — Toggle the display of idle (sleeping) threads. If sleeping threads are filtered, the default sorting order is reversed so that the longest running queries appear at the top of the list.
I — Switch to InnoDB Status mode. The output of SHOW INNODB STATUS will be displayed every cycle. In a future version, this may actually summarize that data rather than producing raw output.
k — Kill a thread.
m — Toggle modes. Currently this switches from top mode to qps (Queries Per Second Mode). In this mode, mytop will write out one integer per second. The number written reflects the number of queries executed by the server in the previous one second interval. More modes may be added in the future.
o — Reverse the default sort order.
p — Pause display.
q — Quit mytop.
r — Reset the server's status counters via a FLUSH STATUS command.
s — Change the sleep time (number of seconds between display refreshes).
u — Show only threads owned by a given user.

Couple of cute little crossovers between keys and flags, iykyk 💅:

The s key has a command-line counterpart: -s.
The h key has two command-line counterparts: -header and -noheader.

🐛 BUGS 🐛

Okay so, real talk: this section is basically BUGS + WishList, and the author is being super upfront about it.

If mytop is chatting with a version 3.22.x MySQL server, some performance info just ... isn't available. Extra info (mostly about threads) got added to the output of SHOW STATUS in MySQL 3.23.x, and mytop uses that. If it's not there, you'll literally see zeros where the real numbers should be. 💀
Just running this program will bump your overall counters (like the number of queries run). Whether that counts as a bug is honestly a vibe call — you may or may not see it that way.
mytop eats too much CPU time while it's running (verified on older versions of Linux and FreeBSD). It's probably a Term::ReadKey situation. The author hasn't had time to investigate yet, so mytop now automatically lowers its priority when you run it. You might also think about running mytop on another workstation instead of your database server. Plot twist: mytop on Solaris does not have this problem, and newer versions of Linux and FreeBSD seem to have fixed it.
You can't specify the maximum number of threads to list. If you have a bunch of threads and a tall xterm, mytop will always try to display as many as it can fit. That's just the rule.
Most columns in the display have a small maximum width. If your database/user/host names are fairly long, the display may look odd. The author has no good idea how best to deal with that yet — suggestions are welcome. 🫶
It'd be nice if you could just add mytop configuration directives in your my.cnf file instead of having a separate config file.
You should be able to specify the columns you'd like to see in the display and the order in which they appear. For example, if you only have one username that connects to your database, it's probably not worth having the User column show up.

👑 AUTHOR 👑

mytop was developed and is maintained by Jeremy D. Zawodny (Jeremy@Zawodny.com).

If you wanna e-mail him about this software, PLEASE subscribe to the mytop mailing list first. Check the mytop homepage for the details. 💌

⚠️ DISCLAIMER ⚠️

While he uses this software in his job at Yahoo!, he is solely responsible for it. Yahoo! does not necessarily support this software in any way. It's just a personal idea that happened to be very useful at his job.

💼 RECRUITING 💼

If you hack Perl and grok MySQL, come work at Yahoo! — contact the author for details. Or just send him your resume. Er, unless we just had layoffs, in which case we're not hiring. :-(

🔗 SEE ALSO 🔗

If you're not sure where some of the output of mytop is coming from, please check the MySQL manual. It's giving documentation energy. ✨

💖 CREDITS 💖

Fix a bug. Add a feature. See your name here! (That's the energy, bestie.)

Many thanks go to these fine folks:

Sami Ahlroos (sami@avis-net.de) — suggested the idle/noidle stuff.
Jan Willamowius (jan@janhh.shnet.org) — Mirnor bug report. Documentation fixes. (Keeping the typo exactly as it appeared, iykyk.)
Alex Osipov (alex@acky.net) — long command-line options, Unix socket support.
Stephane Enten (tuf@grolier.fr) — suggested batch mode.
Richard Ellerbrock (richarde@eskom.co.za) — bug reports and usability suggestions.
William R. Mattil (wrm@newton.irngtx.tel.gte.com) — bug report about empty passwords not working.
Benjamin Pflugmann (philemon@spin.de) — suggested the -P command-line flag as well as other changes.
Justin Mecham (justin@aspect.net) — suggested setting $0 to mytop.
Thorsten Kunz (thorsten.kunz@de.tiscali.com) — provided a fix for cases when we try to remove the domain name from the display even if it is actually an IP address.
Sasha Pachev (sasha@mysql.com) — provided the idea of real-time queries per second in the main display.
Paul DuBois (paul@snake.net) — pointed out some option-handling bugs.
Mike Wexler (mwexler@tias.com) — suggested that we don't mangle (normalize) whitespace in query info by default.
Mark Zweifel (markez@yahoo-inc.com) — make the --idle command-line argument negatable.
Axel Schwenke (schwenke@jobpilot.de) — noticed the inccorect formula for query cache hit percentages in version 1.2. (Again: typo preserved, no cap.)
Steven Roussey (sroussey@network54.com) — supplied a patch to help filter binary junk in queries so that terminals don't freak out.
jon r. luini (falcon@chime.com) — supplied a patch that formed the basis for -prompt support. Sean Leach (sleach@wiggum.com) submitted a similar patch.
Yogish Baliga (baliga@yahoo-inc.com) — supplied a patch that formed the basis for -resolve support.
Per Andreas Buer (perbu@linpro.no) — supplied an excellent patch to tidy up the top display. This includes showing most values in short form, such as 10k rather than 10000.

See the Changes file on the mytop distribution page for more details on what has changed.

📜 LICENSE 📜

mytop is licensed under the GNU General Public License version 2. For the full license information, please visit http://www.gnu.org/copyleft/gpl.html. That's the legal tea. ☕

That's the whole page, bestie — rendered with perl v5.32.1, dated 2022-07-22, and it's literally MYTOP(1) 💅✨

📦 where this page comes from

epel 9: mytop 1.7-24.b737f60.el9 · GPLv2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms