Skip to main content
Version: 2.x

auto_explain

The auto_explain module logs the execution plans of slow statements automatically, without having to run EXPLAIN by hand.

In Apache Cloudberry, auto_explain takes effect only in regular sessions on the coordinator. When the library is loaded in a segment process or in a utility-mode connection, it does nothing and does not define its configuration parameters. Otherwise, it works like the PostgreSQL auto_explain module. With auto_explain.log_analyze enabled, the logged plan also includes the per-slice execution statistics collected from the segments.

Load the module​

auto_explain is built and installed by a default Apache Cloudberry build. It is a library, not an extension: it provides no SQL objects, and you do not run CREATE EXTENSION for it.

To load the module into a single session, run the following command as a superuser:

LOAD 'auto_explain';

To load it into all sessions, add auto_explain to session_preload_libraries or shared_preload_libraries. A change to shared_preload_libraries requires a restart of the cluster. Preloading lets you track slow queries whenever they happen, at the cost of some overhead for all queries.

Configuration parameters​

The module does nothing until auto_explain.log_min_duration is set to a value other than -1. Only superusers can change these parameters.

ParameterDescription
auto_explain.log_min_durationMinimum statement execution time, in milliseconds, above which the plan is logged. 0 logs all plans. -1 (the default) turns logging off.
auto_explain.log_analyzeLogs EXPLAIN ANALYZE output instead of EXPLAIN output.
auto_explain.log_buffersLogs buffer usage. Takes effect only when log_analyze is on.
auto_explain.log_walLogs WAL usage. Takes effect only when log_analyze is on.
auto_explain.log_timingCollects per-node timing. Takes effect only when log_analyze is on.
auto_explain.log_triggersIncludes trigger statistics. Takes effect only when log_analyze is on.
auto_explain.log_verboseLogs EXPLAIN VERBOSE output.
auto_explain.log_settingsLogs the modified configuration parameters that affect query planning.
auto_explain.log_formatOutput format: text, xml, json, or yaml.
auto_explain.log_levelLog level for the plan.
auto_explain.log_nested_statementsLogs statements that are run inside functions.
auto_explain.sample_rateFraction of statements to process in each session.

Example​

LOAD 'auto_explain';
SET auto_explain.log_min_duration = 0;
SET auto_explain.log_analyze = true;
SELECT count(*) FROM pg_class;

The plan of the SELECT statement is written to the coordinator log.

Module documentation​

See auto_explain in the PostgreSQL documentation for details about each configuration parameter.