<?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>
       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>.
      </entry>
      <entry>Since 1.0.0.</entry>
     </row>
     <row>
      <entry>
       <literal>use_master</literal>
      </entry>
      <entry>
       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>.
      </entry>
      <entry>Since 1.0.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_failed</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_failed</literal> + 
       <literal>lazy_connections_slave_failed</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_failed</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_failed</literal> + 
       <literal>lazy_connections_master_failed</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_failed</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_failed</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.collect_statistics = %d\n", ini_get("mysqlnd_ms.collect_statistics"));
var_dump(mysqlnd_ms_get_stats());
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
mysqlnd_ms.collect_statistics = 0
array(13) {
  ["use_slave"]=>
  string(1) "0"
  ["use_master"]=>
  string(1) "0"
  ["use_slave_forced"]=>
  string(1) "0"
  ["use_master_forced"]=>
  string(1) "0"
  ["use_last_used_forced"]=>
  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
-->