repo_zf1/documentation/manual/ja/module_specs/Zend_Db_Profiler.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.db.profiler" xmlns:xi="http://www.w3.org/2001/XInclude">

    <title>Zend_Db_Profiler</title>

    <sect2 id="zend.db.profiler.introduction">

        <title>導入</title>

        <para>
            <classname>Zend_Db_Profiler</classname> を使用すると、クエリの情報を取得することができます。
            アダプタが実際に実行したクエリの内容や実行所要時間などが取得でき、
            余計なデバッグコードをクラスに追加しなくてもクエリを調べられるようになります。
            さらに、条件を指定して特定のクエリだけの情報を取得することもできます。
        </para>

        <para>
            プロファイラを有効にするには、アダプタのコンストラクタで指定するか、
            あるいは後からアダプタに指示します。
        </para>

        <programlisting role="php"><![CDATA[
$params = array(
    'host'     => '127.0.0.1',
    'username' => 'webuser',
    'password' => 'xxxxxxxx',
    'dbname'   => 'test'
    'profiler' => true  // プロファイラを使用します。
                        // false (デフォルト) にすると無効になります。
);

$db = Zend_Db::factory('PDO_MYSQL', $params);

// プロファイラを無効にします
$db->getProfiler()->setEnabled(false);

// プロファイラを有効にします
$db->getProfiler()->setEnabled(true);
]]>
        </programlisting>

        <para>
            <code>profiler</code> オプションの値には柔軟性があり、
            その型に応じて、さまざまな形式で解釈されます。
            たいていは単純な boolean 値を指定することになるでしょうが、
            その他の型を指定することでプロファイラの振る舞いをカスタマイズすることも可能です。
        </para>

        <para>
            boolean 引数 <code>true</code> を指定すると、
            プロファイラを有効にします。あるいは <code>false</code>
            にすると、プロファイラを無効にします。プロファイラのクラスは、
            そのアダプタのデフォルトのプロファイラクラスである
            <classname>Zend_Db_Profiler</classname> となります。
            <programlisting role="php"><![CDATA[
$params['profiler'] = true;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]>
            </programlisting>
        </para>

        <para>
            プロファイラオブジェクトのインスタンスを、アダプタで使用します。
            このオブジェクトの型は、<classname>Zend_Db_Profiler</classname>
            あるいはそのサブクラスでなければなりません。
            プロファイラを有効にするには、次にようにします。
            <programlisting role="php"><![CDATA[
$profiler = MyProject_Db_Profiler();
$profiler->setEnabled(true);
$params['profiler'] = $profiler;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]>
            </programlisting>
        </para>

        <para>
            引数は連想配列で、'<code>enabled</code>'、
            '<code>instance</code>' および '<code>class</code>'
            のいずれか (あるいはすべて) のキーを持ちます。
            '<code>enabled</code>' と '<code>instance</code>' は、
            それぞれ boolean および上で説明したインスタンスです。
            '<code>class</code>' は、独自のプロファイラを使用する場合のクラス名を指定します。
            このクラスは <classname>Zend_Db_Profiler</classname> あるいはそのサブクラスでなければなりません。
            このクラスは、コンストラクタに何も引数を渡さないでインスタンス化されます。
            '<code>class</code>' の内容は、
            '<code>instance</code>' を指定した際には無視されます。
            <programlisting role="php"><![CDATA[
$params['profiler'] = array(
    'enabled' => true,
    'class'   => 'MyProject_Db_Profiler'
);
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]>
            </programlisting>
        </para>

        <para>
            また、引数は <classname>Zend_Config</classname> のオブジェクトで渡すこともできます。
            このオブジェクトのプロパティが、先ほどの連想配列のキーと同じように解釈されます。
            たとえば、次のような内容の "config.ini" ファイルがあったとしましょう。
            <programlisting role="ini"><![CDATA[
[main]
db.profiler.class   = "MyProject_Db_Profiler"
db.profiler.enabled = true
]]>
            </programlisting>

            この設定を適用するには、次のような PHP コードを書きます。

            <programlisting role="php"><![CDATA[
$config = new Zend_Config_Ini('config.ini', 'main');
$params['profiler'] = $config->db->profiler;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]>
            </programlisting>

            '<code>instance</code>' プロパティは、次のように使用します。
            <programlisting role="php"><![CDATA[
$profiler = new MyProject_Db_Profiler();
$profiler->setEnabled(true);
$configData = array(
    'instance' => $profiler
    );
$config = new Zend_Config($configData);
$params['profiler'] = $config;
$db = Zend_Db::factory('PDO_MYSQL', $params);
]]>
            </programlisting>

        </para>

    </sect2>

    <sect2 id="zend.db.profiler.using">

        <title>プロファイラの使用</title>

        <para>
            好きなところでアダプタの
            <code>getProfiler()</code> メソッドを使用すれば、
            プロファイラを取得できます。
        </para>

        <programlisting role="php"><![CDATA[
$profiler = $db->getProfiler();
]]>
        </programlisting>

        <para>
            これは、<classname>Zend_Db_Profiler</classname> オブジェクトのインスタンスを返します。
            このインスタンスのさまざまなメソッドを使用することで、
            クエリの内容を調べることができます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getTotalNumQueries()</code> は、
                    情報を取得したクエリの総数を返します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>getTotalElapsedSecs()</code> は、
                    情報を取得したクエリの実行所要時間の合計を返します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>getQueryProfiles()</code> は、
                    すべてのクエリ情報を配列で返します。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>getLastQueryProfile()</code> は、最後に
                    (直近に) 実行されたクエリの情報を (そのクエリが
                    完了したか否かにかかわらず) 返します
                    (クエリが完了していない場合は、終了時刻が null となります)。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>clear()</code> は、スタック上に残っている
                    過去のクエリ情報をすべて消去します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <code>getLastQueryProfile()</code> の返り値、および
            <code>getQueryProfiles()</code> の個々の要素は
            <classname>Zend_Db_Profiler_Query</classname> オブジェクトで、
            これを使用すると個々のクエリ自体の情報を調べられます。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    <code>getQuery()</code> は、クエリの SQL テキストを返します。
                    パラメータつきのプリペアドステートメントの場合、
                    クエリがプリペアされた時点のテキストを返します。
                    つまり、プレースホルダを含んだままの形式ということです。
                    実行時に置き換えられた値を知ることはできません。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>getQueryParams()</code> は、
                    プリペアドクエリを実行する際に使用する、パラメータの値の配列を返します。
                    ここには、バインドパラメータだけでなく
                    <code>execute()</code> メソッドへの引数も含まれます。
                    配列のキーは、(1 から始まる) 数値かあるいは (文字列の) パラメータ名となります。
                </para>
            </listitem>
            <listitem>
                <para>
                    <code>getElapsedSecs()</code> は、
                    クエリの実行所要時間を返します。
                </para>
            </listitem>
        </itemizedlist>

        <para>
            <classname>Zend_Db_Profiler</classname> の提供する情報は、
            アプリケーションのボトルネックを調査したり
            クエリをデバッグしたりする場合に有用です。
            例えば、直近に実行されたクエリが実際のところどんなものだったのかを知るには次のようにします。
        </para>

        <programlisting role="php"><![CDATA[
$query = $profiler->getLastQueryProfile();

echo $query->getQuery();
]]>
        </programlisting>

        <para>
            ページの生成に時間がかかっているとしましょう。この場合、
            プロファイラを使用してまず全クエリの実行所要秒数を取得します。
            それから、個々のクエリを調べ、一番時間がかかっているのはどれかを見つけます。
        </para>

        <programlisting role="php"><![CDATA[
$totalTime    = $profiler->getTotalElapsedSecs();
$queryCount   = $profiler->getTotalNumQueries();
$longestTime  = 0;
$longestQuery = null;

foreach ($profiler->getQueryProfiles() as $query) {
    if ($query->getElapsedSecs() > $longestTime) {
        $longestTime  = $query->getElapsedSecs();
        $longestQuery = $query->getQuery();
    }
}

echo '全部で ' . $queryCount . ' 件のクエリが ' . $totalTime .
     ' 秒で実行されました' . "\n";
echo '平均の所要時間: ' . $totalTime / $queryCount . ' 秒' . "\n";
echo '1 秒あたりのクエリ実行数: ' . $queryCount / $totalTime . "\n";
echo '所要時間の最大値: ' . $longestTime . "\n";
echo "一番時間のかかっているクエリ: \n" . $longestQuery . "\n";
]]>
        </programlisting>

    </sect2>

    <sect2 id="zend.db.profiler.advanced">

        <title>プロファイラの高度な使用法</title>

        <para>
            単にクエリを調べるだけでなく、どのクエリを調べるのかという
            条件を指定することも可能です。以下で説明するメソッドは、
            <classname>Zend_Db_Profiler</classname> インスタンスのメソッドです。
        </para>

        <sect3 id="zend.db.profiler.advanced.filtertime">
            <title>クエリの実行所要時間による絞り込み</title>

            <para>
                <code>setFilterElapsedSecs()</code> は、クエリの情報を取得する条件として
                実行所要時間の最小値を指定します。このフィルタを削除するには、
                メソッドに null 値を渡します。
            </para>

            <programlisting role="php"><![CDATA[
// 所要時間が 5 秒以上のクエリのみ調べます
$profiler->setFilterElapsedSecs(5);

// 所要時間にかかわらず、すべてのクエリを調べます
$profiler->setFilterElapsedSecs(null);
]]>
            </programlisting>
        </sect3>

        <sect3 id="zend.db.profiler.advanced.filtertype">
            <title>クエリの形式による絞り込み</title>

            <para>
                <code>setFilterQueryType()</code> は、クエリの情報を取得する条件として
                クエリの形式を指定します。複数の形式を扱うには、それらの論理 OR を指定します。
                クエリの形式は、<classname>Zend_Db_Profiler</classname>
                のクラス定数として以下のように定義されています。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::CONNECT</classname>:
                        接続操作、あるいはデータベースの選択。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::QUERY</classname>:
                        他の形式にあてはまらないクエリ。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::INSERT</classname>:
                        新しいデータをデータベースに追加するクエリ。
                        一般的には SQL の INSERT。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::UPDATE</classname>:
                        既存のデータを更新するクエリ。通常は SQL の UPDATE。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::DELETE</classname>:
                        既存のデータを削除するクエリ。通常は SQL の DELETE。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::SELECT</classname>:
                        既存のデータを取得するクエリ。通常は SQL の SELECT。
                    </para>
                </listitem>
                <listitem>
                    <para>
                        <classname>Zend_Db_Profiler::TRANSACTION</classname>:
                        トランザクションに関する操作。例えばトランザクションの開始や
                        コミット、ロールバックなど。
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                既存のフィルタを削除するには、
                <code>setFilterElapsedSecs()</code> の引数に
                <code>null</code> だけを渡します。
            </para>

            <programlisting role="php"><![CDATA[
// SELECT クエリのみを調べます
$profiler->setFilterQueryType(Zend_Db_Profiler::SELECT);

// SELECT、INSERT そして UPDATE クエリを調べます
$profiler->setFilterQueryType(Zend_Db_Profiler::SELECT |
                              Zend_Db_Profiler::INSERT |
                              Zend_Db_Profiler::UPDATE);

// DELETE クエリを調べます
$profiler->setFilterQueryType(Zend_Db_Profiler::DELETE);

// すべてのフィルタを削除します
$profiler->setFilterQueryType(null);
]]>
            </programlisting>

        </sect3>

        <sect3 id="zend.db.profiler.advanced.getbytype">
            <title>クエリの型を指定することによる情報の取得</title>

            <para>
                <code>setFilterQueryType()</code> を使用すると、生成される情報を減らすことができます。
                すべての情報を保持しておくほうがよい場合もありますが、
                普通はそのときに必要な情報のみが見られればよいでしょう。
                <code>getQueryProfiles()</code> のもうひとつの機能として、
                最初の引数にクエリの型 (あるいは複数の型の論理和)
                を指定することによるその場での絞り込みが可能です。
                クエリの型を表す定数については <xref linkend="zend.db.profiler.advanced.filtertype" />
                を参照ください。
            </para>

            <programlisting role="php"><![CDATA[
// SELECT クエリの情報のみを取得します
$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT);

// SELECT、INSERT そして UPDATE クエリの情報のみを取得します
$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::SELECT |
                                        Zend_Db_Profiler::INSERT |
                                        Zend_Db_Profiler::UPDATE);

// DELETE クエリの情報を取得します
$profiles = $profiler->getQueryProfiles(Zend_Db_Profiler::DELETE);
]]>
            </programlisting>

        </sect3>

    </sect2>

    <sect2 id="zend.db.profiler.profilers">
        <title>特化型のプロファイラ</title>

        <para>
            特化型のプロファイラは <classname>Zend_Db_Profiler</classname>
            を継承したオブジェクトです。
            プロファイリング情報を特別な方法で処理します。
        </para>

        <xi:include href="Zend_Db_Profiler-Firebug.xml" />

    </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->