PT-IOPROFILE(1)

📦
version 3.7.1_4 · 5 versions
, in arch rolling

🌸 pt-ioprofile(1) — like, the whole entire manual, bestie 💅

okay so real talk: this is the manual page for pt-ioprofile, straight out of the User Contributed Perl Documentation corner of the universe. she's a Perl script, she's nosy, she watches your process's IO, and she will absolutely freeze your server. let's get into it 🫶

✨ NAME ✨

pt-ioprofile — watch a process's IO and print out a table of file and I/O activity. that's it, that's the whole vibe. 👑

🦋 SYNOPSIS 🦋

Usage: pt-ioprofile [OPTIONS] [FILE]

so pt-ioprofile does two things, and only two things, bestie:

  1. grab lsof+strace for -s seconds
  2. aggregate the result

BUT — and this is the plot twist — if you specify a FILE, then step 1) is literally not performed. like, at all. skip. bye. 💀

💀 RISKS 💀

WARNING: pt-ioprofile freezes the server and may crash the process, or make it perform badly after detaching, or leave it in a sleeping state!

not me opening the manual with a jumpscare 😭 okay but seriously, before you use this tool, please, please, please:

  • read the tool's documentation
  • review the tool's known "BUGS"
  • test the tool on a non-production server
  • back up your production server and verify the backups

pt-ioprofile should be considered an intrusive tool, and should not be used on production servers unless you understand and accept the risks. that's not me being dramatic, that's the manual being dramatic. we're both right. 🙈

💖 DESCRIPTION 💖

pt-ioprofile uses strace and lsof to watch a process's IO and print out a table of files and I/O activity. by default, it watches the mysqld process for 30 seconds. the output is giving:

Tue Dec 27 15:33:57 PST 2011
Tracing process ID 1833
     total       read      write      lseek  ftruncate filename
  0.000150   0.000029   0.000068   0.000038   0.000015 /tmp/ibBE5opS

you probably need to run this tool as root. yes, root. it's that kind of tool. 💅

here's the tea on how it works: pt-ioprofile works by attaching strace to the process using ptrace(), which will make it run very slowly until strace detaches. in addition to freezing the server, there's some risk of the process crashing or performing badly after strace detaches from it, or of strace not detaching cleanly and leaving the process in a sleeping state. as a result, this should be considered an intrusive tool, and should not be used on production servers unless you are comfortable with that.

like... she's powerful, but she's a lot. 🌀

✨ OPTIONS ✨

  • --aggregate — short form: -a; type: string; default: sum

the aggregate function, either sum or avg.

if sum, then each cell will contain the sum of the values in it. if avg, then each cell will contain the average of the values in it. math! slay! 🧮

  • --cell — short form: -c; type: string; default: times

the cell contents. valid values are:

  • count — Count of I/O operations
  • sizes — Sizes of I/O operations
  • times — I/O operation timing
  • --group-by — short form: -g; type: string; default: filename

the group-by item. valid values are:

  • all — Summarize into a single line of output
  • filename — One line of output per filename
  • pid — One line of output per process ID
  • --help — print help and exit. the classic. 🎀
  • --profile-pid — short form: -p; type: int

the PID to profile — this one overrides --profile-process. it's giving main character energy, it wins the argument. 👑

  • --profile-process — short form: -b; type: string; default: mysqld

the process name to profile. yes, default is mysqld, no she will not apologize.

  • --run-time — type: int; default: 30

how long to profile. thirty seconds of pure observation, bestie. ⏱️

  • --save-samples — type: string

filename to save samples in; these can be used for later analysis. save it for the group chat 💌

  • --version — print the tool's version and exit. iconic, brief, perfect.

🌈 ENVIRONMENT 🌈

this tool does not use any environment variables. nothing. zero. a completely clean environment slate. (the PTDEBUG thing down in BUGS is mentioned by name but the manual says here that no environment variables are used — so don't come for me, I'm just the messenger 🫶)

🧚 SYSTEM REQUIREMENTS 🧚

this tool requires the Bourne shell (/bin/sh). that's the whole list. short and sweet.

🐛 BUGS 🐛

for a list of known bugs, see <https://jira.percona.com/projects/PT/issues>.

please report bugs at <https://jira.percona.com/projects/PT>. include the following information in your bug report:

  • Complete command-line used to run the tool
  • Tool --version
  • MySQL version of all servers involved
  • Output from the tool including STDERR
  • Input files (log/dump/config files, etc.)

if possible, include debugging output by running the tool with PTDEBUG; see "ENVIRONMENT".

like, give them the receipts. all of them. 🧾

🙈 ATTENTION 🙈

using PTDEBUG might expose passwords. when debug is enabled, all command line parameters are shown in the output. so maybe don't paste that into a public ticket unless you want the whole internet to know. 😭🔐

⭐ DOWNLOADING ⭐

visit <http://www.percona.com/software/percona-toolkit/> to download the latest release of Percona Toolkit. or, get the latest release from the command line:

wget percona.com/get/percona-toolkit.tar.gz

wget percona.com/get/percona-toolkit.rpm

wget percona.com/get/percona-toolkit.deb

you can also get individual tools from the latest release:

wget percona.com/get/TOOL

replace TOOL with the name of any tool. mix and match, it's a whole aesthetic. 🛍️

👑 AUTHORS 👑

Baron Schwartz

💜 ABOUT PERCONA TOOLKIT 💜

this tool is part of Percona Toolkit, a collection of advanced command-line tools for MySQL developed by Percona. Percona Toolkit was forked from two projects in June, 2011: Maatkit and Aspersa. those projects were created by Baron Schwartz and primarily developed by him and Daniel Nichter. visit <http://www.percona.com/software/> to learn about other free, open-source software from Percona. history! lore! we love to see it. 📚

this program is copyright 2011-2026 Percona LLC and/or its affiliates, 2010-2011 Baron Schwartz.

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.

(no warranty, babe. none. not even the implied ones. 😭)

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, version 2 along with this program; if not, see <https://www.gnu.org/licenses/>.

🌟 VERSION 🌟

pt-ioprofile 3.7.1-4

and that's the whole page, bestie!! 💖 this particular copy was brought to you by perl v5.42.2, dated 2026-09-01 — so like, mark your calendar, screenshot it, frame it. go freeze a server responsibly (or don't, please don't, test on non-production). love u, bye!! 🦋🎀✨

📦 where this page comes from