<?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 and all storage handler. 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 &null; 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="1*"/> <colspec colwidth="7*"/> <colspec colwidth="2*"/> <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 statistics 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 statement, which 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 statement, which 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 executed 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 executed 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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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-v2.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 statements redirected to the master while <link linkend="ini.mysqlnd-ms-plugin-config-v2.trx-stickiness"><literal>trx_stickiness=master</literal></link> and <literal>autocommit</literal> mode is disabled. </entry> <entry>Since 1.0.0.</entry> </row> <row> <entry> <literal>gtid_autocommit_injections_success</literal> </entry> <entry> Number of successful SQL injections in autocommit mode as part of the plugins client-side <link linkend="mysqlnd-ms.gtid">global transaction id emulation</link>. </entry> <entry>Since 1.2.0.</entry> </row> <row> <entry> <literal>gtid_autocommit_injections_failure</literal> </entry> <entry> Number of failed SQL injections in autocommit mode as part of the plugins client-side <link linkend="mysqlnd-ms.gtid">global transaction id emulation</link>. </entry> <entry>Since 1.2.0.</entry> </row> <row> <entry> <literal>gtid_commit_injections_success</literal> </entry> <entry> Number of successful SQL injections in commit mode as part of the plugins client-side <link linkend="mysqlnd-ms.gtid">global transaction id emulation</link>. </entry> <entry>Since 1.2.0.</entry> </row> <row> <entry> <literal>gtid_commit_injections_failure</literal> </entry> <entry> Number of failed SQL injections in commit mode as part of the plugins client-side <link linkend="mysqlnd-ms.gtid">global transaction id emulation</link>. </entry> <entry>Since 1.2.0.</entry> </row> <row> <entry> <literal>gtid_implicit_commit_injections_success</literal> </entry> <entry> Number of successful SQL injections when implicit commit is detected as part of the plugins client-side <link linkend="mysqlnd-ms.gtid">global transaction id emulation</link>. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. Another sequence causing an implicit commit is <literal>begin()</literal>, <literal>query()</literal>, <literal>begin()</literal>. The second call to <literal>begin()</literal> will implicitly commit the transaction started by the first call to <literal>begin()</literal>. <literal>begin()</literal> refers to internal library calls not actual PHP user API calls. </entry> <entry>Since 1.2.0.</entry> </row> <row> <entry> <literal>gtid_implicit_commit_injections_failure</literal> </entry> <entry> Number of failed SQL injections when implicit commit is detected as part of the plugins client-side <link linkend="mysqlnd-ms.gtid">global transaction id emulation</link>. Implicit commit happens, for example, when autocommit has been turned off, a query is executed and autocommit is enabled again. In that case, the statement will be committed by the server and SQL to maintain is injected before the autocommit is re-enabled. </entry> <entry>Since 1.2.0.</entry> </row> <row> <entry> <literal>transient_error_retries</literal> </entry> <entry> How often an operation has been retried when a transient error was detected. See also, <link linkend="ini.mysqlnd-ms-plugin-config-v2.transient_error"><literal>transient_error</literal></link> plugin configuration file setting. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>fabric_sharding_lookup_servers_success</literal> </entry> <entry> Number of successful <literal>sharding.lookup_servers</literal> remote procedure calls to MySQL Fabric. A call is considered successful if the plugin could reach MySQL Fabric and got any reply. The reply itself may or may not be understood by the plugin. Success refers to the network transport only. If the reply was not understood or indicates a valid error condition, <literal>fabric_sharding_lookup_servers_xml_failure</literal> gets incremented. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>fabric_sharding_lookup_servers_failure</literal> </entry> <entry> Number of failed <literal>sharding.lookup_servers</literal> remote procedure calls to MySQL Fabric. A remote procedure call is considered failed if there was a network error in connecting to, writing to or reading from MySQL Fabric. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>fabric_sharding_lookup_servers_time_total</literal> </entry> <entry> Time spent connecting to,writing to and reading from MySQL Fabrich during the <literal>sharding.lookup_servers</literal> remote procedure call. The value is aggregated for all calls. Time is measured in microseconds. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>fabric_sharding_lookup_servers_bytes_total</literal> </entry> <entry> Total number of bytes received from MySQL Fabric in reply to <literal>sharding.lookup_servers</literal> calls. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>fabric_sharding_lookup_servers_xml_failure</literal> </entry> <entry> How often a reply from MySQL Fabric to <literal>sharding.lookup_servers</literal> calls was not understood. Please note, the current experimental implementation does not distinguish between valid errors returned and malformed replies. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_begin</literal> </entry> <entry> How many XA/distributed transactions have been started using <function>mysqlnd_ms_xa_begin</function>. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_commit_success</literal> </entry> <entry> How many XA/distributed transactions have been successfully committed using <function>mysqlnd_ms_xa_commit</function>. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_commit_failure</literal> </entry> <entry> How many XA/distributed transactions failed to commit during <function>mysqlnd_ms_xa_commit</function>. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_rollback_success</literal> </entry> <entry> How many XA/distributed transactions have been successfully rolled back using <function>mysqlnd_ms_xa_rollback</function>. The figure does not include implict rollbacks performed as a result of <function>mysqlnd_ms_xa_commit</function> failure. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_rollback_failure</literal> </entry> <entry> How many XA/distributed transactions could not be rolled back. This includes failures of <function>mysqlnd_ms_xa_rollback</function> but also failured during rollback when closing a connection, if <literal>rollback_on_close</literal> is set. Please, see also <literal>xa_rollback_on_close</literal> below. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_participants</literal> </entry> <entry> Total number of participants in any XA transaction started with <function>mysqlnd_ms_xa_begin</function>. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>xa_rollback_on_close</literal> </entry> <entry> How many XA transactions have been rolled back implicitly when a connection was close and <literal>rollback_on_close</literal> is set. Depending on your coding policies, this may hint a flaw in your code as you may prefer to explicitly clean up resources. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_masters_total</literal> </entry> <entry> Number of master servers (connections) in the internal connection pool. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_slaves_total</literal> </entry> <entry> Number of slave servers (connections) in the internal connection pool. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_masters_active</literal> </entry> <entry> Number of master servers (connections) from the internal connection pool which are currently used for picking a connection. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_slaves_active</literal> </entry> <entry> Number of slave servers (connections) from the internal connection pool which are currently used for picking a connection. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_updates</literal> </entry> <entry> How often the active connection list has been replaced and a new set of master and slave servers had been installed. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_master_reactivated</literal> </entry> <entry> How often a master connection has been reused after being flushed from the active list. </entry> <entry>Since 1.6.0.</entry> </row> <row> <entry> <literal>pool_slave_reactivated</literal> </entry> <entry> How often a slave connection has been reused after being flushed from the active list. </entry> <entry>Since 1.6.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(26) { ["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" ["gtid_autocommit_injections_success"]=> string(1) "0" ["gtid_autocommit_injections_failure"]=> string(1) "0" ["gtid_commit_injections_success"]=> string(1) "0" ["gtid_commit_injections_failure"]=> string(1) "0" ["gtid_implicit_commit_injections_success"]=> string(1) "0" ["gtid_implicit_commit_injections_failure"]=> string(1) "0" ["transient_error_retries"]=> 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> <member> <link linkend="mysqlnd-ms.monitoring">Monitoring</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 -->