Chapter 23. pg_options

Note: Contributed by Massimo Dal Zotto

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. 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 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. New options and parameters must be defined in backend/utils/misc/trace.c and backend/include/utils/trace.h.

data/pg_options というオプションファイルには、 バックエンドがトレースメッセージを制御するための実行時用オプション やその他のバックエンドのチューニング用パラメータを記述します。バッ クエンドは SIGHUP シグナルを受け取ると、このファイルを再読み込みし ます。これにより、Postgres を再起動する ことなく、実行した状態のまま実行時用オプションを変更することができ ます。この事実はこのファイルを興味深いものにしています。このファイ ルでは、トレース用パッケージ( backend/utils/misc/trace.c )で使用されるデバ ッグ用フラグやバックエンドの動作を制御するための数値パラメータとい ったオプションを指定できます。新規のオプションやパラメータは backend/utils/misc/trace.cbackend/include/utils/trace.h 内で定義される必 要があります。

For example suppose we want to add conditional trace messages and a tunable numeric parameter to the code in file foo.c. All we need to do is to add the constant TRACE_FOO and OPT_FOO_PARAM into backend/include/utils/trace.h:

例えば、foo.c ファイルのコードに条件付トレース メッセージと調整用の数値パラメータを追加する場合を考えます。行なわな ければいけないことは、次のように backend/include/utils/trace.h 内に定数 TRACE_FOO と OPT_FOO_PARAM を追加し、

/* 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 */
/* trace.h ファイル */
enum pg_option_enum {
    TRACE_FOO,			/* foo 関数群のトレース */
    OPT_FOO_PARAM,		/* foo 調整用パラメータ */

    NUM_PG_OPTIONS              /* これはenumの項目の最後になければいけません */
and a corresponding line in backend/utils/misc/trace.c: そして、次のように上に相当する行を backend/utils/misc/trace.c に追加することです。

/* file trace.c */
static char *opt_names[] = {
    "foo",            		/* trace foo functions */
    "fooparam"         		/* foo tunable parameter */
/* trace.c ファイル*/
static char *opt_names[] = {
    "foo",            		/* foo 関数群のトレース */
    "fooparam"         		/* foo 調整用パラメータ */

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: この 2 ファイル内のオプションは正確に同じ順序でなければいけません。 これで foo ソースファイルで、新しいフラグを参照することができるよ うになります。

/* file foo.c */
/* foo.c ファイル */
#include "trace.h"
#define foo_param pg_options[OPT_FOO_PARAM]

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);

Existing files using private trace flags can be changed by simply adding the following code:

既存の非公式なトレースフラグを使用しているファイルも、次のコードを 単純に追加することで変更できます。

#include "trace.h"
/* int my_own_flag = 0; -- removed */
#define my_own_flag pg_options[OPT_MY_OWN_FLAG]
#include "trace.h"
/* int my_own_flag = 0; -- この行を削除する */
#define my_own_flag pg_options[OPT_MY_OWN_FLAG]

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 PostgresMain. Now we can set the foo_param and enable foo trace by writing values into the data/pg_options file:

バックエンドが起動する時、全ての pg_options は 0 に初期化されていま す。異なったデフォルト値を必要とする場合、 PostgresMain の初めに初期化用コードを追加しなけ ればなりません。こうして、以下のように data/pg_options ファイル内に値を書き込むことに よって、foo_param の設定と foo トレースを有効にすることができるよう になります。

# file pg_options

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.

新しいオプションは、新しくバックエンドが起動した時に読み込まれます。 実行中のバックエンドでオプションの変更を有効にするには、postmaster に対して SIGHUP シグナルを送信する必要があります。そのシグナルは自動 的に全てのバックエンドに対して送信されます。特定のバックエンドに対し てのみに、SIGHUP を直接送信することにより、そのバックエンドに対しての み変更を有効にすることもできます。

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

pg_options は、Postgres-T スイッチを以下のように使って指定することもでき ます。

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:

エラーやデバッグ用メッセージを表示するために使用される関数は、 syslog(2) 機能を使用するように設定できるよ うになりました。標準出力や標準エラーに表示されるメッセージに時刻 とバックエンドのプロセス番号を前につけた、以下のように形式で出力 されます。

#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.

この形式はログファイルの可読性を向上させており、どのバックエンドが いつ何をしたのかがユーザに判るようになっています。データベースに 関するエラーや問題の検出を行なう、ログを監視する簡単な awk や perl スクリプトを作成することや、トランザクション時間に関する統計情報の 演算を行なうことがより簡単にできるようになっています。

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.

メッセージを syslog に出力する時には LOG_LOCAL0 ファシリティが使 われます。syslog を使用するかどうかは syslog pg_option で設定でき ます。残念ながら、多くの関数は printf() を直 接使ってメッセージを標準出力や標準エラーに出力していますので、その 出力はsyslogに出力することも時刻情報を付与することもできません。 全ての出力を統一された形で制御できるように、全ての printf の呼び出 しを PRINTF に置換すること、また、もしそれが標準エラーへの出力であ る場合は EPRINTF に置換することですっきりすることはわかっているの ですが(まだ行なわれていません)。

The new pg_options mechanism is more convenient than defining new backend option switches because:

新しい pg_options という仕組みは、次のような理由で、新しいバックエン ドオプションを定義する方法に比べて、より使いやすくなっています。

The format of the pg_options file is as follows: pg_options ファイルの形式は以下の通りです。

# comment
option=integer_value  # set value for option
option                # set option = 1
option+               # set option = 1
option-               # set option = 0
# コメント
オプション=整数値  # オプション に値を設定します。
オプション    # オプション を 1 に設定します。
オプション+   # オプション を 1 に設定します。
オプション-   # オプション を 0 に設定します。

Note that keyword can also be an abbreviation of the option name defined in backend/utils/misc/trace.c. keyword は、 backend/utils/misc/trace.cで定義されたオプ ション名の省略形にもなることに注意して下さい。

Refer to The Administrator's Guide chapter on runtime options for a complete list of currently supported options.

現時点でサポートしている全オプションの一覧については、 管理者ガイド の実行時オプションの章を参照 して下さい。

Some of the existing code using private variables and option switches has been changed to make use of the pg_options feature, mainly in postgres.c. 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 Postgres command line and can have more tunable options with a unique place to put option values.

非公式な変数とオプションを使っていた既存のコード、主に postgres.c 内にあったものは、pg_options 機能 を使うように変更されています。既存の全てのコードをこの方法を使うよ うに変更したいと思っています。そうすれば、 Postgres のコマンドラインスイッチから多 くを取り除くことも、オプションの値を設定する一意な場所を持つ調整用 オプションをもっと多く持つこともできるようになります。