auto_explainモジュールは、手動でEXPLAINの実行を必要とせず、自動的に遅い文の実行計画をログ記録する手段を提供します。
大きなアプリケーションにおける最適化されていない問い合わせを追跡するのに特に有用です。
このモジュールはSQLでアクセスできる関数を提供しません。 使用するには、サーバに単に読み込ませます。 ある個別のセッションに読み込ませることができます。
LOAD 'auto_explain';
（実行するためにはスーパーユーザでなければなりません。）
より一般的な使用方法は、postgresql.confのsession_preload_librariesまたはshared_preload_librariesにauto_explainを含めて、特定のまたはすべてのセッションで事前にロードしておくことです。
すると、想定外に低速な問い合わせを発生時に何も行うことなく追跡することができます。
当然ながらこのためのオーバーヘッドという代償があります。
auto_explainの動作を制御するいくつかの設定パラメータが存在します。
デフォルトの動作は何もしないことなので、なんらかの結果を望むのであれば少なくともauto_explain.log_min_durationを設定しなければならないことに注意してください。
auto_explain.log_min_duration (integer)
auto_explain.log_min_durationは、文の実行計画がログに記録されるようになる、ミリ秒単位の最小の文実行時間です。
これを0にすれば、すべての計画が記録されます。
-1（デフォルト）は計画の記録を無効にします。
例えば、250msに設定すると、250ms以上実行する文すべてが記録されます。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.log_analyze (boolean)
auto_explain.log_analyzeは、実行計画のログが取得されたときに出力されるものとして、単にEXPLAIN出力ではなく、EXPLAIN ANALYZE出力を行います。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更できます。
このパラメータが有効の場合、計画ノードごとの時間的調整は事実上ログされるまで如何に時間が掛かろうと、全ての実行文に対して引き起こります。
極端に性能上のマイナスの影響が起こり得ます。
auto_explain.log_timingを無効にすれば、得られる情報が少なくなるという犠牲を払って、性能の損失が改善されます。
auto_explain.log_buffers (boolean)
auto_explain.log_buffersは実行計画のログを取得するときに、バッファ使用統計を出力するかどうかを制御します。
EXPLAINのBUFFERSオプションと同じです。
auto_explain.log_analyzeパラメータが設定されていなければ、このパラメータは効果がありません。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.log_wal (boolean)
auto_explain.log_walは実行計画のログを取得するときに、WAL使用統計を出力するかどうかを制御します。
EXPLAINのWALオプションと同じです。
auto_explain.log_analyzeパラメータが設定されていなければ、このパラメータは効果がありません。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.log_timing (boolean)
auto_explain.log_timingは、実行計画のログが取得されたときに、ノード毎の時間的調整情報を出力するかどうかを制御します。
EXPLAINのTIMINGオプションと同じです。
システムクロックを繰り返し読み出すことによるオーバーヘッドのため、システムの中には問い合わせが非常に遅くなるものがありますので、実際の行数のみ必要で正確な時刻は必要でない場合にはこのパラメータを無効にすると役に立つかも知れません。
auto_explain.log_analyzeが設定されていなければ、このパラメータは効果がありません。
デフォルトで有効です。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.log_triggers (boolean)
auto_explain.log_triggersにより、実行計画のログを記録するときに、トリガ実行の統計を含めるようになります。
auto_explain.log_analyzeパラメータが設定されていなければ、このパラメータは効果がありません。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.log_verbose (boolean)
auto_explain.log_verboseは、実行計画のログが取得されたときに、冗長な詳細が出力されるかどうかを制御します。
EXPLAINのVERBOSEオプションと同じです。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更できます。
auto_explain.log_settings (boolean)
auto_explain.log_settingsは、実行計画が記録される時に修正された設定オプションに関する情報を表示するかどうかを制御します。
問い合わせ計画に影響し、組み込みのデフォルトの値と異なる値であるオプションだけが出力に含まれます。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更できます。
auto_explain.log_format (enum)
auto_explain.log_formatは使用するEXPLAIN出力書式を選びます。
許容される値はtext、xml、json、yamlです。
デフォルトはtextです。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.log_level (enum)
auto_explain.log_levelは、auto_explainが問い合わせ計画を記録するログレベルを選択します。
有効な値はDEBUG5、DEBUG4、DEBUG3、DEBUG2、DEBUG1、INFO、NOTICE、WARNING、LOGです。
デフォルトはLOGです。
スーパーユーザのみがこの設定を変更できます。
auto_explain.log_nested_statements (boolean)
auto_explain.log_nested_statementsにより、入れ子状の文（関数内から実行される文）を考慮して記録するようになります。
無効ならば、最上位の問い合わせ計画のみが記録されます。
このパラメータはデフォルトで無効です。
スーパーユーザのみがこの設定を変更することができます。
auto_explain.sample_rate (real)
auto_explain.sample_rateにより、auto_explainは各セッションで一部の文の実行計画のみをログに記録するようになります。
デフォルトは1で、すべての問い合わせの実行計画をログに記録します。
入れ子になった文の場合には、実行計画がすべてログに記録されるか、全くされないかのどちらかです。
スーパーユーザのみがこの設定を変更できます。
スーパーユーザは自身のセッション内でその場で変更できますが、通常の使用では、これらパラメータはpostgresql.confに設定しなければなりません。
典型的な使用方法は以下のようになります。
# postgresql.conf session_preload_libraries = 'auto_explain' auto_explain.log_min_duration = '3s'
postgres=# LOAD 'auto_explain';
postgres=# SET auto_explain.log_min_duration = 0;
postgres=# SET auto_explain.log_analyze = true;
postgres=# SELECT count(*)
FROM pg_class, pg_index
WHERE oid = indrelid AND indisunique;
これにより、以下のようなログ出力が作成されます。
LOG: duration: 3.651 ms plan:
Query Text: SELECT count(*)
FROM pg_class, pg_index
WHERE oid = indrelid AND indisunique;
Aggregate (cost=16.79..16.80 rows=1 width=0) (actual time=3.626..3.627 rows=1 loops=1)
-> Hash Join (cost=4.17..16.55 rows=92 width=0) (actual time=3.349..3.594 rows=92 loops=1)
Hash Cond: (pg_class.oid = pg_index.indrelid)
-> Seq Scan on pg_class (cost=0.00..9.55 rows=255 width=4) (actual time=0.016..0.140 rows=255 loops=1)
-> Hash (cost=3.02..3.02 rows=92 width=4) (actual time=3.238..3.238 rows=92 loops=1)
Buckets: 1024 Batches: 1 Memory Usage: 4kB
-> Seq Scan on pg_index (cost=0.00..3.02 rows=92 width=4) (actual time=0.008..3.187 rows=92 loops=1)
Filter: indisunique