mirror of https://github.com/postgres/postgres
Thomas G. Lockhart
28 years ago
parent
09128223be
commit
634a575f7c
@ -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> |
||||
@ -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