<?xml version="1.0" encoding="utf-8"?>
<chapter xml:id="mysqlnd.stats" xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude">
 <title>Statistics</title>

 <para>
  MySQL Native Driver contains support for gathering statistics on the
  communication between the client and the server. The statistics
  gathered are of two main types:
  <itemizedlist>
   <listitem>
    <simpara>Client statistics</simpara>
   </listitem>
   <listitem>
    <simpara>Connection statistics</simpara>
   </listitem>
  </itemizedlist>
 </para>
 <para>
  When using the <link linkend="book.mysqli">mysqli</link> extension,
  these statistics can be obtained through two API calls:
  <itemizedlist>
   <listitem>
    <simpara><function>mysqli_get_client_stats</function></simpara>
   </listitem>
   <listitem>
    <simpara><function>mysqli_get_connection_stats</function></simpara>
   </listitem>
  </itemizedlist>
 </para>

 <note>
  <simpara>
   Statistics are aggregated among all extensions that use the MySQL Native
   Driver.
   For example, if the <link linkend="book.mysqli">mysqli</link>
   extension and the PDO MySQL driver are both set-up to use MySQLnd,
   then function calls from <link linkend="book.mysqli">mysqli</link>
   and method calls from PDO will affect the statistics.
  </simpara>
  <simpara>
   There is no way to find out how much a certain API call of any extension
   that has been compiled against MySQL Native Driver has impacted a certain
   statistic.
  </simpara>
 </note>

 <section xml:id="mysqlnd.stats.retrieve" annotations="chunk:false">
  <title>Retrieving statistics</title>

  <simpara>
   Client statistics can be retrieved by calling the
   <function>mysqli_get_client_stats</function> function.
  </simpara>

  <simpara>
   Connection statistics can be retrieved by calling the
   <function>mysqli_get_connection_stats</function> function.
  </simpara>

  <simpara>
   Both functions return an associative array,
   where the name of a statistic is the key for the corresponding
   statistical data.
  </simpara>
 </section>

 <section xml:id="mysqlnd.stats.statistics" annotations="chunk:false">
  <title>MySQL Native Driver Statistics</title>
  <simpara>
   Most statistics are associated to a connection, but some are associated
   to the process in which case this will be mentioned.
   <!-- Process running the server? -->
  </simpara>
  <simpara>
   The following statistics are produced by the MySQL Native Driver:
  </simpara>

  <variablelist>
   <title>Network Related Statistics</title>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-sent">
    <term><literal>bytes_sent</literal></term>
    <listitem>
     <simpara>
      Number of bytes sent from PHP to the MySQL server.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received">
    <term><literal>bytes_received</literal></term>
    <listitem>
     <simpara>
      Number of bytes received from the MySQL server.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-sent">
    <term><literal>packets_sent</literal></term>
    <listitem>
     <simpara>
      Number of packets sent by the MySQL Client Server protocol.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received">
    <term><literal>packets_received</literal></term>
    <listitem>
     <simpara>
      Number of packets received from the MySQL Client Server protocol.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.protocol-overhead-in">
    <term><literal>protocol_overhead_in</literal></term>
    <listitem>
     <simpara>
      MySQL Client Server protocol overhead in bytes for incoming traffic.
      Currently only the Packet Header (4 bytes) is considered as overhead.
      <code>protocol_overhead_in = packets_received * 4</code>
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.protocol-overhead-out">
    <term><literal>protocol_overhead_out</literal></term>
    <listitem>
     <simpara>
      MySQL Client Server protocol overhead in bytes for outgoing traffic.
      Currently only the Packet Header (4 bytes) is considered as overhead.
      <code>protocol_overhead_out = packets_received * 4</code>
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-ok-packet">
    <term><literal>bytes_received_ok_packet</literal></term>
    <listitem>
     <simpara>
      Total size of bytes of MySQL Client Server protocol OK packets received.
      OK packets can contain a status message.
      The length of the status message can vary and thus the size of an OK
      packet is not fixed.
     </simpara>
     <note>
      <simpara>
       The total size in bytes includes the size of the header packet
       (4 bytes, see protocol overhead).
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-ok">
    <term><literal>packets_received_ok</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol OK packets received.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-eof-packet">
    <term><literal>bytes_received_eof_packet</literal></term>
    <listitem>
     <simpara>
      Total size in bytes of MySQL Client Server protocol EOF packets received.
      EOF can vary in size depending on the server version.
      Also, EOF can transport an error message.
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.bytes-received-ok-packet')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-eof">
    <term><literal>packets_received_eof</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol EOF packets.
     </simpara>
     <simpara>
      Like with other packet statistics the number of packets will be
      increased even if PHP does not receive the expected packet but,
      for example, an error message.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-rset-header-packet">
    <term><literal>bytes_received_rset_header_packet</literal></term>
    <listitem>
     <simpara>
      Total size in bytes of MySQL Client Server protocol result set header
      packets.
      The size of the packets varies depending on the payload
      (<literal>LOAD LOCAL INFILE</literal>, <literal>INSERT</literal>,
      <literal>UPDATE</literal>, <literal>SELECT</literal>, error message).
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.bytes-received-ok-packet')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-rset-header">
    <term><literal>packets_received_rset_header</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol result set header packets.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-rset-field-meta-packet">
    <term><literal>bytes_received_rset_field_meta_packet</literal></term>
    <listitem>
     <simpara>
      Total size in bytes of MySQL Client Server protocol result set metadata
      (field information) packets.
      Of course the size varies with the fields in the result set.
      The packet may also transport an error or an EOF packet in case of
      COM_LIST_FIELDS.
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.bytes-received-ok-packet')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-rset-field-meta">
    <term><literal>packets_received_rset_field_meta</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol result set metadata
      (field information) packets.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-rset-row-packet">
    <term><literal>bytes_received_rset_row_packet</literal></term>
    <listitem>
     <simpara>
      Total size in bytes of MySQL Client Server protocol result set row data
      packets.
      The packet may also transport an error or an EOF packet.
      One can compute the number of error and EOF packets by subtracting
      <literal>rows_fetched_from_server_normal</literal>
      and <literal>rows_fetched_from_server_ps</literal>
      from <literal>bytes_received_rset_row_packet</literal>.
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.bytes-received-ok-packet')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-rset-row">
    <term><literal>packets_received_rset_row</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol result set row data packets.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-prepare-response-packet">
    <term><literal>bytes_received_prepare_response_packet</literal></term>
    <listitem>
     <simpara>
      Total size in bytes of MySQL Client Server protocol OK for Prepared
      Statement Initialization packets (prepared statement init packets).
      The packet may also transport an error.
      The packet size depends on the MySQL version.
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.bytes-received-ok-packet')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-prepare-response">
    <term><literal>packets_received_prepare_response</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol OK for Prepared Statement
      Initialization packets (prepared statement init packets).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-change-user-packet">
    <term><literal>bytes_received_change_user_packet</literal></term>
    <listitem>
     <simpara>
      Total size in bytes of MySQL Client Server protocol COM_CHANGE_USER packets.
      The packet may also transport an error or EOF.
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.bytes-received-ok-packet')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-received-change-user">
    <term><literal>packets_received_change_user</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol COM_CHANGE_USER packets.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.packets-sent-command">
    <term><literal>packets_sent_command</literal></term>
    <listitem>
     <simpara>
      Number of MySQL Client Server protocol commands sent from PHP to MySQL.
     </simpara>
     <simpara>
      There is no way to know which specific commands and how many of
      them have been sent.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-real-data_normal">
    <term><literal>bytes_received_real_data_normal</literal></term>
    <listitem>
     <simpara>
      Number of bytes of payload fetched by the PHP client from
      <literal>mysqlnd</literal> using the text protocol.
     </simpara>
     <simpara>
      This is the size of the actual data contained in result sets that do not
      originate from prepared statements and which have been fetched by the PHP client.
     </simpara>
     <simpara>
      Note that although a full result set may have been pulled from MySQL
      by <literal>mysqlnd</literal>, this statistic only counts actual data
      pulled from <literal>mysqlnd</literal> by the PHP client.
     </simpara>
     <para>
      An example of a code sequence that will increase the value is as follows:
      <programlisting>
