MK-LOG-PLAYER(1)

📦

version 7540 · 3 versions

🎀 mk-log-player 🎀

okay bestie, so this is a page from the User Contributed Perl Documentation (that's the (1) bit, it's giving very "one of many, but iconic") and it's all about mk-log-player, which — as the NAME says — is here to replay MySQL query logs. 💅

✨ NAME ✨

mk-log-player — replay MySQL query logs. fr fr that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

Usage: mk-log-player [OPTION...] [DSN]

mk-log-player splits and plays slow log files. (yes, both. multitasking queen. 👑)

Split slow.log on Thread_id into 16 session files, save in ./sessions:

mk-log-player --split Thread_id --session-files 16 --base-dir ./sessions slow.log

Play all those sessions on host1, save results in ./results:

mk-log-player --play ./sessions --base-dir ./results h=host1

Use mk-query-digest to summarize the results:

mk-query-digest ./results/*

💀 RISKS 💀

okay so this section exists to tell you the potential risks — whether known or unknown — of using this tool. The two main categories of risk are:

risks created by the nature of the tool (like, read-only tools vs. read-write tools, you know?), and
risks created by bugs.

This tool is literally meant to load a server as much as possible, for stress-testing purposes. It is not designed to be used on production servers. not even a little. 🙈

At the time of this release there is a bug which causes mk-log-player to exceed max open files during --split. 💀

The authoritative source for updated info is always the online issue tracking system. Issues that affect this tool will be marked as such. You can see a list of such issues at the following URL:

http://www.maatkit.org/bugs/mk-log-player

See also "BUGS" for more on filing bugs and getting help. 🫶

🦋 DESCRIPTION 🦋

mk-log-player does two things, bestie: it splits MySQL query logs into session files, and it plays (executes) queries in session files on a MySQL server. Only session files can be played — slow logs cannot be played directly without being split. periodt.

A session is a group of queries from the slow log that all share a common attribute, usually Thread_id. The common attribute is specified with --split. Multiple sessions are saved into a single session file. See --session-files, --max-sessions, --base-file-name and --base-dir. These session files are played with --play. 🌈

mk-log-player will --play session files in parallel using N number of --threads. (they're not technically threads, but we call them that anyway, iykyk 😭) Each thread will play all the sessions in its given session files. The sessions are played as fast as possible — there are no delays — because the goal is to stress-test and load-test the server. So be careful using this script on a production server! like genuinely.

Each --play thread writes its results to a separate file. These result files are in slow log format so they can be aggregated and summarized with mk-query-digest. See "OUTPUT". ✨

💖 OUTPUT 💖

Both --split and --play have two outputs:

status messages printed to STDOUT to let you know what the script is doing, and
session or result files written to separate files saved in --base-dir.

You can suppress all output to STDOUT for each with --quiet, or increase output with --verbose. 🎀

The session files written by --split are simple text files containing queries grouped into sessions. For example:

-- START SESSION 10

use foo

SELECT col FROM foo_tbl

The format of these session files is important: each query must be a single line separated by a single blank line. And the -- START SESSION comment tells mk-log-player where individual sessions begin and end so that --play can correctly fake Thread_id in its result files. no cap.

The result files written by --play are in slow log format with a minimal header: the only attributes printed are Thread_id, Query_time and Schema. 💅

👑 OPTIONS 👑

Specify at least one of --play, --split or --split-random.

--play and --split are mutually exclusive. (they cannot both be the main character at once, sorry. 🙈)

This tool accepts additional command-line arguments. Refer to the "SYNOPSIS" and usage information for details.

--ask-pass — group: Play. Prompt for a password when connecting to MySQL. 🔐
--base-dir — type: string; default: ./. Base directory for --split session files and --play result file.
--base-file-name — type: string; default: session. Base file name for --split session files and --play result file.

Each --split session file will be saved as <base-file-name>-N.txt, where N is a four digit, zero-padded session ID. For example: session-0003.txt. 🍓

Each --play result file will be saved as <base-file-name>-results-PID.txt, where PID is the process ID of the executing thread.

All files are saved in --base-dir.

--charset — short form: -A; type: string; group: Play. Default character set. If the value is utf8, sets Perl's binmode on STDOUT to utf8, passes the mysql_enable_utf8 option to DBD::mysql, and runs SET NAMES UTF8 after connecting to MySQL. Any other value sets binmode on STDOUT without the utf8 layer, and runs SET NAMES after connecting to MySQL. 🌈
--config — type: Array. Read this comma-separated list of config files; if specified, this must be the first option on the command line.
--defaults-file — short form: -F; type: string. Only read mysql options from the given file.
--dry-run — Print which processes play which session files then exit. 🕵️
--filter — type: string; group: Split. Discard --split events for which this Perl code doesn't return true.

This option only works with --split.

This option allows you to inject Perl code into the tool to affect how the tool runs. Usually your code should examine $event to decided whether or not to allow the event. $event is a hashref of attributes and values of the event being filtered. Or, your code could add new attribute-value pairs to $event for use by other options that accept event attributes as their value. You can find an explanation of the structure of $event at http://code.google.com/p/maatkit/wiki/EventAttributes. 👑

There are two ways to supply your code: on the command line or in a file. If you supply your code on the command line, it is injected into the following subroutine where $filter is your code:

sub {
   MKDEBUG && _d('callback: filter');
   my( $event ) = shift;
   ( $filter ) && return $event;
}

Therefore you must ensure two things: first, that you correctly escape any special characters that need to be escaped on the command line for your shell, and two, that your code is syntactically valid when injected into the subroutine above. (two things bestie, don't skip one 😭)

Here's an example filter supplied on the command line that discards events that are not SELECT statements:

--filter '$event->{arg} =~ m/^select/i'

The second way to supply your code is in a file. If your code is too complex to be expressed on the command line that results in valid syntax in the subroutine above, then you need to put the code in a file and give the file name as the value to --filter. The file should not contain a shebang (#!/usr/bin/perl) line. The entire contents of the file is injected into the following subroutine:

sub {
   MKDEBUG && _d('callback: filter');
   my( $event ) = shift;
   $filter && return $event;
}

That subroutine is almost identical to the one above except your code is not wrapped in parentheses. This allows you to write multi-line code like:

my $event_ok;
if (...) {
   $event_ok = 1;
}
else {
   $event_ok = 0;
}
$event_ok

Notice that the last line is not syntactically valid by itself, but it becomes syntactically valid when injected into the subroutine because it becomes:

$event_ok && return $event;

If your code doesn't compile, the tool will die with an error. Even if your code compiles, it may crash to tool during runtime if, for example, it tries a pattern match an undefined value. No safeguards of any kind of provided so code carefully! 💀

--help — Show help and exit. 🫶
--host — short form: -h; type: string; group: Play. Connect to host.
--iterations — type: int; default: 1; group: Play. How many times each thread should play all its session files. 🔁
--max-sessions — type: int; default: 5000000; group: Split. Maximum number of sessions to --split.

By default, mk-log-player tries to split every session from the log file. For huge logs, however, this can result in millions of sessions. This option causes only the first N number of sessions to be saved. All sessions after this number are ignored, but sessions split before this number will continue to have their queries split even if those queries appear near the end of the log and after this number has been reached. ✨

--only-select — group: Play. Play only SELECT and USE queries; ignore all others.
--password — short form: -p; type: string; group: Play. Password to use when connecting. 🔐
--pid — type: string. Create the given PID file. The file contains the process ID of the script. The PID file is removed when the script exits. Before starting, the script checks if the PID file already exists. If it does not, then the script creates and writes its own PID to it. If it does, then the script checks the following: if the file contains a PID and a process is running with that PID, then the script dies; or, if there is no process running with that PID, then the script overwrites the file with its own PID and starts; else, if the file contains no PID, then the script dies. 💀
--play — type: string; group: Play. Play (execute) session files created by --split.

The argument to play must be a comma-separated list of session files created by --split or a directory. If the argument is a directory, ALL files in that directory will be played. 👑

--port — short form: -P; type: int; group: Play. Port number to use for connection.
--print — group: Play. Print queries instead of playing them; requires --play.

You must also specify --play with --print. Although the queries will not be executed, --play is required to specify which session files to read. 🖨️

--quiet — short form: -q. Do not print anything; disables --verbose. 🤫
--[no]results — default: yes. Print --play results to files in --base-dir.
--session-files — type: int; default: 8; group: Split. Number of session files to create with --split. 🎀

...and bestie, we're not even done — more of this page is coming, so don't go anywhere 💜

...so the number of session files should either match the number of --threads you're gonna --play with, or be an even multiple of --threads. Why do we care? Because it's the whole key to max performance, babes, and here's the receipts:

it lets every thread have roughly the same amount of sessions to play 🫶
it avoids having to open/close a million session files
it avoids disk IO overhead by doing big ol' sequential reads ✨

You might wanna bump this number past --threads if each session file ends up being a chonky girl. Like, splitting a 20G log into 8 session files gives you roughly eight 2G session files. 💅

🌈 DSN OPTIONS 🌈

These DSN options are used to build a DSN. Each option goes in like "option=value". Heads up bestie: these options are case-sensitive, so P and p are not the same option, okay? There can't be any whitespace before or after the =, and if the value has whitespace in it, it's gotta be quoted. DSN options are comma-separated. See the maatkit manpage for the full details. 🎀

A
- dsn: charset; copy: yes
- Default character set.
D
- dsn: database; copy: yes
- Default database.
F
- dsn: mysql_read_default_file; copy: yes
- Only read default options from the given file.
h
- dsn: host; copy: yes
- Connect to host.
p
- dsn: password; copy: yes
- Password to use when connecting.
P
- dsn: port; copy: yes
- Port number to use for connection.
S
- dsn: mysql_socket; copy: yes
- Socket file to use for connection.
u
- dsn: user; copy: yes
- User for login if not current user.

⬇️ DOWNLOADING ⬇️

You can download Maatkit from Google Code at <http://code.google.com/p/maatkit/>, or you can grab any of the tools super easily with a command like this:

wget http://www.maatkit.org/get/toolname
or
wget http://www.maatkit.org/trunk/toolname

Where toolname gets swapped out for the name (or even just a fragment of a name) of any of the Maatkit tools. Once it's downloaded, it's ready to run — no installation needed, periodt. The first URL gets you the latest released version of the tool, and the second one gets the latest trunk code from Subversion. ✨

🌱 ENVIRONMENT 🌱

The environment variable MKDEBUG enables verbose debugging output in all of the Maatkit tools:

MKDEBUG=1 mk-....

🖥️ SYSTEM REQUIREMENTS 🖥️

You need Perl, plus some core packages that honestly oughta already be installed in any reasonably new version of Perl. 🐪

💀 BUGS 💀

For a list of known bugs, go look at <http://www.maatkit.org/bugs/mk-log-player>.

Please use Google Code Issues and Groups to report bugs or request support: <http://code.google.com/p/maatkit/>. You can also hop into #maatkit on Freenode to chat Maatkit with us. 🫶

When you report, please include the complete command-line you used to reproduce the problem, the version of all MySQL servers involved, the complete output of the tool when it's run with --version, and if you can, the debugging output produced by running with the MKDEBUG=1 environment variable. The more deets the better, fr fr. 🔍

📜 COPYRIGHT, LICENSE AND WARRANTY 📜

THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

That's the all-caps legal bit and it means business — no warranty, bestie.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2; OR the Perl Artistic License. On UNIX and similar systems, you can issue man perlgpl or man perlartistic to read these licenses.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

👑 AUTHOR 👑

Daniel Nichter

🌟 ABOUT MAATKIT 🌟

This tool is part of Maatkit, a toolkit for power users of MySQL. Maatkit was created by Baron Schwartz; Baron and Daniel Nichter are the primary code contributors. Both are employed by Percona. Financial support for Maatkit development is primarily provided by Percona and its clients. 💖

🏷️ VERSION 🏷️

This manual page documents Ver 1.0.9 Distrib 7540 $Revision: 7531 $.

And that's the whole thing, bestie — this page documents Ver 1.0.9 Distrib 7540 (revision 7531), rendered for perl v5.42.0 and dated 2025-07-24. Go forth and split those logs, you absolute icon. 💅✨🦋

📦 where this page comes from

fedora 43: maatkit 7540-39.fc43 · GPL-2.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms