head	1.9;
access;
symbols
	REL9_0_0:1.8.2.1
	REL9_1_ALPHA1:1.9
	REL9_0_RC1:1.8.2.1
	REL9_0_BETA4:1.8.2.1
	REL9_0_STABLE:1.8.0.2
	REL9_0_BETA3:1.8
	REL9_0_BETA2:1.8
	REL8_4_4:1.3
	REL9_0_BETA1:1.8
	REL9_0_ALPHA5_BRANCH:1.7.0.2
	REL9_0_ALPHA5:1.7
	REL8_4_3:1.3
	REL9_0_ALPHA4:1.6
	REL9_0_ALPHA4_BRANCH:1.6.0.4
	REL8_5_ALPHA3:1.6
	REL8_5_ALPHA3_BRANCH:1.6.0.2
	REL8_4_2:1.3
	REL8_5_ALPHA2:1.4
	REL8_5_ALPHA2_BRANCH:1.4.0.4
	REL8_4_1:1.3
	REL8_5_ALPHA1:1.4
	REL8_5_ALPHA1_BRANCH:1.4.0.2
	REL8_4_STABLE:1.3.0.2
	REL8_4_0:1.3
	REL8_4_RC2:1.3
	REL8_4_RC1:1.3
	REL8_4_BETA2:1.3
	REL8_4_BETA1:1.3;
locks; strict;
comment	@# @;


1.9
date	2010.07.29.19.34.40;	author petere;	state Exp;
branches;
next	1.8;

1.8
date	2010.04.03.07.22.52;	author petere;	state Exp;
branches
	1.8.2.1;
next	1.7;

1.7
date	2010.02.20.22.24.29;	author adunstan;	state Exp;
branches;
next	1.6;

1.6
date	2009.12.15.04.57.47;	author rhaas;	state Exp;
branches;
next	1.5;

1.5
date	2009.12.11.01.33.35;	author adunstan;	state Exp;
branches;
next	1.4;

1.4
date	2009.08.10.05.46.50;	author tgl;	state Exp;
branches;
next	1.3;

1.3
date	2009.01.02.01.16.02;	author tgl;	state Exp;
branches;
next	1.2;

1.2
date	2008.12.07.23.46.39;	author alvherre;	state Exp;
branches;
next	1.1;

1.1
date	2008.11.19.02.59.28;	author tgl;	state Exp;
branches;
next	;

1.8.2.1
date	2010.07.29.19.34.36;	author petere;	state Exp;
branches;
next	;


desc
@@


1.9
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.8 2010/04/03 07:22:52 petere Exp $ -->

<sect1 id="auto-explain">
 <title>auto_explain</title>

 <indexterm zone="auto-explain">
  <primary>auto_explain</primary>
 </indexterm>

 <para>
  The <filename>auto_explain</filename> module provides a means for
  logging execution plans of slow statements automatically, without
  having to run <xref linkend="sql-explain">
  by hand.  This is especially helpful for tracking down un-optimized queries
  in large applications.
 </para>

 <para>
  The module provides no SQL-accessible functions.  To use it, simply
  load it into the server.  You can load it into an individual session:

