5.7. Error Reporting and Logging

5.7.1. Where To Log

log_destination (string)

Pgpool-II supports two destinations for logging the Pgpool-II messages. The supported log destinations are stderr and syslog. You can also set this parameter to a list of desired log destinations separated by commas if you want the log messages on the multiple destinations.

       #for example to log on both syslog and stderr
       log_destination = 'syslog,stderr'
      

The default is to log to stderr only.

Note: On some systems you will need to alter the configuration of your system's syslog daemon in order to make use of the syslog option for log_destination. Pgpool-II can log to syslog facilities LOCAL0 through LOCAL7 (see syslog_facility), but the default syslog configuration on most platforms will discard all such messages. You will need to add something like:

	 local0.*    /var/log/pgpool.log
	

to the syslog daemon's configuration file to make it work.

This parameter can be changed by reloading the Pgpool-II configurations.

logging_collector (boolean)

This parameter enables the logging collector, which is a background process that captures log messages sent to stderr and redirects them into log files.

Note: It is possible to log to stderr without using the logging collector; the log messages will just go to wherever the server's stderr is directed. However, that method is only suitable for low log volumes, since it provides no convenient way to rotate log files.

This parameter can only be set at the Pgpool-II start.

logging_collector is not available prior to Pgpool-II V4.2.

log_directory (string)

When logging_collector is enabled, this parameter determines the directory in which log files will be created.

The default is /tmp/pgpool_logs.

This parameter can only be set at the Pgpool-II start.

log_filename (string)

When logging_collector is enabled, this parameter sets the file names of the created log files. The value is treated as a strftime pattern, so %-escapes can be used to specify time-varying file names. The supported %-escapes are similar to those listed in the Open Group's strftimespecification.

If you specify a file name without escapes, you should plan to use a log rotation utility to avoid eventually filling the entire disk.

The default is pgpool-%Y-%m-%d_%H%M%S.log.

This parameter can only be set at the Pgpool-II start.

log_file_mode (integer)

This parameter sets the permissions for log files when logging_collector is enabled. The parameter value is expected to be a numeric mode specified in the format accepted by the chmod and umask system calls.

Note: To use the customary octal format the number must start with a 0 (zero).

This parameter can only be set at the Pgpool-II start.

log_rotation_age (integer)

When logging_collector is enabled, this parameter determines the maximum amount of time to use an individual log file, after which a new log file will be created. If this value is specified without units, it is taken as minutes. The default is 24 hours.

Set to zero to disable time-based creation of new log files.

This parameter can only be set at the Pgpool-II start.

log_rotation_size (integer)

When logging_collector is enabled, this parameter determines the maximum size of an individual log file. After this many kilobytes have been emitted into a log file, a new log file will be created.

Set to zero to disable size-based creation of new log files.

This parameter can only be set at the Pgpool-II start.

log_truncate_on_rotation (boolean)

When logging_collector is enabled, this parameter will cause Pgpool-II to truncate (overwrite), rather than append to, any existing log file of the same name. However, truncation will occur only when a new file is being opened due to time-based rotation, not during the startup or size-based rotation. When off, pre-existing files will be appended to in all cases. For example, using this setting in combination with a log_filename like pgpool-%H.log would result in generating twenty-four hourly log files and then cyclically overwriting them.

This parameter can only be set at the Pgpool-II start.

syslog_facility (enum)

See also the documentation of your system's syslog daemon. When logging to syslog is enabled, this parameter determines the syslog "facility" to be used. You can choose from LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7; the default is LOCAL0. See also the documentation of your system's syslog daemon.

This parameter can be changed by reloading the Pgpool-II configurations.

syslog_ident (string)

When logging to syslog is enabled, this parameter determines the program name used to identify Pgpool-II messages in syslog logs. The default is pgpool.

This parameter can be changed by reloading the Pgpool-II configurations.

5.7.2. When To Log

client_min_messages (enum)

Controls which minimum message levels are sent to the client. Valid values are DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1, LOG, NOTICE, WARNING and ERROR. Each level includes all the levels that follow it. The default is NOTICE.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

log_min_messages (enum)

The default is WARNING. Controls which minimum message levels are emitted to log. Valid values are DEBUG5, DEBUG4, DEBUG3, DEBUG2, DEBUG1, INFO, NOTICE, WARNING, ERROR, LOG, FATAL, and PANIC. Each level includes all the levels that follow it. The default is WARNING.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

5.7.3. What To Log

log_statement (boolean)

Setting to on, prints all SQL statements to the log.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

log_per_node_statement (boolean)

Similar to log_statement, except that it print the logs for each DB node separately. It can be useful to make sure that replication or load-balancing is working.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

notice_per_node_statement (boolean)

Similar to log_per_node_statement, except that it prints the statement logs for each DB node separately as a NOTICE message. With the default client_min_messages setting (that is NOTICE), the log message will be printed on client's terminal as well. This is convenient for clients because it does not need to access Pgpool-II log file. Note that unlike log_per_node_statement, notice_per_node_statement does not print internal queries, (e.g., system catalog inquiry). This is because this feature is designed to be used for testing as well. As internal queries tend to be non-deterministic, printing them in testing is not helpful. For the same reason, backend process id is not printed.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

log_client_messages (boolean)

Setting to on, prints client messages to the log.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

log_hostname (boolean)

Setting to on, prints the hostname instead of IP address in the ps command result, and connection logs (when log_connections is on).

This parameter can be changed by reloading the Pgpool-II configurations.

log_connections (boolean)

Setting to on, prints all client connections from to the log.

This parameter can be changed by reloading the Pgpool-II configurations.

log_disconnections (boolean)

Setting to on, prints all client connection terminations to the log.

This parameter can be changed by reloading the Pgpool-II configurations.

log_pcp_processes (boolean)

Setting to on, enable logging about normal PCP Process fork and exit status. Default is on.

This parameter can be changed by reloading the Pgpool-II configurations.

log_error_verbosity (enum)

Controls the amount of detail emitted for each message that is logged. Valid values are TERSE, DEFAULT, and VERBOSE, each adding more fields to displayed messages. TERSE excludes the logging of DETAIL, HINT, QUERY and CONTEXT error information.

This parameter can be changed by reloading the Pgpool-II configurations. You can also use PGPOOL SET command to alter the value of this parameter for a current session.

log_line_prefix (string)

This is a printf-style string that is output at the beginning of each log line. % characters begin "escape sequences" that are replaced with information outlined below. All unrecognized escapes are ignored. Other characters are copied straight to the log line. Default is '%m: %a pid %p: ', which prints timestamp, application name and process id.

Table 5-6. log_line_prefix escape options

EscapeEffect
%a Application name. The initial value for child (session process) is "child". If Clients set application name (either in the startup message or by using SET command), application name will be changed accordingly. In other types of process, application name is a hard coded string. see Table 5-7.
%pProcess ID (PID)
%PProcess name
%tTime stamp without milliseconds
%mTime stamp with milliseconds
%dDatabase name
%uUser name
%lLog line number for each process
%%'%' character

Table 5-7. application names in various process

Process typeapplication name
mainmain
childchild
streaming replication delay check workersr_check_worker
watchdog heart beat senderheart_beat_sender
watchdog heart beat receiverheart_beat_receiver
watchdogwatchdog
watchdog life checklife_check
follow primary childfollow_child
watchdog utilitywatchdog_utility
pcp mainpcp_main
pcp childpcp_child
health check processhealth_check%d (%d is replaced with backend node id)
logger processlogger (Note that the application name "logger" will not be output to the log file managed by logger process)

This parameter can be changed by reloading the Pgpool-II configurations.