mirror of
https://github.com/sigmasternchen/php-doc-en
synced 2025-03-21 03:18:55 +00:00
174c6269a5
git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@317392 c90b9560-bf6c-de11-be94-00142212c4b1
475 lines
16 KiB
XML
Executable file
475 lines
16 KiB
XML
Executable file
<?xml version="1.0" encoding="utf-8"?>
|
|
<!-- $Revision$ -->
|
|
|
|
<refentry xml:id="function.mysqlnd-ms-get-stats" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
|
|
<refnamediv>
|
|
<refname>mysqlnd_ms_get_stats</refname>
|
|
<refpurpose>Returns query distribution and connection statistics</refpurpose>
|
|
</refnamediv>
|
|
|
|
<refsect1 role="description">
|
|
&reftitle.description;
|
|
<methodsynopsis>
|
|
<type>array</type>
|
|
<methodname>mysqlnd_ms_get_stats</methodname>
|
|
<void />
|
|
</methodsynopsis>
|
|
<para>
|
|
Returns an array of statistics collected by the replication
|
|
and load balancing plugin.
|
|
</para>
|
|
<para>
|
|
The PHP configuration setting
|
|
<literal><link linkend="ini.mysqlnd-ms.collect_statistics">mysqlnd_ms.collect_statistics</link></literal>
|
|
controls the collection of statistics. The collection of statistics
|
|
is disabled by default for performance reasons.
|
|
</para>
|
|
<para>
|
|
The scope of the statistics is the
|
|
<literal>PHP</literal> process.
|
|
Depending on your deployment model a
|
|
<literal>PHP</literal> process may handle one or multiple requests.
|
|
</para>
|
|
<para>
|
|
Statistics are aggregated for all connections. It is not possible
|
|
to tell how much queries originating from
|
|
<literal>mysqli</literal>,
|
|
<literal>PDO_MySQL</literal> or
|
|
<literal>mysql</literal> API calls have
|
|
contributed to the aggregated data values.
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="parameters">
|
|
&reftitle.parameters;
|
|
&no.function.parameters;
|
|
</refsect1>
|
|
|
|
<refsect1 role="returnvalues">
|
|
&reftitle.returnvalues;
|
|
<para>
|
|
Returns <literal>NULL</literal> if
|
|
the PHP configuration directive
|
|
<link linkend="ini.mysqlnd-ms.enable"><literal>mysqlnd_ms.enable</literal></link>
|
|
has disabled the plugin. Otherwise, returns array of statistics.
|
|
</para>
|
|
<para>
|
|
Array of statistics
|
|
</para>
|
|
<informaltable>
|
|
<tgroup cols="3">
|
|
<colspec colwidth="10%"/>
|
|
<colspec colwidth="70%"/>
|
|
<colspec colwidth="20%"/>
|
|
<thead>
|
|
<row>
|
|
<entry>Statistic</entry>
|
|
<entry>Description</entry>
|
|
<entry>Version</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>
|
|
<literal>use_slave</literal>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
The semantics of this statistic has changed between 1.0.1 - 1.1.0.
|
|
</para>
|
|
<para>
|
|
The meaning for version 1.0.1 is as follows.
|
|
Number of statements considered as read-only by the built-in query analyzer.
|
|
Neither statements which begin with a SQL hint to force
|
|
use of slave nor statements directed to a slave by an user-defined
|
|
callback are included. The total number of statements sent to the slaves is
|
|
<literal>use_slave</literal> + <literal>use_slave_sql_hint</literal> +
|
|
<literal>use_slave_callback</literal>.
|
|
</para>
|
|
<para>
|
|
PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The
|
|
statictics is now set by the internal load balancing filter. With
|
|
version 1.1.0 the load balancing filter is always the last in the
|
|
filter chain, if used. In future versions a load balancing filter may be
|
|
followed by other filters causing another change in the meaning of
|
|
the statistic. If, in the future, a load balancing filter is followed
|
|
by another filter it is no longer guaranteed that the satement, whichs
|
|
increments <literal>use_slave</literal>, will be executed on the slaves.
|
|
</para>
|
|
<para>
|
|
The meaning for version 1.1.0 is as follows. Number of statements
|
|
sent to the slaves. Statements directed to a slave by the user filter
|
|
(an user-defined callback) are not included. The latter are counted by
|
|
<literal>use_slave_callback</literal>.
|
|
</para>
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_master</literal>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
The semantics of this statistic has changed between 1.0.1 - 1.1.0.
|
|
</para>
|
|
<para>
|
|
The meaning for version 1.0.1 is as follows.
|
|
Number of statements not considered as read-only by the built-in query analyzer.
|
|
Neither statements which begin with a SQL hint to force
|
|
use of master nor statements directed to a master by an user-defined
|
|
callback are included. The total number of statements sent to the master is
|
|
<literal>use_master</literal> + <literal>use_master_sql_hint</literal> +
|
|
<literal>use_master_callback</literal>.
|
|
</para>
|
|
<para>
|
|
PECL/mysqlnd_ms 1.1.0 introduces a new concept of chained filters. The
|
|
statictics is now set by the internal load balancing filter. With
|
|
version 1.1.0 the load balancing filter is always the last in the
|
|
filter chain, if used. In future versions a load balancing filter may be
|
|
followed by other filters causing another change in the meaning of
|
|
the statistic. If, in the future, a load balancing filter is followed
|
|
by another filter it is no longer guaranteed that the satement, whichs
|
|
increments <literal>use_master</literal>, will be executed on the slaves.
|
|
</para>
|
|
<para>
|
|
The meaning for version 1.1.0 is as follows. Number of statements
|
|
sent to the masters. Statements directed to a master by the user filter
|
|
(an user-defined callback) are not included. The latter are counted by
|
|
<literal>use_master_callback</literal>.
|
|
</para>
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_slave_guess</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements the built-in query analyzer recommends sending to
|
|
a slave because they contain no SQL hint to force use of a
|
|
certain server. The recommendation may be overruled in the following.
|
|
It is not guaranteed whether the statement will be excuted on a slave
|
|
or not. This is how often the internal <literal>is_select</literal>
|
|
function has guessed that a slave shall be used. Please, see also the
|
|
user space function <function>mysqlnd_ms_query_is_select</function>.
|
|
</entry>
|
|
<entry>Since 1.1.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_master_guess</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements the built-in query analyzer recommends sending to
|
|
a master because they contain no SQL hint to force use of a
|
|
certain server. The recommendation may be overruled in the following.
|
|
It is not guaranteed whether the statement will be excuted on a slave
|
|
or not. This is how often the internal <literal>is_select</literal>
|
|
function has guessed that a master shall be used. Please, see also the
|
|
user space function <function>mysqlnd_ms_query_is_select</function>.
|
|
</entry>
|
|
<entry>Since 1.1.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_slave_sql_hint</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements sent to a slave because statement begins with
|
|
the SQL hint to force use of slave.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_master_sql_hint</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements sent to a master because statement begins with
|
|
the SQL hint to force use of master.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_last_used_sql_hint</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements sent to server which has run the previous statement,
|
|
because statement begins with the SQL hint to force use of previously
|
|
used server.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_slave_callback</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements sent to a slave because an user-defined callback
|
|
has chosen a slave server for statement execution.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>use_master_callback</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statements sent to a master because an user-defined callback
|
|
has chosen a master server for statement execution.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>non_lazy_connections_slave_success</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of successfully opened slave connections from
|
|
configurations not using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
The total number of successfully opened slave connections
|
|
is <literal>non_lazy_connections_slave_success</literal> +
|
|
<literal>lazy_connections_slave_success</literal>
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>non_lazy_connections_slave_failure</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of failed slave connection attempts from
|
|
configurations not using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
The total number of failed slave connection attempts
|
|
is <literal>non_lazy_connections_slave_failure</literal> +
|
|
<literal>lazy_connections_slave_failure</literal>
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>non_lazy_connections_master_success</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of successfully opened master connections from
|
|
configurations not using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
The total number of successfully opened master connections
|
|
is <literal>non_lazy_connections_master_success</literal> +
|
|
<literal>lazy_connections_master_success</literal>
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>non_lazy_connections_master_failure</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of failed master connection attempts from
|
|
configurations not using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
The total number of failed master connection attempts
|
|
is <literal>non_lazy_connections_master_failure</literal> +
|
|
<literal>lazy_connections_master_failure</literal>
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>lazy_connections_slave_success</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of successfully opened slave connections from
|
|
configurations using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>lazy_connections_slave_failure</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of failed slave connection attempts from
|
|
configurations using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>lazy_connections_master_success</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of successfully opened master connections from
|
|
configurations using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>lazy_connections_master_failure</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of failed master connection attempts from
|
|
configurations using
|
|
<literal><link linkend="ini.mysqlnd-ms-plugin-config.lazy_connections">lazy connections</link></literal>.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>trx_autocommit_on</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of <literal>autocommit</literal> mode activations via API calls.
|
|
This figure may be used to monitor activity related to the plugin configuration
|
|
setting
|
|
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness</literal></link>.
|
|
If, for example, you want to know if a certain API call invokes the
|
|
<literal>mysqlnd</literal> library function <literal>trx_autocommit()</literal>,
|
|
which is a requirement for
|
|
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness</literal></link>,
|
|
you may call the user API function in question and check if the
|
|
statistic has changed. The statistic is modified only by the
|
|
plugins internal subclassed <literal>trx_autocommit()</literal>
|
|
method.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>trx_autocommit_off</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of <literal>autocommit</literal> mode deactivations via API calls.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<literal>trx_master_forced</literal>
|
|
</entry>
|
|
<entry>
|
|
Number of statemens redirected to the master while
|
|
<link linkend="ini.mysqlnd-ms-plugin-config.trx_stickiness"><literal>trx_stickiness=master</literal></link>
|
|
and <literal>autocommit</literal> mode is disabled.
|
|
</entry>
|
|
<entry>Since 1.0.0.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</refsect1>
|
|
|
|
<refsect1 role="examples">
|
|
&reftitle.examples;
|
|
<para>
|
|
<example>
|
|
<title><function>mysqlnd_ms_get_stats</function> example</title>
|
|
<programlisting role="php">
|
|
<![CDATA[
|
|
<?php
|
|
printf("mysqlnd_ms.enable = %d\n", ini_get("mysqlnd_ms.enable"));
|
|
printf("mysqlnd_ms.collect_statistics = %d\n", ini_get("mysqlnd_ms.collect_statistics"));
|
|
var_dump(mysqlnd_ms_get_stats());
|
|
?>
|
|
]]>
|
|
</programlisting>
|
|
&example.outputs;
|
|
<screen>
|
|
<![CDATA[
|
|
mysqlnd_ms.enable = 1
|
|
mysqlnd_ms.collect_statistics = 1
|
|
array(20) {
|
|
["use_slave"]=>
|
|
string(1) "0"
|
|
["use_master"]=>
|
|
string(1) "0"
|
|
["use_slave_guess"]=>
|
|
string(1) "0"
|
|
["use_master_guess"]=>
|
|
string(1) "0"
|
|
["use_slave_sql_hint"]=>
|
|
string(1) "0"
|
|
["use_master_sql_hint"]=>
|
|
string(1) "0"
|
|
["use_last_used_sql_hint"]=>
|
|
string(1) "0"
|
|
["use_slave_callback"]=>
|
|
string(1) "0"
|
|
["use_master_callback"]=>
|
|
string(1) "0"
|
|
["non_lazy_connections_slave_success"]=>
|
|
string(1) "0"
|
|
["non_lazy_connections_slave_failure"]=>
|
|
string(1) "0"
|
|
["non_lazy_connections_master_success"]=>
|
|
string(1) "0"
|
|
["non_lazy_connections_master_failure"]=>
|
|
string(1) "0"
|
|
["lazy_connections_slave_success"]=>
|
|
string(1) "0"
|
|
["lazy_connections_slave_failure"]=>
|
|
string(1) "0"
|
|
["lazy_connections_master_success"]=>
|
|
string(1) "0"
|
|
["lazy_connections_master_failure"]=>
|
|
string(1) "0"
|
|
["trx_autocommit_on"]=>
|
|
string(1) "0"
|
|
["trx_autocommit_off"]=>
|
|
string(1) "0"
|
|
["trx_master_forced"]=>
|
|
string(1) "0"
|
|
}
|
|
]]>
|
|
</screen>
|
|
</example>
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="seealso">
|
|
&reftitle.seealso;
|
|
<para>
|
|
<simplelist>
|
|
<member>
|
|
<link linkend="mysqlnd-ms.configuration">Runtime configuration</link>
|
|
</member>
|
|
<member>
|
|
<link linkend="ini.mysqlnd-ms.collect_statistics">mysqlnd_ms.collect_statistics</link>
|
|
</member>
|
|
<member>
|
|
<link linkend="ini.mysqlnd-ms.enable">mysqlnd_ms.enable</link>
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
</refsect1>
|
|
|
|
</refentry>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
sgml-omittag:t
|
|
sgml-shorttag:t
|
|
sgml-minimize-attributes:nil
|
|
sgml-always-quote-attributes:t
|
|
sgml-indent-step:1
|
|
sgml-indent-data:t
|
|
indent-tabs-mode:nil
|
|
sgml-parent-document:nil
|
|
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
|
|
sgml-exposed-tags:nil
|
|
sgml-local-catalogs:nil
|
|
sgml-local-ecat-files:nil
|
|
End:
|
|
vim600: syn=xml fen fdm=syntax fdl=2 si
|
|
vim: et tw=78 syn=sgml
|
|
vi: ts=1 sw=1
|
|
-->
|