mirror of
https://git.postgresql.org/git/postgresql.git
synced 2025-02-17 19:30:00 +08:00
New programmer's information from Massimo Dal Zotto.
This commit is contained in:
Thomas G. Lockhart
parent
09128223be
commit
634a575f7c
543
doc/src/sgml/pg_options.sgml
Normal file
543
doc/src/sgml/pg_options.sgml
Normal file
@ -0,0 +1,543 @@
|
||||
<Chapter Id="pg-options">
|
||||
<DocInfo>
|
||||
<AuthorGroup>
|
||||
<Author>
|
||||
<FirstName>Massimo</FirstName>
|
||||
<Surname>Dal Zotto</Surname>
|
||||
</Author>
|
||||
</AuthorGroup>
|
||||
<Date>Transcribed 1998-10-16</Date>
|
||||
</DocInfo>
|
||||
|
||||
<Title>Using pg_options</Title>
|
||||
|
||||
<Para>
|
||||
<Note>
|
||||
<Para>
|
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
|
||||
</Para>
|
||||
</Note>
|
||||
|
||||
<Para>
|
||||
The optional file <filename>data/pg_options</filename> contains runtime
|
||||
options used by the backend to control trace messages and other backend
|
||||
tunable parameters.
|
||||
What makes this file interesting is the fact that it 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
|
||||
<productname>Postgres</productname>.
|
||||
The options specified in this file may be debugging flags used by the trace
|
||||
package (<filename>backend/utils/misc/trace.c</filename>) or numeric
|
||||
parameters which can be used by the backend to control its behaviour.
|
||||
New options and parameters must be defined in
|
||||
<filename>backend/utils/misc/trace.c</filename> and
|
||||
<filename>backend/include/utils/trace.h</filename>.
|
||||
|
||||
<Para>
|
||||
For example suppose we want to add conditional trace messages and a tunable
|
||||
numeric parameter to the code in file <filename>foo.c</filename>.
|
||||
All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into
|
||||
<filename>backend/include/utils/trace.h</filename>:
|
||||
|
||||
<programlisting>
|
||||
/* file trace.h */
|
||||
enum pg_option_enum {
|
||||
...
|
||||
TRACE_FOO, /* trace foo functions */
|
||||
OPT_FOO_PARAM, /* foo tunable parameter */
|
||||
|
||||
NUM_PG_OPTIONS /* must be the last item of enum */
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
and a corresponding line in <filename>backend/utils/misc/trace.c</filename>:
|
||||
|
||||
<programlisting>
|
||||
/* file trace.c */
|
||||
static char *opt_names[] = {
|
||||
...
|
||||
"foo", /* trace foo functions */
|
||||
"fooparam" /* foo tunable parameter */
|
||||
};
|
||||
</programlisting>
|
||||
|
||||
Options in the two files must be specified in exactly the same order.
|
||||
In the foo source files we can now reference the new flags with:
|
||||
|
||||
<programlisting>
|
||||
/* file foo.c */
|
||||
#include "trace.h"
|
||||
#define foo_param pg_options[OPT_FOO_PARAM]
|
||||
|
||||
int
|
||||
foo_function(int x, int y)
|
||||
{
|
||||
TPRINTF(TRACE_FOO, "entering foo_function, foo_param=%d", foo_param);
|
||||
if (foo_param > 10) {
|
||||
do_more_foo(x, y);
|
||||
}
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
Existing files using private trace flags can be changed by simply adding
|
||||
the following code:
|
||||
|
||||
<programlisting>
|
||||
#include "trace.h"
|
||||
/* int my_own_flag = 0; -- removed */
|
||||
#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
All pg_options are initialized to zero at backend startup. If we need a
|
||||
different default value we must add some initialization code at the beginning
|
||||
of <function>PostgresMain</function>.
|
||||
|
||||
Now we can set the foo_param and enable foo trace by writing values into the
|
||||
<filename>data/pg_options</filename> file:
|
||||
|
||||
<programlisting>
|
||||
# file pg_options
|
||||
...
|
||||
foo=1
|
||||
fooparam=17
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The new options will be read by all new backends when they are started.
|
||||
To make effective the 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.
|
||||
|
||||
<para>
|
||||
pg_options can also be specified with the <option>-T</option> switch of
|
||||
<productname>Postgres</productname>:
|
||||
|
||||
<programlisting>
|
||||
postgres <replaceable>options</replaceable> -T "verbose=2,query,hostlookup-"
|
||||
</programlisting>
|
||||
|
||||
<Para>
|
||||
The functions used for printing errors and debug messages can now make use
|
||||
of the <citetitle>syslog(2)</citetitle> facility. Message printed to stdout
|
||||
or stderr are prefixed by a timestamp containing also the backend pid:
|
||||
|
||||
<programlisting>
|
||||
#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
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
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.
|
||||
|
||||
<para>
|
||||
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 <function>printf()</function>
|
||||
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.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
The new pg_options mechanism is more convenient than defining new backend
|
||||
option switches because:
|
||||
|
||||
<ItemizedList Mark="bullet" Spacing="compact">
|
||||
<ListItem>
|
||||
<Para>
|
||||
we don't have to define a different switch for each thing we want to control.
|
||||
All options are defined as keywords in an external file stored in the data
|
||||
directory.
|
||||
</Para>
|
||||
</ListItem>
|
||||
|
||||
<ListItem>
|
||||
<Para>
|
||||
we don't have to restart <productname>Postgres</productname> to change
|
||||
the setting of some option.
|
||||
Normally backend options are specified to the postmaster and passed to each
|
||||
backend when it is started. Now they are read from a file.
|
||||
</Para>
|
||||
</ListItem>
|
||||
|
||||
<ListItem>
|
||||
<Para>
|
||||
we can change options on the fly while a backend is running. We can thus
|
||||
investigate some problem by activating debug messages only when the problem
|
||||
appears. We can also try different values for tunable parameters.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</ItemizedList>
|
||||
|
||||
The format of the <filename>pg_options</filename> file is as follows:
|
||||
|
||||
<programlisting>
|
||||
# <replaceable>comment</replaceable>
|
||||
<replaceable>option</replaceable>=<replaceable class="parameter">integer_value</replaceable> # set value for <replaceable>option</replaceable>
|
||||
<replaceable>option</replaceable> # set <replaceable>option</replaceable> = 1
|
||||
<replaceable>option</replaceable>+ # set <replaceable>option</replaceable> = 1
|
||||
<replaceable>option</replaceable>- # set <replaceable>option</replaceable> = 0
|
||||
</programlisting>
|
||||
|
||||
Note that <replaceable class="parameter">keyword</replaceable> can also be
|
||||
an abbreviation of the option name defined in
|
||||
<filename>backend/utils/misc/trace.c</filename>.
|
||||
</Para>
|
||||
|
||||
<Para>
|
||||
The options currently defined in
|
||||
<filename>backend/utils/misc/trace.c</filename> are the following:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
all
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Global trace flag. Allowed values are:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
0
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Trace messages enabled individually
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
1
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Enable all trace messages
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
-1
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Disable all trace messages
|
||||
|
||||
</variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
verbose
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Verbosity flag. Allowed values are:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
0
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
No messages. This is the default.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
1
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print information messages.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
2
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print more information messages.
|
||||
|
||||
</variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
query
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Query trace flag. Allowed values are:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
0
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Don't print query.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
1
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print a condensed query in one line.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
4
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print the full query.
|
||||
|
||||
</variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
plan
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print query plan.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
parse
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print parser output.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
rewritten
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print rewritten query.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
parserstats
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print parser statistics.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
plannerstats
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print planner statistics.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
executorstats
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Print executor statistics.
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
shortlocks
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Currently unused but needed to enable features in the future.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
locks
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Trace locks.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
userlocks
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Trace user locks.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
spinlocks
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Trace spin locks.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
notify
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Trace notify functions.
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
malloc
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Currently unused.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
palloc
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Currently unused.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
lock_debug_oidmin
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Minimum relation oid traced by locks.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
lock_debug_relid
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
oid, if not zero, of relation traced by locks.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
lock_read_priority
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Currently unused.
|
||||
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
deadlock_timeout
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Deadlock check timer.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
syslog
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
syslog flag. Allowed values are:
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term>
|
||||
0
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Messages to stdout/stderr.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
1
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Messages to stdout/stderr and syslog.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
2
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Messages only to syslog.
|
||||
|
||||
</variablelist>
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
hostlookup
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Enable hostname lookup in ps_status.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
showportnumber
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Show port number in ps_status.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
notifyunlock
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Unlock of pg_listener after notify.
|
||||
|
||||
<varlistentry>
|
||||
<term>
|
||||
notifyhack
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
Remove duplicate tuples from pg_listener.
|
||||
|
||||
</variablelist>
|
||||
|
||||
For example my pg_options file contains the following values:
|
||||
|
||||
<programlisting>
|
||||
verbose=2
|
||||
query
|
||||
hostlookup
|
||||
showportnumber
|
||||
</programlisting>
|
||||
|
||||
</Para>
|
||||
|
||||
|
||||
<Para>
|
||||
Some of the existing code using private variables and option switches has
|
||||
been changed to make use of the pg_options feature, mainly in
|
||||
<filename>postgres.c</filename>. It would be advisable to modify
|
||||
all existing code
|
||||
in this way, so that we can get rid of many of the switches on
|
||||
the <productname>Postgres</productname> command line
|
||||
and can have more tunable options
|
||||
with a unique place to put option values.
|
||||
</Para>
|
||||
|
||||
</Chapter>
|
||||
190
doc/src/sgml/signals.sgml
Normal file
190
doc/src/sgml/signals.sgml
Normal file
@ -0,0 +1,190 @@
|
||||
<chapter id="signals">
|
||||
<DocInfo>
|
||||
<AuthorGroup>
|
||||
<Author>
|
||||
<FirstName>Massimo</FirstName>
|
||||
<Surname>Dal Zotto</Surname>
|
||||
</Author>
|
||||
</AuthorGroup>
|
||||
<Date>Transcribed 1998-10-16</Date>
|
||||
</DocInfo>
|
||||
|
||||
<title><productname>Postgres</productname> Signals</title>
|
||||
|
||||
<Para>
|
||||
<Note>
|
||||
<Para>
|
||||
Contributed by <ULink url="mailto:dz@cs.unitn.it">Massimo Dal Zotto</ULink>
|
||||
</Para>
|
||||
</Note>
|
||||
|
||||
<para>
|
||||
<productname>Postgres</productname> uses the following signals for
|
||||
communication between the postmaster and backends:
|
||||
|
||||
<para>
|
||||
<table tocentry="1">
|
||||
<title><productname>Postgres</productname> Signals</title>
|
||||
<titleabbrev>Signals</titleabbrev>
|
||||
|
||||
<tgroup cols="2">
|
||||
<thead>
|
||||
<row>
|
||||
<entry>
|
||||
Signal
|
||||
<entry>
|
||||
<application>postmaster</application> Action
|
||||
<entry>
|
||||
Server Action
|
||||
|
||||
<tbody>
|
||||
<row>
|
||||
<entry>
|
||||
SIGHUP
|
||||
<entry>
|
||||
kill(*,sighup)
|
||||
<entry>
|
||||
read_pg_options
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGINT
|
||||
<entry>
|
||||
die
|
||||
<entry>
|
||||
cancel query
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGQUIT
|
||||
<entry>
|
||||
kill(*,sigterm)
|
||||
<entry>
|
||||
handle_warn
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGTERM
|
||||
<entry>
|
||||
kill(*,sigterm), kill(*,9), die
|
||||
<entry>
|
||||
die
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGPIPE
|
||||
<entry>
|
||||
ignored
|
||||
<entry>
|
||||
die
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGUSR1
|
||||
<entry>
|
||||
kill(*,sigusr1), die
|
||||
<entry>
|
||||
quickdie
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGUSR2
|
||||
<entry>
|
||||
kill(*,sigusr2)
|
||||
<entry>
|
||||
async notify (SI flush)
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGCHLD
|
||||
<entry>
|
||||
reaper
|
||||
<entry>
|
||||
ignored (alive test)
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGTTIN
|
||||
<entry>
|
||||
ignored
|
||||
<entry>
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGTTOU
|
||||
<entry>
|
||||
ignored
|
||||
<entry>
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGCONT
|
||||
<entry>
|
||||
dumpstatus
|
||||
<entry>
|
||||
|
||||
<row>
|
||||
<entry>
|
||||
SIGFPE
|
||||
<entry>
|
||||
<entry>
|
||||
FloatExceptionHandler
|
||||
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</table>
|
||||
|
||||
<note>
|
||||
<para>
|
||||
<quote>kill(*,signal)</quote> means sending a signal to all backends.
|
||||
</note>
|
||||
|
||||
<para>
|
||||
The main changes to the old signal handling are the use of SIGQUIT instead
|
||||
of SIGHUP to handle warns, SIGHUP to re-read the pg_options file and the
|
||||
redirection to all active backends of SIGHUP, SIGTERM, SIGUSR1 and SIGUSR2
|
||||
sent to the postmaster.
|
||||
In this way these signals sent to the postmaster can be sent
|
||||
automatically to all the backends without need to know their pids.
|
||||
To shut down postgres one needs only to send a SIGTERM to postmaster
|
||||
and it will stop automatically all the backends.
|
||||
|
||||
<para>
|
||||
The SIGUSR2 signal is also used to prevent SI cache table overflow
|
||||
which happens when some backend doesn't process SI cache for a long period.
|
||||
When a backend detects the SI table full at 70% it simply sends a signal
|
||||
to the postmaster which will wake up all idle backends and make them flush
|
||||
the cache.
|
||||
|
||||
<para>
|
||||
The typical use of signals by programmers could be the following:
|
||||
|
||||
<programlisting>
|
||||
# stop postgres
|
||||
kill -TERM $postmaster_pid
|
||||
</programlisting>
|
||||
|
||||
<programlisting>
|
||||
# kill all the backends
|
||||
kill -QUIT $postmaster_pid
|
||||
</programlisting>
|
||||
|
||||
<programlisting>
|
||||
# kill only the postmaster
|
||||
kill -INT $postmaster_pid
|
||||
</programlisting>
|
||||
|
||||
<programlisting>
|
||||
# change pg_options
|
||||
cat new_pg_options > $DATA_DIR/pg_options
|
||||
kill -HUP $postmaster_pid
|
||||
</programlisting>
|
||||
|
||||
<programlisting>
|
||||
# change pg_options only for a backend
|
||||
cat new_pg_options > $DATA_DIR/pg_options
|
||||
kill -HUP $backend_pid
|
||||
cat old_pg_options > $DATA_DIR/pg_options
|
||||
</programlisting>
|
||||
|
||||
</chapter>
|
||||
Loading…
Reference in New Issue
Block a user