<programlisting>
LOAD 'auto_explain';
</programlisting>

  (You must be superuser to do that.)  More typical usage is to preload
  it into all sessions by including <literal>auto_explain</> in
  <xref linkend="guc-shared-preload-libraries"> in
  <filename>postgresql.conf</>.  Then you can track unexpectedly slow queries
  no matter when they happen.  Of course there is a price in overhead for
  that.
 </para>

 <sect2>
  <title>Configuration parameters</title>

 <para>
  There are several configuration parameters that control the behavior of
  <filename>auto_explain</filename>.  Note that the default behavior is
  to do nothing, so you must set at least
  <varname>auto_explain.log_min_duration</varname> if you want any results.
 </para>

  <variablelist>
   <varlistentry>
    <term>
     <varname>auto_explain.log_min_duration</varname> (<type>integer</type>)
    </term>
    <indexterm>
     <primary><varname>auto_explain.log_min_duration</> configuration parameter</primary>
    </indexterm>
    <listitem>
     <para>
      <varname>auto_explain.log_min_duration</varname> is the minimum statement
      execution time, in milliseconds, that will cause the statement's plan to
      be logged. Setting this to zero logs all plans. Minus-one (the default)
      disables logging of plans.  For example, if you set it to
      <literal>250ms</literal> then all statements that run 250ms or longer
      will be logged. Only superusers can change this setting.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <varname>auto_explain.log_analyze</varname> (<type>boolean</type>)
    </term>
    <indexterm>
     <primary><varname>auto_explain.log_analyze</> configuration parameter</primary>
    </indexterm>
    <listitem>
     <para>
      <varname>auto_explain.log_analyze</varname> causes <command>EXPLAIN ANALYZE</>
      output, rather than just <command>EXPLAIN</> output, to be printed
      when an execution plan is logged. This parameter is off by default.
      Only superusers can change this setting.
     </para>
     <note>
      <para>
       When this parameter is on, per-plan-node timing occurs for all
       statements executed, whether or not they run long enough to actually
       get logged.  This can have extremely negative impact on performance.
      </para>
     </note>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <varname>auto_explain.log_verbose</varname> (<type>boolean</type>)
    </term>
    <indexterm>
     <primary><varname>auto_explain.log_verbose</> configuration parameter</primary>
    </indexterm>
    <listitem>
     <para>
      <varname>auto_explain.log_verbose</varname> causes <command>EXPLAIN VERBOSE</>
      output, rather than just <command>EXPLAIN</> output, to be printed
      when an execution plan is logged. This parameter is off by default.
      Only superusers can change this setting.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <varname>auto_explain.log_buffers</varname> (<type>boolean</type>)
    </term>
    <indexterm>
     <primary><varname>auto_explain.log_buffers</> configuration parameter</primary>
    </indexterm>
    <listitem>
     <para>
      <varname>auto_explain.log_buffers</varname> causes <command>EXPLAIN
      (ANALYZE, BUFFERS)</> output, rather than just <command>EXPLAIN</> 
      output, to be printed when an execution plan is logged. This parameter is 
      off by default. Only superusers can change this setting. This
      parameter has no effect unless <varname>auto_explain.log_analyze</>
      parameter is set.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <varname>auto_explain.log_format</varname> (<type>enum</type>)
    </term>
    <indexterm>
     <primary><varname>auto_explain.log_format</> configuration parameter</primary>
    </indexterm>
    <listitem>
     <para>
      <varname>auto_explain.log_format</varname> selects the
      <command>EXPLAIN</> output format to be used.
      The allowed values are <literal>text</literal>, <literal>xml</literal>,
      <literal>json</literal>, and <literal>yaml</literal>.  The default is text.
      Only superusers can change this setting.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>
     <varname>auto_explain.log_nested_statements</varname> (<type>boolean</type>)
    </term>
    <indexterm>
     <primary><varname>auto_explain.log_nested_statements</> configuration parameter</primary>
    </indexterm>
    <listitem>
     <para>
      <varname>auto_explain.log_nested_statements</varname> causes nested
      statements (statements executed inside a function) to be considered
      for logging.  When it is off, only top-level query plans are logged. This
      parameter is off by default. Only superusers can change this setting.
     </para>
    </listitem>
   </varlistentry>
  </variablelist>

  <para>
   In order to set these parameters in your <filename>postgresql.conf</> file,
   you will need to add <literal>auto_explain</> to
   <xref linkend="guc-custom-variable-classes">.  Typical usage might be:
  </para>

<programlisting>
# postgresql.conf
shared_preload_libraries = 'auto_explain'

custom_variable_classes = 'auto_explain'
auto_explain.log_min_duration = '3s'
</programlisting>
 </sect2>

 <sect2>
  <title>Example</title>

<programlisting>
postgres=# LOAD 'auto_explain';
postgres=# SET auto_explain.log_min_duration = 0;
postgres=# SELECT count(*)
           FROM pg_class, pg_index
           WHERE oid = indrelid AND indisunique;
</programlisting>

  <para>
   This might produce log output such as:
  </para>

<screen><![CDATA[
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
]]></screen>
 </sect2>

 <sect2>
  <title>Author</title>

  <para>
   Takahiro Itagaki <email>itagaki.takahiro@@oss.ntt.co.jp</email>
  </para>
 </sect2>

</sect1>
@


1.8
log
@Remove unnecessary xref endterm attributes and title ids

The endterm attribute is mainly useful when the toolchain does not support
automatic link target text generation for a particular situation.  In  the
past, this was required by the man page tools for all reference page links,
but that is no longer the case, and it now actually gets in the way of
proper automatic link text generation.  The only remaining use cases are
currently xrefs to refsects.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.7 2010/02/20 22:24:29 adunstan Exp $ -->
d22 1
a22 1
  <programlisting>
d24 1
a24 1
  </programlisting>
d166 1
a166 1
  <programlisting>
d172 1
a172 1
  </programlisting>
d178 7
a184 7
  <programlisting>
  postgres=# LOAD 'auto_explain';
  postgres=# SET auto_explain.log_min_duration = 0;
  postgres=# SELECT count(*)
               FROM pg_class, pg_index
              WHERE oid = indrelid AND indisunique;
  </programlisting>
d190 14
a203 15
  <programlisting><![CDATA[
  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
]]>
  </programlisting>
@


1.8.2.1
log
@Fix indentation of verbatim block elements

Block elements with verbatim formatting (literallayout, programlisting,
screen, synopsis) should be aligned at column 0 independent of the surrounding
SGML, because whitespace is significant, and indenting them creates erratic
whitespace in the output.  The CSS stylesheets already take care of indenting
the output.

Assorted markup improvements to go along with it.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.8 2010/04/03 07:22:52 petere Exp $ -->
d22 1
a22 1
<programlisting>
d24 1
a24 1
</programlisting>
d166 1
a166 1
<programlisting>
d172 1
a172 1
</programlisting>
d178 7
a184 7
<programlisting>
postgres=# LOAD 'auto_explain';
postgres=# SET auto_explain.log_min_duration = 0;
postgres=# SELECT count(*)
           FROM pg_class, pg_index
           WHERE oid = indrelid AND indisunique;
</programlisting>
d190 15
a204 14
<screen><![CDATA[
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
]]></screen>
@


1.7
log
@Adjust sample auto-explain output to reflect query text inclusion.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.6 2009/12/15 04:57:47 rhaas Exp $ -->
d13 1
a13 1
  having to run <xref linkend="sql-explain" endterm="sql-explain-title">
@


1.6
log
@Add an EXPLAIN (BUFFERS) option to show buffer-usage statistics.

This patch also removes buffer-usage statistics from the track_counts
output, since this (or the global server statistics) is deemed to be a better
interface to this information.

Itagaki Takahiro, reviewed by Euler Taveira de Oliveira.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.5 2009/12/11 01:33:35 adunstan Exp $ -->
d191 12
a202 11
  LOG:  duration: 0.986 ms  plan:
          Aggregate  (cost=14.90..14.91 rows=1 width=0)
            ->  Hash Join  (cost=3.91..14.70 rows=81 width=0)
                  Hash Cond: (pg_class.oid = pg_index.indrelid)
                  ->  Seq Scan on pg_class  (cost=0.00..8.27 rows=227 width=4)
                  ->  Hash  (cost=2.90..2.90 rows=81 width=4)
                        ->  Seq Scan on pg_index  (cost=0.00..2.90 rows=81 width=4)
                              Filter: indisunique
  STATEMENT:  SELECT count(*)
            FROM pg_class, pg_index
           WHERE oid = indrelid AND indisunique;
@


1.5
log
@Add YAML to list of EXPLAIN formats. Greg Sabino Mullane, reviewed by Takahiro Itagaki.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.4 2009/08/10 05:46:50 tgl Exp $ -->
d107 19
@


1.4
log
@Extend EXPLAIN to support output in XML or JSON format.

There are probably still some adjustments to be made in the details
of the output, but this gets the basic structure in place.

Robert Haas
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.3 2009/01/02 01:16:02 tgl Exp $ -->
d117 1
a117 1
      and <literal>json</literal>.  The default is text.
@


1.3
log
@Tweak guc.c to allow underscores in the names of custom variable classes,
and change auto_explain's custom GUC variables to be named auto_explain.xxx
not just explain.xxx.  Per discussion in connection with the
pg_stat_statements patch, it seems like a good idea to have the convention
that custom variable classes are named the same as their defining module.
Committing separately since this should happen regardless of what happens
with pg_stat_statements itself.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.2 2008/12/07 23:46:39 alvherre Exp $ -->
d107 18
@


1.2
log
@Desultorily enclose programlisting tags in CDATA, to get rid of some obnoxious
SGML-escaping.
@
text
@d1 1
a1 1
<!-- $PostgreSQL: pgsql/doc/src/sgml/auto-explain.sgml,v 1.1 2008/11/19 02:59:28 tgl Exp $ -->
d41 1
a41 1
  <varname>explain.log_min_duration</varname> if you want any results.
d47 1
a47 1
     <varname>explain.log_min_duration</varname> (<type>integer</type>)
d50 1
a50 1
     <primary><varname>explain.log_min_duration</> configuration parameter</primary>
d54 1
a54 1
      <varname>explain.log_min_duration</varname> is the minimum statement
d66 1
a66 1
     <varname>explain.log_analyze</varname> (<type>boolean</type>)
d69 1
a69 1
     <primary><varname>explain.log_analyze</> configuration parameter</primary>
d73 1
a73 1
      <varname>explain.log_analyze</varname> causes <command>EXPLAIN ANALYZE</>
d90 1
a90 1
     <varname>explain.log_verbose</varname> (<type>boolean</type>)
d93 1
a93 1
     <primary><varname>explain.log_verbose</> configuration parameter</primary>
d97 1
a97 1
      <varname>explain.log_verbose</varname> causes <command>EXPLAIN VERBOSE</>
d107 1
a107 1
     <varname>explain.log_nested_statements</varname> (<type>boolean</type>)
d110 1
a110 1
     <primary><varname>explain.log_nested_statements</> configuration parameter</primary>
d114 1
a114 1
      <varname>explain.log_nested_statements</varname> causes nested
d125 2
a126 2
   you will need to add <literal>explain</> in
   <varname>custom_variable_classes</>.  Typical usage might be:
d133 2
a134 2
custom_variable_classes = 'explain'
explain.log_min_duration = '3s'
d143 1
a143 1
  postgres=# SET explain.log_min_duration = 0;
@


1.1
log
@Add auto-explain contrib module for automatic logging of the plans of
slow-running queries.

Takahiro Itagaki
@
text
@d1 1
a1 1
<!-- $PostgreSQL$ -->
d153 1
a153 1
  <programlisting>
d156 1
a156 1
            -&gt;  Hash Join  (cost=3.91..14.70 rows=81 width=0)
d158 3
a160 3
                  -&gt;  Seq Scan on pg_class  (cost=0.00..8.27 rows=227 width=4)
                  -&gt;  Hash  (cost=2.90..2.90 rows=81 width=4)
                        -&gt;  Seq Scan on pg_index  (cost=0.00..2.90 rows=81 width=4)
d165 1
@

