The Percona ToolKit needs a cookbook. The documentation is reference only, very thin and total void of useful examples. You’re beginning to frustrate the masses.
Here is what’s happening. My MySQL server crashes or stalls ever few months. I searched the Goog and find PT-Stalk :
“watches for a trigger condition to become true, and then collects data to help in diagnosing problems. It is designed to run as a daemon with root privileges, so that you can diagnose intermittent problems that you cannot observe directly. You can also use it to execute a custom command, or to gather the data on demand without waiting for the trigger to happen.”
I attend your webinar. I even attend the Percona Live conference in San Francisco to talke with the developer in person and still I get little more then:
pt-stalk [OPTIONS] [-- MYSQL OPTIONS]
??!!
Anyone else feel the same?
I’m going to take a deep dive into the Percona ToolKit code and try to bring you some working examples (Cut and Paste). I’m going to start with PT-STALK because it fills a need. I’ll pick the next in the line of useful tools that need more documentation.
If you would like be to document a Percona tool you need, leave me a comment.
Tweet
pt-stalk takes care of the most common situation for you, that is checking the values in ‘SHOW GLOBAL STATUS’, or looking at an aggregate version of ‘SHOW PROCESSLIST’ and then running a collection script (pt-collect) if the values exceed a given threshold (perhaps having met this threshold for a given period of time).
You can look at the values of Threads_running or Threads_connected, as typical examples, or count the number of processes in a specific state, such as ‘Sending Data’ or ‘statistics’. Examples of these use cases are embedded in the documentation.
If you have more complex requirements for triggering collection (maybe you want to find when the number of threads in the InnoDB queue exceeds a certain threshold) then you can write a plugin to execute, instead of using the built-in function that only supports ‘SHOW GLOBAL STATUS’ and ‘SHOW PROCESSLIST’. These functions are easy to write, but better documentation in this area is probably needed.
Link | April 16th, 2012 at 4:05 pm
Creating good documentation is a lot of work. The documentation in the tools is very good, but one-sided. It explains what the tools do, but not how to solve problems with them. The domain of problems you can solve and tasks you can do with the tools is enormous. Even if you wrote a book on the tool and contributed it to the toolkit, I wouldn’t accept it because I don’t have the budget to maintain such documentation.
I would welcome an unofficial (non-Percona-hosted, non-Percona-endorsed) community wiki or something like that. Hint, hint?
Looking forward to your pt-stalk guide!
- Baron
Link | April 17th, 2012 at 8:51 am
Oh, I meant to say — we offer training courses, too :)
Link | April 17th, 2012 at 8:52 am
The Percona ToolKit doesn’t need defending. There are lots of helpful tools that provide MUCH! less then these.
My post is really a backwards compliment. I wouldn’t feel so teased by it if I didn’t want to use it so much. I know documentation is hard. That’s why blog is more like a list of HOWTOs.
Will the training be on-line?
Link | April 17th, 2012 at 2:58 pm
Yup. I don’t think crashes and stalls are common. But, yes pt-stalk will take care of capturing what happened when my server hangs at 3:00am and the SysOps do a kill -9.
I though I know the PT-Toolkit but at this years conference I learned about pt-stalk. This is part of why I’ll be going over each tool and blogging about it.
Link | April 17th, 2012 at 3:09 pm
You should email Dave Hildebrandt to give him feedback on what you would find most useful for the training. His email is dave-dot-hildebrandt-at-percona-dot-com.
I think your posts about each tool will be great, and I will read them carefully to see what I can learn. Toolkit users constantly teach me new things about the tools.
Link | April 17th, 2012 at 8:14 pm
While I think reading the documentation fully and trying each thing out and seeing that behavior and experiencing what it does with what ever options is highly valuable in and of itself.
But I have been in the same spot you describe: something’s horribly wrong, time is of the essence, and why isn’t there just a frigging real-use example of how to use this command!!
Building documentation is laborious, but something like this is a perfect topic for a wiki.
Link | April 18th, 2012 at 1:05 pm
Mark, drop me a line. We talked about this in San Francisco. I felt your frustration. Now I would like to talk to you about ways you can help us fill the need.
Link | April 19th, 2012 at 2:20 pm
Mark, I totally agree! In fact, I wrote up the first guide to mk-table-checksum (previously mk, now pt) – http://sheeri.net/content/online-verification-master-and-slaves-are- because it was so frustrating to try to figure out how to use it.
And at the time, mk-table-sync wasn’t reliable (you’d sync, then run mk-table-checksum and the same differences would show up), otherwise I would have written a guide to that.
I’m all for great documentation and I’d love to help this effort out.
Link | April 30th, 2012 at 9:19 pm
totally agree….both with you and Baron….
and on that note, and to consolidate effort, if anyone started a community wiki (google has failed me) please point to it and I will be happy to post anything I learned there and also to look for info ;)
I use PT every week…the more heads learning together the better :)
Link | June 26th, 2012 at 11:20 am
I’ve been using these tools for the past couple of years and would like to help with good examples as I typically use them with just a few args if that. The past few weeks I started to build out the config files for easier usage when problems do come or other tasks such as archiving, comparisons (the list goes on).
Please count me in on sharing my usage as well as learning from all of you.
Link | June 27th, 2012 at 9:59 am
OK – As you can guess I have to many project. Beside my day job of keeping weather data flowing smoothly between the Feds and Public. I’m working on studding the internals of MySQL, keeping my How To documents up to date. Like “The full Monty” and some consulting for others.
Anything you would like to write up I’d be happy to publish with your name. You can email me (mark at grennan dot com) or you could write it up on Google Docs and share it. Thats where I write up all my blog ideas.
Link | June 27th, 2012 at 4:58 pm