<?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 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>
    </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"
}
]]>
    </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
-->