diff --git a/reference/mysqlnd_ms/concepts.xml b/reference/mysqlnd_ms/concepts.xml
index f544ac3246..2ef44f16fd 100755
--- a/reference/mysqlnd_ms/concepts.xml
+++ b/reference/mysqlnd_ms/concepts.xml
@@ -803,7 +803,8 @@ version = 5.6.2-m5-log
Selection filter:
user,
- quality-of-service (qos).
+ user_multi,
+ quality_of_service.
diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml
index 30a0446cdf..e30236135f 100755
--- a/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml
+++ b/reference/mysqlnd_ms/functions/mysqlnd-ms-get-stats.xml
@@ -447,6 +447,9 @@ array(20) {
mysqlnd_ms.enable
+
+ Monitoring
+
diff --git a/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml b/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml
index 7c52978b40..2eaa5ab353 100644
--- a/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml
+++ b/reference/mysqlnd_ms/functions/mysqlnd-ms-set-qos.xml
@@ -187,6 +187,9 @@ if (!mysqlnd_ms_set_qos($mysqli, MYSQLND_MS_QOS_CONSISTENCY_EVENTUAL))
mysqlnd_ms_get_last_gtid
+
+ Service level and consistency concept
+
Filter concept
diff --git a/reference/mysqlnd_ms/setup.xml b/reference/mysqlnd_ms/setup.xml
index ed67d1f21c..19382139ef 100755
--- a/reference/mysqlnd_ms/setup.xml
+++ b/reference/mysqlnd_ms/setup.xml
@@ -1117,6 +1117,88 @@ User has connected to 'myapp'...
+
+
+ Filter: user_multi
+ object
+
+
+
+ The user_multi differs from the user
+ only in one aspect. Otherwise, their syntax is identical.
+ The user filter must pick
+ and return exactly one node for statement execution. A filter chain
+ usually ends with a filter that emits only one node. The filter chain
+ shall reduce the list of candidates for statement execution down to
+ one. This, only one node left, is the case after the user
+ filter has been run.
+
+
+ The user_multi filter is a multi filter. It returns a
+ list of slave and a list of master servers. This list needs further filtering
+ to identify exactly one node for statement execution. A multi filter is typically
+ placed at the top of the filter chain. The quality_of_service
+ filter is another example of a multi filter.
+
+
+ The return value of the callback set for user_multi must
+ be an an array with two elements. The first element holds a list of selected master
+ servers. The second element contains a list of selected slave servers. The
+ lists shall contain the keys of the slave and master servers as found in
+ the slave and master lists passed to the callback. The below example returns
+ random master and slave lists extracted from the functions input.
+
+
+
+ Returning random masters and slaves
+
+ $value) {
+ if (mt_rand(0, 2) > 1)
+ $picked_masters[] = $key;
+ }
+ $picked_slaves = array()
+ foreach ($slaves as $key => $value) {
+ if (mt_rand(0, 2) > 1)
+ $picked_slaves[] = $key;
+ }
+ return array($picked_masters, $picked_slaves);
+}
+]]>
+
+
+
+
+ The plugin will issue an
+ error of type E_RECOVERABLE if the callback fails to return
+ a server list. The error may read (mysqlnd_ms) User multi
+ filter callback has not returned a list of servers to use.
+ The callback must return an array in %s on line %d. In case the
+ server list is not empty but has invalid servers key/ids in it, an error
+ of type E_RECOVERABLE will the thrown with an
+ error message like (mysqlnd_ms) User multi filter callback
+ has returned an invalid list of servers to use.
+ Server id is negative in %s on line %d, or similar.
+
+
+ Whether an error is emitted in case of an empty slave or master list
+ depends on the configuration. If an empty master list is returned
+ for a write operation, it is likely that the plugin will emit a
+ warning that may read (mysqlnd_ms) Couldn't find the appropriate
+ master connection. 0 masters to choose from. Something is wrong in %s on line %d.
+ Typically a follow up error of type E_ERROR will happen.
+ In case of a read operation and an empty slave list the behviour depends
+ on the fail over configuration. If fail over to master is enabled, no
+ error should appear. If fail over to master is deactivated the plugin will
+ emit a warning that may read (mysqlnd_ms) Couldn't find the appropriate
+ slave connection. 0 slaves to choose from. Something is wrong in %s on line %d.
+
+
+
Filter: quality_of_service
@@ -2064,6 +2146,110 @@ mysqlnd.debug=d:t:x:O,/tmp/mysqlnd.trace
+
+ Monitoring
+
+ 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.
+
+
+ Writing a trace log is a slow operation. If using an external PHP debugging tool,
+ please refer to the vendors manual about its perfomance 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.
+
+
+ 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 mysqlnd_ms_get_stats
+ is used to access the statistics. Please, see the functions description for a list
+ of available statistics.
+
+
+ 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.
+
+
+
+ Verify plugin activity in a non-threaded deployment model
+
+
+
+
+query("SELECT 'Read request' FROM DUAL")) {
+ var_dump($res->fetch_all());
+}
+$stats_after = mysqlnd_ms_get_stats();
+if ($stats_after['use_slave'] <= $stats_before['use_slave']) {
+ echo "According to the statistics the read request has not been run on a slave!";
+}
+?>
+]]>
+
+
+
+
+ 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.
+
+
+ Utilizing PHPs register_shutdown_function function or the
+ auto_append_file 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.
+
+
+
+ Recording statistics during shutdown
+
+
+
+
+
+]]>
+
+
+
+
+