<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Monitoring</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.debugging.html">Debugging and Tracing</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.constants.html">Predefined Constants</a></div>
<div class="up"><a href="mysqlnd-ms.setup.html">Installing/Configuring</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqlnd-ms.monitoring" class="section">
<h2 class="title">Monitoring</h2>
<p class="para">
Plugin activity can be monitored using the mysqlnd trace log,
mysqlnd statistics, mysqlnd_ms plugin statistics and external PHP debugging tools.
Use of the trace log should be limited to debugging. It is recommended
to use the plugins statistics for monitoring.
</p>
<p class="para">
Writing a trace log is a slow operation. If using an external PHP debugging tool,
please refer to the vendors manual about its performance impact and the
type of information collected. In many cases, external debugging tools will
provide call stacks. Often, a call stack or a trace log is more difficult to interpret
than the statistics provided by the plugin.
</p>
<p class="para">
Plugin statistics tell how often which kind of cluster node has been used (slave or master),
why the node was used, if lazy connections have been used and if global transaction
ID injection has been performed. The monitoring information provided enables
user to verify plugin decisions and to plan their cluster resources based on usage pattern.
The function <span class="function"><a href="function.mysqlnd-ms-get-stats.html" class="function">mysqlnd_ms_get_stats()</a></span>
is used to access the statistics. Please, see the functions description for a list
of available statistics.
</p>
<p class="para">
Statistics are collected on a per PHP process basis. Their scope is a PHP process.
Depending on the PHP deployment model a process may serve one or multiple web requests.
If using CGI model, a PHP process serves one web request. If using FastCGI or
pre-fork web server models, a PHP process usually serves multiple web requests.
The same is the case with a threaded web server. Please, note that threads running
in parallel can update the statistics in parallel. Thus, if using a threaded PHP
deployment model, statistics can be changed by more than one script at a time. A
script cannot rely on the fact that it sees only its own changes to statistics.
</p>
<p class="para">
<div class="example" id="example-1835">
<p><strong>Example #1 Verify plugin activity in a non-threaded deployment model</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">mysqlnd_ms.enable=1
mysqlnd_ms.collect_statistics=1</pre>
</div>
</div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #FF8000">/* Load balanced following "myapp" section rules from the plugins config file (not shown) */<br /></span><span style="color: #0000BB">$mysqli </span><span style="color: #007700">= new </span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"myapp"</span><span style="color: #007700">, </span><span style="color: #DD0000">"username"</span><span style="color: #007700">, </span><span style="color: #DD0000">"password"</span><span style="color: #007700">, </span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">mysqli_connect_errno</span><span style="color: #007700">())<br /> </span><span style="color: #FF8000">/* Of course, your error handling is nicer... */<br /> </span><span style="color: #007700">die(</span><span style="color: #0000BB">sprintf</span><span style="color: #007700">(</span><span style="color: #DD0000">"[%d] %s\n"</span><span style="color: #007700">, </span><span style="color: #0000BB">mysqli_connect_errno</span><span style="color: #007700">(), </span><span style="color: #0000BB">mysqli_connect_error</span><span style="color: #007700">()));<br /><br /></span><span style="color: #0000BB">$stats_before </span><span style="color: #007700">= </span><span style="color: #0000BB">mysqlnd_ms_get_stats</span><span style="color: #007700">();<br />if (</span><span style="color: #0000BB">$res </span><span style="color: #007700">= </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">"SELECT 'Read request' FROM DUAL"</span><span style="color: #007700">)) {<br /> </span><span style="color: #0000BB">var_dump</span><span style="color: #007700">(</span><span style="color: #0000BB">$res</span><span style="color: #007700">-></span><span style="color: #0000BB">fetch_all</span><span style="color: #007700">());<br />}<br /></span><span style="color: #0000BB">$stats_after </span><span style="color: #007700">= </span><span style="color: #0000BB">mysqlnd_ms_get_stats</span><span style="color: #007700">();<br />if (</span><span style="color: #0000BB">$stats_after</span><span style="color: #007700">[</span><span style="color: #DD0000">'use_slave'</span><span style="color: #007700">] <= </span><span style="color: #0000BB">$stats_before</span><span style="color: #007700">[</span><span style="color: #DD0000">'use_slave'</span><span style="color: #007700">]) {<br /> echo </span><span style="color: #DD0000">"According to the statistics the read request has not been run on a slave!"</span><span style="color: #007700">;<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Statistics are aggregated for all plugin activities and all connections handled by
the plugin. It is not possible to tell how much a certain connection handle has
contributed to the overall statistics.
</p>
<p class="para">
Utilizing PHPs <span class="function"><a href="function.register-shutdown-function.html" class="function">register_shutdown_function()</a></span> function or the
<em>auto_append_file</em> PHP configuration directive it is
easily possible to dump statistics into, for example, a log file when a script
finishes. Instead of using a log file it is also possible to send the statistics
to an external monitoring tool for recording and display.
</p>
<p class="para">
<div class="example" id="example-1836">
<p><strong>Example #2 Recording statistics during shutdown</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">mysqlnd_ms.enable=1
mysqlnd_ms.collect_statistics=1
error_log=/tmp/php_errors.log</pre>
</div>
</div>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">function </span><span style="color: #0000BB">check_stats</span><span style="color: #007700">() {<br /> </span><span style="color: #0000BB">$msg </span><span style="color: #007700">= </span><span style="color: #0000BB">str_repeat</span><span style="color: #007700">(</span><span style="color: #DD0000">"-"</span><span style="color: #007700">, </span><span style="color: #0000BB">80</span><span style="color: #007700">) . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$msg </span><span style="color: #007700">.= </span><span style="color: #0000BB">var_export</span><span style="color: #007700">(</span><span style="color: #0000BB">mysqlnd_ms_get_stats</span><span style="color: #007700">(), </span><span style="color: #0000BB">true</span><span style="color: #007700">) . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">$msg </span><span style="color: #007700">.= </span><span style="color: #0000BB">str_repeat</span><span style="color: #007700">(</span><span style="color: #DD0000">"-"</span><span style="color: #007700">, </span><span style="color: #0000BB">80</span><span style="color: #007700">) . </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /> </span><span style="color: #0000BB">error_log</span><span style="color: #007700">(</span><span style="color: #0000BB">$msg</span><span style="color: #007700">);<br />}<br /></span><span style="color: #0000BB">register_shutdown_function</span><span style="color: #007700">(</span><span style="color: #DD0000">"check_stats"</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqlnd-ms.debugging.html">Debugging and Tracing</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqlnd-ms.constants.html">Predefined Constants</a></div>
<div class="up"><a href="mysqlnd-ms.setup.html">Installing/Configuring</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
