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.c と backend/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]
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);
}
}
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 ... foo=1 fooparam=17
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 という仕組みは、次のような理由で、新しいバックエン ドオプションを定義する方法に比べて、より使いやすくなっています。
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.
制御したい事柄それぞれに異なるスイッチを定義する必要がありませ ん。全てのオプションは、data ディレクトリ内にある外部ファイル内 のキーワードとして定義されています。
we don't have to restart Postgres 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.
あるオプションの設定を変更するために Postgres を再起動する必要がありません。 通常、バックエンドオプションは postmaster に対してその起動時に指 定され、各バックエンドに渡されます。この段階でファイルから読み込 まれることになります。
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.
バックエンドが実行中の状態のままでオプションを変更することがで きます。このため、デバッグ用メッセージ出力を問題が発生した時に だけ有効にすることで、問題の究明ができるようになります。また、 調整用パラメータに対しても異なる値を試すこともできます。
# 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 のコマンドラインスイッチから多 くを取り除くことも、オプションの値を設定する一意な場所を持つ調整用 オプションをもっと多く持つこともできるようになります。