<![CDATA[
$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->fetch_assoc();
$res->close();
]]>
      </programlisting>
      Every fetch operation will increase the value.
     </para>
     <para>
      However, the statistic will not be increased if the result set is only
      buffered on the client, but not fetched, such as in the following example:
      <programlisting>
<![CDATA[
$mysqli = new mysqli();
$res = $mysqli->query("SELECT 'abc'");
$res->close();
]]>
      </programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bytes-received-real-data-ps">
    <term><literal>bytes_received_real_data_ps</literal></term>
    <listitem>
     <simpara>
      Number of bytes of the payload fetched by the PHP client from
      <literal>mysqlnd</literal> using the prepared statement protocol.
     </simpara>
     <simpara>
      This is the size of the actual data contained in result sets that
      originate from prepared statements and which have been fetched by the PHP client.
     </simpara>
     <simpara>
      The value will not be increased if the result set is not subsequently read by the PHP client.
     </simpara>
     <simpara>
      Note that although a full result set may have been pulled from MySQL
      by <literal>mysqlnd</literal>, this statistic only counts actual data
      pulled from <literal>mysqlnd</literal> by the PHP client.
     </simpara>
     <simpara>
      See also <literal>bytes_received_real_data_normal</literal>.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>

  <variablelist>
   <title>Result Set Related Statistics</title>

   <varlistentry xml:id="mysqlnd.stats.statistics.result-set-queries">
    <term><literal>result_set_queries</literal></term>
    <listitem>
     <simpara>
      Number of queries that have generated a result set.
      Examples of queries that generate a result set:
      <literal>SELECT</literal>, <literal>SHOW</literal>.
     </simpara>
     <simpara>
      The statistic will not be incremented if there is an error reading
      the result set header packet from the line.
     </simpara>
     <note>
      <simpara>
       This statistic can be used as an indirect measure for the number of
       queries PHP has sent to MySQL.
       This could help identifying a client that causes a high database load.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.non-result-set-queries">
    <term><literal>non_result_set_queries</literal></term>
    <listitem>
     <simpara>
      Number of queries that did not generate a result set.
      Examples of queries that do not generate a result set:
      <literal>INSERT</literal>, <literal>UPDATE</literal>, <literal>LOAD DATA</literal>.
     </simpara>
     <simpara>
      The statistic will not be incremented if there is an error reading
      the result set header packet from the line.
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.result-set-queries')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.no-index-used">
    <term><literal>no_index_used</literal></term>
    <listitem>
     <simpara>
      Number of queries that have generated a result set but did not use an index.
      (See also the mysqld start option <literal>--log-queries-not-using-indexes</literal>).
     </simpara>
     <note>
      <simpara>
       Those queries can be reported via an exception by calling
       <code>mysqli_report(MYSQLI_REPORT_INDEX);</code>.
       It is possible to have them be reported via a warning instead by calling
       <code>mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);</code>.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.bad-index-used">
    <term><literal>bad_index_used</literal></term>
    <listitem>
     <simpara>
      Number of queries that have generated a result set and did not use a good index.
      (See also the mysqld start option <literal>--log-slow-queries</literal>).
     </simpara>
     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.no-index-used')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.slow-queries">
    <term><literal>slow_queries</literal></term>
    <listitem>
     <simpara>
      SQL statements that took more than <literal>long_query_time</literal>
      seconds to execute and required at least
      <literal>min_examined_row_limit</literal> rows to be examined.
     </simpara>
     <caution>
      <simpara>
       Not reported through <function>mysqli_report</function>.
      </simpara>
     </caution>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.buffered-sets">
    <term><literal>buffered_sets</literal></term>
    <listitem>
     <simpara>
      Number of buffered result sets returned by normal
      (i.e. not via a prepared statement) queries.
     </simpara>
     <para>
      Examples of API calls that will buffer result sets on the client:
      <simplelist type="inline">
       <member><function>mysqli_query</function></member>
       <member><function>mysqli_store_result</function></member>
       <member><function>mysqli_stmt_get_result</function></member>
      </simplelist>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.unbuffered-sets">
    <term><literal>unbuffered_sets</literal></term>
    <listitem>
     <simpara>
      Number of unbuffered result sets returned by normal
      (i.e. not via a prepared statement) queries.
     </simpara>
     <para>
      Examples of API calls that will not buffer result sets on the client:
      <simplelist type="inline">
       <member><function>mysqli_use_result</function></member>
      </simplelist>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.ps-buffered-sets">
    <term><literal>ps_buffered_sets</literal></term>
    <listitem>
     <simpara>
      Number of buffered result sets returned by prepared statements.
     </simpara>
     <para>
      Examples of API calls that will buffer result sets on the client:
      <simplelist type="inline">
       <member><function>mysqli_stmt_store_result</function></member>
      </simplelist>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.ps-unbuffered-sets">
    <term><literal>ps_unbuffered_sets</literal></term>
    <listitem>
     <simpara>
      Number of unbuffered result sets returned by prepared statements.
     </simpara>
     <simpara>
      By default prepared statements are unbuffered,
      thus most prepared statements will be accounted in this statistic.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.flushed-normal-sets">
    <term><literal>flushed_normal_sets</literal></term>
    <listitem>
     <simpara>
      Number of result sets returned by normal
      (i.e. not via a prepared statement) queries
      with unread data that have been silently flushed.
     </simpara>

     <note>
      <simpara>
       Flushing happens only with unbuffered result sets.
      </simpara>
      <simpara>
       Unbuffered result sets must be fetched completely before a new query can
       be run on the connection otherwise MySQL will throw an error.
       If the application does not fetch all rows from an unbuffered result set,
       mysqlnd does implicitly fetch the result set to clear the line.
      </simpara>
      <simpara>
       See also <literal>rows_skipped_normal</literal>, <literal>rows_skipped_ps</literal>.
      </simpara>
      <para>
       Some possible causes for an implicit flush:
       <itemizedlist>
        <listitem>
         <simpara>
          Faulty client application
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          Client stopped reading after it found what it was looking for
          but has made MySQL calculate more records than needed
         </simpara>
        </listitem>
        <listitem>
         <simpara>
          Client application has stopped unexpectedly
         </simpara>
        </listitem>
       </itemizedlist>
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.flushed-ps-sets">
    <term><literal>flushed_ps_sets</literal></term>
    <listitem>
     <simpara>
      Number of result sets from prepared statements
      with unread data that have been silently flushed.
     </simpara>

     <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('mysqlnd.stats.statistics.flushed-normal-sets')/db:listitem/db:note)">
      <xi:fallback/>
     </xi:include>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.ps-prepared-never-executed">
    <term><literal>ps_prepared_never_executed</literal></term>
    <listitem>
     <simpara>
      Number of statements prepared but never executed.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.ps-prepared-once-executed">
    <term><literal>ps_prepared_once_executed</literal></term>
    <listitem>
     <simpara>
      Number of prepared statements executed only once.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-fetched-from-server-normal">
    <term><literal>rows_fetched_from_server_normal</literal></term>
    <term><literal>rows_fetched_from_server_ps</literal></term>
    <listitem>
     <simpara>
      Total number of result set rows fetched from the server.
      This includes the rows which were not read by the client but
      had been implicitly fetched due to flushed unbuffered result sets.
     </simpara>
     <simpara>
      See also <literal>packets_received_rset_row</literal>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-buffered-from-server-normal">
    <term><literal>rows_buffered_from_client_normal</literal></term>
    <listitem>
     <simpara>
      Total number of buffered rows originating from a normal query.
     </simpara>
     <simpara>
      This is the number of rows that have been fetched from MySQL and buffered on client.
     </simpara>
     <para>
      Examples of queries that will buffer results:
      <simplelist>
       <member><function>mysqli_query</function></member>
       <member><function>mysqli_store_result</function></member>
      </simplelist>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-buffered-from-server-ps">
    <term><literal>rows_buffered_from_server_ps</literal></term>
    <listitem>
     <simpara>
      Same as <literal>rows_buffered_from_client_normal</literal>
      but for prepared statements.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-fetched-from-client-normal-buffered">
    <term><literal>rows_fetched_from_client_normal_buffered</literal></term>
    <listitem>
     <simpara>
      Total number of rows fetched by the client from a buffered result set
      created by a normal query.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-fetched-from-client-ps-buffered">
    <term><literal>rows_fetched_from_client_ps_buffered</literal></term>
    <listitem>
     <simpara>
      Total number of rows fetched by the client from a buffered result set
      created by a prepared statement.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-fetched-from-client-normal-unbuffered">
    <term><literal>rows_fetched_from_client_normal_unbuffered</literal></term>
    <listitem>
     <simpara>
      Total number of rows fetched by the client from an unbuffered result set
      created by a normal query.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-fetched-from-client-ps-unbuffered">
    <term><literal>rows_fetched_from_client_ps_unbuffered</literal></term>
    <listitem>
     <simpara>
      Total number of rows fetched by the client from an unbuffered result set
      created by a prepared statement.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.rows-fetched-from-client-ps-cursor">
    <term><literal>rows_fetched_from_client_ps_cursor</literal></term>
    <listitem>
     <simpara>
      Total number of rows fetch by the client from a cursor created by a
      prepared statement.
     </simpara>
    </listitem>
   </varlistentry>

   <!-- TODO: This seems to actually be supported, check and document -->
   <varlistentry xml:id="mysqlnd.stats.statistics.rows-skipped-normal">
    <term><literal>rows_skipped_normal</literal></term>
    <term><literal>rows_skipped_ps</literal></term>
    <listitem>
     <simpara>
      Reserved for future use (currently not supported).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.copy-on-write">
    <term><literal>copy_on_write_saved</literal></term>
    <term><literal>copy_on_write_performed</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
     <simpara>
      With mysqlnd, variables returned by the extensions point into mysqlnd
      internal network result buffers.
      If the data are not changed, the fetched data is kept only once in memory.
      However, any modification to the data will require mysqlnd to perform
      a copy-on-write operation.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.free-result">
    <term><literal>explicit_free_result</literal></term>
    <term><literal>implicit_free_result</literal></term>
    <listitem>
     <simpara>
      This is a connection and process level scope statistic.
     </simpara>
     <simpara>
      Total number of freed result sets.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-null">
    <term><literal>proto_text_fetched_null</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_NULL</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-null">
    <term><literal>proto_binary_fetched_null</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_NULL</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-bit">
    <term><literal>proto_text_fetched_bit</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_BIT</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-bit">
    <term><literal>proto_binary_fetched_bit</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_BIT</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-tinyint">
    <term><literal>proto_text_fetched_tinyint</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TINY</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-tinyint">
    <term><literal>proto_binary_fetched_tinyint</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TINY</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-short">
    <term><literal>proto_text_fetched_short</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_SHORT</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-short">
    <term><literal>proto_binary_fetched_short</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_SHORT</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-int24">
    <term><literal>proto_text_fetched_int24</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_INT24</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-int24">
    <term><literal>proto_binary_fetched_int24</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_INT24</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-int">
    <term><literal>proto_text_fetched_int</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_LONG</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-int">
    <term><literal>proto_binary_fetched_int</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_LONG</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-bigint">
    <term><literal>proto_text_fetched_bigint</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_LONGLONG</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-bigint">
    <term><literal>proto_binary_fetched_bigint</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_LONGLONG</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-decimal">
    <term><literal>proto_text_fetched_decimal</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DECIMAL</literal>, or <literal>MYSQL_TYPE_NEWDECIMAL</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-decimal">
    <term><literal>proto_binary_fetched_decimal</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DECIMAL</literal>, or <literal>MYSQL_TYPE_NEWDECIMAL</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-float">
    <term><literal>proto_text_fetched_float</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_FLOAT</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-float">
    <term><literal>proto_binary_fetched_float</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_FLOAT</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-double">
    <term><literal>proto_text_fetched_double</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DOUBLE</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-double">
    <term><literal>proto_binary_fetched_double</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DOUBLE</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-date">
    <term><literal>proto_text_fetched_date</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DATE</literal>, or <literal>MYSQL_TYPE_NEWDATE</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-date">
    <term><literal>proto_binary_fetched_date</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DATE</literal>, or <literal>MYSQL_TYPE_NEWDATE</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-year">
    <term><literal>proto_text_fetched_year</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_YEAR</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-year">
    <term><literal>proto_binary_fetched_year</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_YEAR</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-time">
    <term><literal>proto_text_fetched_time</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TIME</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-time">
    <term><literal>proto_binary_fetched_time</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TIME</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-datetime">
    <term><literal>proto_text_fetched_datetime</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DATETIME</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-datetime">
    <term><literal>proto_binary_fetched_datetime</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_DATETIME</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-timestamp">
    <term><literal>proto_text_fetched_timestamp</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TIMESTAMP</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-timestamp">
    <term><literal>proto_binary_fetched_timestamp</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TIMESTAMP</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-string">
    <term><literal>proto_text_fetched_string</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_STRING</literal>, <literal>MYSQL_TYPE_VARSTRING</literal>, or <literal>MYSQL_TYPE_VARCHAR</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-string">
    <term><literal>proto_binary_fetched_string</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_STRING</literal>, <literal>MYSQL_TYPE_VARSTRING</literal>, or <literal>MYSQL_TYPE_VARCHAR</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-blob">
    <term><literal>proto_text_fetched_blob</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TINY_BLOB</literal>,
      <literal>MYSQL_TYPE_MEDIUM_BLOB</literal>,
      <literal>MYSQL_TYPE_LONG_BLOB</literal>,
      or <literal>MYSQL_TYPE_BLOB</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-blob">
    <term><literal>proto_binary_fetched_blob</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_TINY_BLOB</literal>,
      <literal>MYSQL_TYPE_MEDIUM_BLOB</literal>,
      <literal>MYSQL_TYPE_LONG_BLOB</literal>,
      or <literal>MYSQL_TYPE_BLOB</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-enum">
    <term><literal>proto_text_fetched_enum</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_ENUM</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-enum">
    <term><literal>proto_binary_fetched_enum</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_ENUM</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-set">
    <term><literal>proto_text_fetched_set</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_SET</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-set">
    <term><literal>proto_binary_fetched_set</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_SET</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-geometry">
    <term><literal>proto_text_fetched_geometry</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_GEOMETRY</literal>
      fetched from a normal query (MySQL text protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-geometry">
    <term><literal>proto_binary_fetched_geometry</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_GEOMETRY</literal>
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-text-fetched-other">
    <term><literal>proto_text_fetched_other</literal></term>
    <listitem>
     <simpara>
      Total number of columns of types
      <literal>MYSQL_TYPE_<replaceable>*</replaceable></literal>
      not listed previously
      fetched from a normal query (MySQL text protocol).
     </simpara>
     <note>
      <simpara>
       In theory, this should always be <literal>0</literal>.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.proto-binary-fetched-other">
    <term><literal>proto_binary_fetched_other</literal></term>
    <listitem>
     <simpara>
      Total number of columns of type
      <literal>MYSQL_TYPE_<replaceable>*</replaceable></literal>
      not listed previously
      fetched from a prepared statement (MySQL binary protocol).
     </simpara>
     <note>
      <simpara>
       In theory, this should always be <literal>0</literal>.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

  </variablelist>

  <variablelist>
   <title>Connection Related Statistics</title>

   <varlistentry xml:id="mysqlnd.stats.statistics.connect-success">
    <term><literal>connect_success</literal></term>
    <listitem>
     <simpara>
      Total number of successful connection attempts.
     </simpara>
     <note>
      <simpara>
       <literal>connect_success</literal> holds the sum of successful
       persistent and non-persistent connection attempts.
       Therefore, the number of successful non-persistent connection attempts
       is <literal>connect_success - pconnect_success</literal>.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.pconnect-success">
    <term><literal>pconnect_success</literal></term>
    <listitem>
     <simpara>
      Total number of successful persistent connection attempts.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.connect-failure">
    <term><literal>connect_failure</literal></term>
    <listitem>
     <simpara>
      Total number of failed connection attempts.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.reconnect">
    <term><literal>reconnect</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.active-connections">
    <term><literal>active_connections</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
     <simpara>
      Total number of active persistent and non-persistent connections.
     </simpara>
     <note>
      <simpara>
       The total number of active non-persistent connections is
       <literal>active_connections - active_persistent_connections</literal>.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.active-persistent-connections">
    <term><literal>active_persistent_connections</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
     <simpara>
      Total number of active persistent connections.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.explicit-close">
    <term><literal>explicit_close</literal></term>
    <listitem>
     <simpara>
      Total number of explicitly closed connections.
     </simpara>
     <example>
      <title>Examples of code snippets that cause an explicit close</title>
      <itemizedlist>
       <listitem>
        <programlisting>
<![CDATA[
$link = new mysqli(/* ... */);
$link->close(/* ... */);
]]>
        </programlisting>
       </listitem>
       <listitem>
        <programlisting>
<![CDATA[
$link = new mysqli(/* ... */);
$link->connect(/* ... */);
]]>
        </programlisting>
       </listitem>
      </itemizedlist>
     </example>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.implicit-close">
    <term><literal>implicit_close</literal></term>
    <listitem>
     <simpara>
      Total number of implicitly closed connections.
     </simpara>
     <example>
      <title>Examples of code snippets that cause an implicit close</title>
      <itemizedlist>
       <listitem>
        <programlisting>
<![CDATA[
$link = new mysqli(/* ... */);
$link->real_connect(/* ... */);
]]>
        </programlisting>
       </listitem>
       <listitem>
        <programlisting>
         <code>unset($link)</code>
        </programlisting>
       </listitem>
       <listitem>
        <simpara>
         Persistent connection: pooled connection has been created with
         real_connect and there may be unknown options set - close
         implicitly to avoid returning a connection with unknown options
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Persistent connection: ping/change_user fails and ext/mysqli
         closes the connection
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         End of script execution: close connections that have not been
         closed by the user
        </simpara>
       </listitem>
      </itemizedlist>
     </example>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.disconnect-close">
    <term><literal>disconnect_close</literal></term>
    <listitem>
     <simpara>
      Connection failures indicated by the C API call
      <literal>mysql_real_connect</literal> during an attempt to
      establish a connection.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.in-middle-of-command-close">
    <term><literal>in_middle_of_command_close</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
     <simpara>
      A connection has been closed in the middle of a command execution
      (outstanding result sets not fetched, after sending a query and
      before retrieving an answer, while fetching data, while
      transferring data with LOAD DATA).
     </simpara>
     <warning>
      <simpara>
       Unless asynchronous queries are used,
       this should only happen if the PHP application terminated unexpectedly,
       and PHP shuts down the connection automatically.
      </simpara>
     </warning>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.init-command-executed-count">
    <term><literal>init_command_executed_count</literal></term>
    <listitem>
     <simpara>
      Total number of init command executions.
      For example: <code>mysqli_options(MYSQLI_INIT_COMMAND , $value)</code>.
     </simpara>
     <simpara>
      The number of successful executions is
      <literal>init_command_executed_count - init_command_failed_count</literal>.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.init-command-failed-count">
    <term><literal>init_command_failed_count</literal></term>
    <listitem>
     <simpara>
      Total number of failed init commands.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>

  <variablelist>
   <title><literal>COM_*</literal> Command Related Statistics</title>

   <varlistentry xml:id="mysqlnd.stats.statistics.com">
    <term><literal>com_quit</literal></term>
    <term><literal>com_init_db</literal></term>
    <term><literal>com_query</literal></term>
    <term><literal>com_field_list</literal></term>
    <term><literal>com_create_db</literal></term>
    <term><literal>com_drop_db</literal></term>
    <term><literal>com_refresh</literal></term>
    <term><literal>com_shutdown</literal></term>
    <term><literal>com_statistics</literal></term>
    <term><literal>com_process_info</literal></term>
    <term><literal>com_connect</literal></term>
    <term><literal>com_process_kill</literal></term>
    <term><literal>com_debug</literal></term>
    <term><literal>com_ping</literal></term>
    <term><literal>com_time</literal></term>
    <term><literal>com_delayed_insert</literal></term>
    <term><literal>com_change_user</literal></term>
    <term><literal>com_binlog_dump</literal></term>
    <term><literal>com_table_dump</literal></term>
    <term><literal>com_connect_out</literal></term>
    <term><literal>com_register_slave</literal></term>
    <term><literal>com_stmt_prepare</literal></term>
    <term><literal>com_stmt_execute</literal></term>
    <term><literal>com_stmt_send_long_data</literal></term>
    <term><literal>com_stmt_close</literal></term>
    <term><literal>com_stmt_reset</literal></term>
    <term><literal>com_stmt_set_option</literal></term>
    <term><literal>com_stmt_fetch</literal></term>
    <term><literal>com_daemon</literal></term>
    <listitem>
     <simpara>
      Total number of attempts to send a certain <literal>COM_*</literal>
      command from PHP to MySQL.
     </simpara>
     <simpara>
      The statistics are incremented after checking the line and immediately
      before sending the corresponding MySQL client server protocol packet.
     </simpara>
     <caution>
      <simpara>
       If MySQLnd fails to send the packet over the wire the statistics will not be decremented.
       In case of a failure MySQLnd emits a PHP warning
       <quote>Error while sending %s packet. PID=%d.</quote>
      </simpara>
     </caution>

     <example>
      <title>Usage examples</title>
      <itemizedlist>
       <listitem>
        <para>
         Check if PHP sends certain commands to MySQL, for example,
         check if a client sends <literal>COM_PROCESS_KILL</literal>
        </para>
       </listitem>
       <listitem>
        <para>
         Calculate the average number of prepared statement executions
         by comparing <literal>COM_EXECUTE</literal> with
         <literal>COM_PREPARE</literal>
        </para>
       </listitem>
       <listitem>
        <para>
         Check if PHP has run any non-prepared SQL statements by
         checking if <literal>COM_QUERY</literal> is zero
        </para>
       </listitem>
       <listitem>
        <para>
         Identify PHP scripts that run an excessive number of SQL
         statements by checking <literal>COM_QUERY</literal> and
         <literal>COM_EXECUTE</literal>
        </para>
       </listitem>
      </itemizedlist>
     </example>
    </listitem>
   </varlistentry>
  </variablelist>

  <variablelist>
   <title>Miscellaneous Statistics</title>

   <varlistentry xml:id="mysqlnd.stats.statistics.stmt-close">
    <term><literal>explicit_stmt_close</literal></term>
    <term><literal>implicit_stmt_close</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
     <simpara>
      Total number of closed prepared statements.
     </simpara>
     <note>
      <simpara>
       A prepared statement is always explicitly closed. The only time it's closed implicitly is when preparing it fails.
      </simpara>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.memory-management">
    <term><literal>mem_emalloc_count</literal></term>
    <term><literal>mem_emalloc_ammount</literal></term>
    <term><literal>mem_ecalloc_count</literal></term>
    <term><literal>mem_ecalloc_ammount</literal></term>
    <term><literal>mem_realloc_count</literal></term>
    <term><literal>mem_realloc_ammount</literal></term>
    <term><literal>mem_efree_count</literal></term>
    <term><literal>mem_malloc_count</literal></term>
    <term><literal>mem_malloc_ammount</literal></term>
    <term><literal>mem_calloc_count</literal></term>
    <term><literal>mem_calloc_ammount</literal></term>
    <term><literal>mem_ealloc_count</literal></term>
    <term><literal>mem_ealloc_ammount</literal></term>
    <term><literal>mem_free_count</literal></term>
    <listitem>
     <simpara>
      This is a process level scope statistic.
     </simpara>
     <simpara>
      Memory management calls.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.command-buffer-too-small">
    <term><literal>command_buffer_too_small</literal></term>
    <!-- TODO: XInclude/sync description of INI setting
     ini.mysqlnd.net-cmd-buffer-size with this statistic -->
    <listitem>
     <simpara>
      Number of network command buffer extensions while sending commands from
      PHP to MySQL.
     </simpara>
     <simpara>
      MySQLnd allocates an internal command/network buffer of
      <link linkend="ini.mysqlnd.net-cmd-buffer-size">mysqlnd.net_cmd_buffer_size</link>
      bytes for every connection.
     </simpara>
     <simpara>
      If a MySQL Client Server protocol command,
      e.g. <literal>COM_QUERY</literal> (normal query),
      does not fit into the buffer,
      MySQLnd will grow the buffer to what is needed for sending the command.
      Whenever the buffer gets extended for one connection
      <literal>command_buffer_too_small</literal> will be incremented by one.
     </simpara>
     <simpara>
      If MySQLnd has to grow the buffer beyond its initial size of
      <link linkend="ini.mysqlnd.net-cmd-buffer-size">mysqlnd.net_cmd_buffer_size</link>
      bytes for almost every connection,
      considerations to increase the default size should be made to avoid
      re-allocations.
     </simpara>
    </listitem>
   </varlistentry>

   <varlistentry xml:id="mysqlnd.stats.statistics.connection-reused">
    <term><literal>connection_reused</literal></term>
    <listitem>
     <simpara>
      The total number of times a persistent connection has been reused.
     </simpara>
    </listitem>
   </varlistentry>
  </variablelist>
 </section>
</chapter>
<!-- 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
-->