1MK-LOADAVG(1) User Contributed Perl Documentation MK-LOADAVG(1)
2
6 mk-loadavg - Watch MySQL load and take action when it gets too high.
7
9 Execute my_script.sh when Threads_running exceeds 10:
10 mk-loadavg --watch "Status:status:Threads_running:>:10" \
12 --execute-command my_script.sh
13
15 The following section is included to inform users about the potential
16 risks, whether known or unknown, of using this tool. The two main
17 categories of risks are those created by the nature of the tool (e.g.
18 read-only tools vs. read-write tools) and those created by bugs.
19 mk-loadavg merely reads and prints information by default, and is very
21 low-risk. The "--execute-command" option can execute user-specified
22 commands.
23 At the time of this release, we know of no bugs that could cause
25 serious harm to users.
26 The authoritative source for updated information is always the online
28 issue tracking system. Issues that affect this tool will be marked as
29 such. You can see a list of such issues at the following URL:
30 http://www.maatkit.org/bugs/mk-loadavg <http://www.maatkit.org/bugs/mk-
31 loadavg>.
32 See also "BUGS" for more information on filing bugs and getting help.
34
36 mk-loadavg watches a MySQL server and takes action when a defined
37 threshold is exceeded. One or more items can be watched including
38 MySQL status values from SHOW STATUS, SHOW INNODB STATUS and SHOW SLAVE
39 STATUS, the three system load averages from "uptime", and values from
40 "vmstat". Watched items and their threshold values are specified by
41 "--watch". Every item is checked at intervals (see "--interval"). By
42 default, if any one item's check returns true (i.e. its threshold is
43 exceeded), then "--execute-command" is executed. Specifying "--and"
44 requires that every item has exceeded its threshold before
45 "--execute-command" is executed.
46
48 If you specify "--verbose", mk-loadavg prints information to STDOUT
49 about each check for each watched item. Else, it prints nothing and
50 "--execute-command" (if specified) is responsible for logging any
51 information you want.
52
54 Successful exit status is 0. Any other value represents the exit
55 status of the Perl process itself, or of the last forked process that
56 exited if there were multiple servers to monitor.
57
59 --and
60 group: Action
61 Trigger the actions only when all "--watch" items exceed their
63 thresholds.
64 The default is to trigger the actions when any one of the watched
66 items exceeds its threshold. This option requires that all watched
67 items exceed their thresholds before any action is triggered.
68 --ask-pass
70 Prompt for a password when connecting to MySQL.
71 --charset
73 short form: -A; type: string
74 Default character set. If the value is utf8, sets Perl's binmode
76 on STDOUT to utf8, passes the mysql_enable_utf8 option to
77 DBD::mysql, and runs SET NAMES UTF8 after connecting to MySQL. Any
78 other value sets binmode on STDOUT without the utf8 layer, and runs
79 SET NAMES after connecting to MySQL.
80 --config
82 type: Array
83 Read this comma-separated list of config files; if specified, this
85 must be the first option on the command line.
86 --daemonize
88 Fork to the background and detach from the shell. POSIX operating
89 systems only.
90 --database
92 short form: -D; type: string
93 Database to use.
95 --defaults-file
97 short form: -F; type: string
98 Only read mysql options from the given file. You must give an
100 absolute pathname.
101 --execute-command
103 type: string; group: Action
104 Execute this command when watched items exceed their threshold
106 values
107 This command will be executed every time a "--watch" item (or all
109 items if "--and" is specified) exceeds its threshold. For example,
110 if you specify "--watch "Server:vmstat:swpd:":0">, then this
111 command will be executed when the server begins to swap and it will
112 be executed again at each "--interval" so long as the server is
113 still swapping.
114 After the command is executed, mk-loadavg has no control over it,
116 so it is responsible for its own info gathering, logging, interval,
117 etc. Since the command is spawned from mk-loadavg, its STDOUT,
118 STDERR and STDIN are closed so it doesn't interfere with mk-
119 loadavg. Therefore, the command must redirect its output to files
120 or some other destination. For example, if you specify
121 "--execute-command 'echo Hello'", you will not see "Hello" printed
122 anywhere (neither to screen nor "--log") because STDOUT is closed
123 for the command.
124 No information from mk-loadavg is passed to the command.
126 See also "--and".
128 --help
130 Show help and exit.
131 --host
133 short form: -h; type: string
134 Connect to host.
136 --interval
138 type: time; default: 60s; group: Watch
139 How long to sleep between each check.
141 --log
143 type: string
144 Print all output to this file when daemonized.
146 Output from "--execute-command" is not printed to this file.
148 --password
150 short form: -p; type: string
151 Password to use when connecting.
153 --pid
155 type: string
156 Create the given PID file when daemonized. The file contains the
158 process ID of the daemonized instance. The PID file is removed
159 when the daemonized instance exits. The program checks for the
160 existence of the PID file when starting; if it exists and the
161 process with the matching PID exists, the program exits.
162 --port
164 short form: -P; type: int
165 Port number to use for connection.
167 --run-time
169 type: time
170 Time to run before exiting.
172 Causes "mk-loadavg" to stop after the specified time has elapsed.
174 Optional suffix: s=seconds, m=minutes, h=hours, d=days; if no
175 suffix, s is used.
176 --sentinel
178 type: string; default: /tmp/mk-loadavg-sentinel
179 Exit if this file exists.
181 --set-vars
183 type: string; default: wait_timeout=10000
184 Set these MySQL variables. Immediately after connecting to MySQL,
186 this string will be appended to SET and executed.
187 --socket
189 short form: -S; type: string
190 Socket file to use for connection.
192 --stop
194 Stop running instances by creating the "--sentinel" file.
195 --user
197 short form: -u; type: string
198 User for login if not current user.
200 --verbose
202 short form: -v
203 Print information to STDOUT about what is being done.
205 This can be used as a heartbeat to see that mk-loadavg is still
207 properly watching all its values. If "--log" is specified, this
208 information will be printed to that file instead.
209 --version
211 Show version and exit.
212 --vmstat
214 type: string; default: vmstat 1 2; group: Watch
215 vmstat command for "--watch" Server:vmstat:...
217 The vmstat output should look like:
219 procs -----------memory---------- ---swap-- -----io---- -system-- ----cpu----
221 r b swpd free buff cache si so bi bo in cs us sy id wa
222 0 0 0 590380 143756 571852 0 0 6 9 228 340 4 1 94 1
223 0 0 0 590400 143764 571852 0 0 0 28 751 818 4 2 90 3
224 The second line from the top needs to be column headers for
226 subsequent lines. Values are taken from the last line.
227 The default, "vmstat 1 2", gets current values. Running just
229 "vmstat" would get average values since last reboot.
230 --wait
232 type: time; default: 60s
233 Wait this long to reconnect to MySQL.
235 If the MySQL server goes away between "--interval" checks, mk-
237 loadavg will attempt to reconnect to MySQL forever, sleeping this
238 amount of time in between attempts.
239 --watch
241 type: string; group: Watch
242 A comma-separated list of watched items and their thresholds
244 (required).
245 Each watched item is string of arguments separated by colons (like
247 arg:arg). Each argument defines the watch item: what particular
248 value is watched and how to compare the current value to a
249 threshold value (N). Multiple watched items can be given by
250 separating them with a comma, and the same watched item can be
251 given multiple times (but, of course, it only makes sense to do
252 this if the comparison and/or threshold values are differnt).
253 The first argument is the most important and is case-sensitive. It
255 defines the module responsible for watching the value. For
256 example,
257 --watch Status:...
259 causes the WatchStatus module to be loaded. The second and
261 subsequent arguments are passed to the WatchStatus module which
262 parses them. Each watch module requires different arguments. The
263 watch modules included in mk-loadavg and what arguments they
264 require are listed below.
265 This is a common error when specifying "--watch" on the commnad
267 line:
268 mk-loadavg --watch Server:vmstat:swpd:>:0
270 Failed to load --watch WatchServer: Error parsing parameters vmstat:swpd:: No comparison parameter; expected >, < or = at ./mk-loadavg line 3100.
272 The "--watch" values need to be quoted:
274 mk-loadavg --watch "Server:vmstat:swpd:>:0"
276 Status
278 Watch SHOW STATUS, SHOW INNODB STATUS, and SHOW SLAVE STATUS
279 values. The value argument is case-sensitive.
280 --watch Status:[status|innodb|slave]:value:[><=]:N
282 Examples:
284 --watch "Status:status:Threads_connected:>:16"
286 --watch "Status:innodb:Innodb_buffer_pool_hit_rate:<:0.98"
287 --watch "Status:slave:Seconds_behind_master:>:300"
288 You can easily see what values are available for SHOW STATUS
290 and SHOW SLAVE STATUS, but the values for SHOW INNODB STATUS
291 are not apparent. Some common values are:
292 Innodb_buffer_pool_hit_rate
294 Innodb_buffer_pool_pages_created_sec
295 Innodb_buffer_pool_pages_dirty
296 Innodb_buffer_pool_pages_read_sec
297 Innodb_buffer_pool_pages_written_sec
298 Innodb_buffer_pool_pending_data_writes
299 Innodb_buffer_pool_pending_dirty_writes
300 Innodb_buffer_pool_pending_fsyncs
301 Innodb_buffer_pool_pending_reads
302 Innodb_buffer_pool_pending_single_writes
303 Innodb_common_memory_allocated
304 Innodb_data_fsyncs_sec
305 Innodb_data_pending_fsyncs
306 Innodb_data_pending_preads
307 Innodb_data_pending_pwrites
308 Innodb_data_reads_sec
309 Innodb_data_writes_sec
310 Innodb_insert_buffer_pending_reads
311 Innodb_rows_read_sec
312 Innodb_rows_updated_sec
313 lock_wait_time
314 mysql_tables_locked
315 mysql_tables_used
316 row_locks
317 io_avg_wait
318 io_wait
319 max_io_wait
320 Several of those values can appear multiple times in the SHOW
322 INNODB STATUS output. The value used for comparison is always
323 the higest value. So the value for io_wait is the highest
324 io_wait value for all the IO threads.
325 Processlist
327 Watch aggregated SHOW PROCESSLIST values.
328 --watch Processlist:[db|user|host|state|command]:value:[count|time]:[><=]:N
330 Examples:
332 --watch "Processlist:state:Locked:count:>:5"
334 --watch "Processlist:command:Query:time:<:1"
335 Server
337 Watch server values.
338 --watch Server:loadavg:[1|5|15]:[><=]:N
340 --watch Server:vmstat:[r|b|swpd|free|buff|cache|si|so|bi|bo|in|cs|us|sy|id|wa]:[><=]:N
341 Examples:
343 --watch "Server:loadavg:5:>:4.00"
345 --watch "Server:vmstat:swpd:>:0"
346 --watch "Server:vmstat:free:=:0"
347 See "--vmstat".
349
351 These DSN options are used to create a DSN. Each option is given like
352 "option=value". The options are case-sensitive, so P and p are not the
353 same option. There cannot be whitespace before or after the "=" and if
354 the value contains whitespace it must be quoted. DSN options are
355 comma-separated. See the maatkit manpage for full details.
356 · A
358 dsn: charset; copy: yes
360 Default character set.
362 · D
364 dsn: database; copy: yes
366 Default database.
368 · F
370 dsn: mysql_read_default_file; copy: yes
372 Only read default options from the given file
374 · h
376 dsn: host; copy: yes
378 Connect to host.
380 · p
382 dsn: password; copy: yes
384 Password to use when connecting.
386 · P
388 dsn: port; copy: yes
390 Port number to use for connection.
392 · S
394 dsn: mysql_socket; copy: yes
396 Socket file to use for connection.
398 · u
400 dsn: user; copy: yes
402 User for login if not current user.
404
406 You can download Maatkit from Google Code at
407 <http://code.google.com/p/maatkit/>, or you can get any of the tools
408 easily with a command like the following:
409 wget http://www.maatkit.org/get/toolname
411 or
412 wget http://www.maatkit.org/trunk/toolname
413 Where "toolname" can be replaced with the name (or fragment of a name)
415 of any of the Maatkit tools. Once downloaded, they're ready to run; no
416 installation is needed. The first URL gets the latest released version
417 of the tool, and the second gets the latest trunk code from Subversion.
418
420 The environment variable "MKDEBUG" enables verbose debugging output in
421 all of the Maatkit tools:
422 MKDEBUG=1 mk-....
424
426 You need Perl, DBI, DBD::mysql, and some core packages that ought to be
427 installed in any reasonably new version of Perl.
428
430 For a list of known bugs see http://www.maatkit.org/bugs/mk-loadavg
431 <http://www.maatkit.org/bugs/mk-loadavg>.
432 Please use Google Code Issues and Groups to report bugs or request
434 support: <http://code.google.com/p/maatkit/>. You can also join
435 #maatkit on Freenode to discuss Maatkit.
436 Please include the complete command-line used to reproduce the problem
438 you are seeing, the version of all MySQL servers involved, the complete
439 output of the tool when run with "--version", and if possible,
440 debugging output produced by running with the "MKDEBUG=1" environment
441 variable.
442
444 This program is copyright 2008-2010 Baron Schwartz. Feedback and
445 improvements are welcome.
446 THIS PROGRAM IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
448 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
449 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
450 This program is free software; you can redistribute it and/or modify it
452 under the terms of the GNU General Public License as published by the
453 Free Software Foundation, version 2; OR the Perl Artistic License. On
454 UNIX and similar systems, you can issue `man perlgpl' or `man
455 perlartistic' to read these licenses.
456 You should have received a copy of the GNU General Public License along
458 with this program; if not, write to the Free Software Foundation, Inc.,
459 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.
460
462 Baron Schwartz, Daniel Nichter
463
465 This tool is part of Maatkit, a toolkit for power users of MySQL.
466 Maatkit was created by Baron Schwartz; Baron and Daniel Nichter are the
467 primary code contributors. Both are employed by Percona. Financial
468 support for Maatkit development is primarily provided by Percona and
469 its clients.
470
472 This manual page documents Ver 0.9.6 Distrib 6839 $Revision: 6831 $.
473perl v5.12.1 2010-08-01 MK-LOADAVG(1)