PostgreSQL
Prev | Chapter 27. Runtime Environment | Next

# Using pg_options

> Note: Contributed by Massimo Dal Zotto

The optional file `data/pg_options` contains runtime options used by the backend to control trace messages and other backend tunable parameters. The file is re-read by a backend when it receives a SIGHUP signal, making thus possible to change run-time options on the fly without needing to restart Postgres. The options specified in this file may be debugging flags used by the trace package (`backend/utils/misc/trace.c`) or numeric parameters which can be used by the backend to control its behaviour.

All pg_options are initialized to zero at backend startup. New or modified options will be read by all new backends when they are started. To make effective any changes for all running backends we need to send a SIGHUP to the postmaster. The signal will be automatically sent to all the backends. We can also activate the changes only for a specific backend by sending the SIGHUP directly to it.

pg_options can also be specified with the -T switch of Postgres:

    postgres options -T "verbose=2,query,hostlookup-"

The functions used for printing errors and debug messages can now make use of the syslog(2) facility. Message printed to stdout or stderr are prefixed by a timestamp containing also the backend pid:

    #timestamp          #pid    #message
    980127.17:52:14.173 [29271] StartTransactionCommand
    980127.17:52:14.174 [29271] ProcessUtility: drop table t;
    980127.17:52:14.186 [29271] SIIncNumEntries: table is 70% full
    980127.17:52:14.186 [29286] Async_NotifyHandler
    980127.17:52:14.186 [29286] Waking up sleeping backend process
    980127.19:52:14.292 [29286] Async_NotifyFrontEnd
    980127.19:52:14.413 [29286] Async_NotifyFrontEnd done
    980127.19:52:14.466 [29286] Async_NotifyHandler done

This format improves readability of the logs and allows people to understand exactly which backend is doing what and at which time. It also makes easier to write simple awk or perl scripts which monitor the log to detect database errors or problem, or to compute transaction time statistics.

Messages printed to syslog use the log facility LOG_LOCAL0. The use of syslog can be controlled with the syslog pg_option. Unfortunately many functions call directly `printf()` to print their messages to stdout or stderr and this output can't be redirected to syslog or have timestamps in it. It would be advisable that all calls to printf would be replaced with the PRINTF macro and output to stderr be changed to use EPRINTF instead so that we can control all output in a uniform way.

The format of the `pg_options` file is as follows:

    # comment
    option=integer_value  # set value for option
    option                # set option = 1
    option+               # set option = 1
    option-               # set option = 0

Note that `keyword` can also be an abbreviation of the option name defined in `backend/utils/misc/trace.c`.

Example 27-1. pg_options File

For example my pg_options file contains the following values:

    verbose=2
    query
    hostlookup
    showportnumber

## Recognized Options

The options currently defined are:

all

  Global trace flag. Allowed values are:

  0

    Trace messages enabled individually

  1

    Enable all trace messages

  -1

    Disable all trace messages

verbose

  Verbosity flag. Allowed values are:

  0

    No messages. This is the default.

  1

    Print information messages.

  2

    Print more information messages.

query

  Query trace flag. Allowed values are:

  0

    Don't print query.

  1

    Print a condensed query in one line.

  4

    Print the full query.

plan

  Print query plan.

parse

  Print parser output.

rewritten

  Print rewritten query.

pretty_plan

  Pretty-print query plan.

pretty_parse

  Pretty-print parser output.

pretty_rewritten

  Pretty-print rewritten query.

parserstats

  Print parser statistics.

plannerstats

  Print planner statistics.

executorstats

  Print executor statistics.

shortlocks

  Currently unused but needed to enable features in the future.

locks

  Trace locks.

userlocks

  Trace user locks.

spinlocks

  Trace spin locks.

notify

  Trace notify functions.

malloc

  Currently unused.

palloc

  Currently unused.

lock_debug_oidmin

  Minimum relation oid traced by locks.

lock_debug_relid

  oid, if not zero, of relation traced by locks.

lock_read_priority

  Currently unused.

deadlock_timeout

  Deadlock check timer.

syslog

  syslog flag. Allowed values are:

  0

    Messages to stdout/stderr.

  1

    Messages to stdout/stderr and syslog.

  2

    Messages only to syslog.

hostlookup

  Enable hostname lookup in ps_status.

showportnumber

  Show port number in ps_status.

nofsync

  Disable fsync on a per-backend basis.

Prev | Home | Next
Starting postmaster | Up | Security