Release History
Requirements

Introduction

Quick onboard

Deployment

Data Modeling

Connecting

Write data

Migration

Query

Operations and Maintenance

Performance Tuning

Troubleshooting

Reference Guide

SQL Reference

FAQ

Error Reporting and Logging Parameters

This document describes the system configuration parameters in the Error Reporting and Logging category.

Note!
To ensure system stability and security, manually modifying these parameters should be done with caution.


Where to Log

event_source

When logging to the event log is enabled, this parameter determines the program name used to identify YMatrix messages in the log.

Data Type Default Value Setting Scope
string PostgreSQL segments; system; restart

logging_collector

Enables the log collector, a background process that captures log messages sent to stderr and redirects them into log files.

  • This method is generally more useful than logging to syslog, as certain message types (e.g., dynamic linker errors, errors from scripts like syslog) do not appear in archive_command output.
  • This parameter can only be set at server startup.
  • Note: Logging directly to stderr without the log collector is possible. In this case, log messages go only to wherever the server's stderr is directed. However, this approach suits only low-volume logging, as it lacks log rotation capabilities. On some platforms, concurrent writes by multiple processes to the same log file may result in lost or scrambled output when the log collector is not used.
  • Note: The log collector never drops messages. Under extreme load, if server processes attempt to send more log messages while the collector is lagging, they may be blocked. In contrast, syslog may drop messages when unable to write, avoiding blocking but potentially losing some log entries.
Data Type Default Value Setting Scope
boolean on segments; system; restart

log_destination

YMatrix supports multiple methods for logging server messages. Set this parameter to a comma-separated list of desired log destinations.

  • If csvlog is included in log_destination, log entries are output in "comma-separated values" (CSV) format, which facilitates loading logs into applications. Enabling logging_collector is required for CSV log output.
  • When stderr or csvlog is included, a file named current_logfiles is created to record the current log file used by the log collector and its associated destination. This provides a convenient way to locate the active log file for a node instance. Example content:
    stderr log/postgresql.log
csvlog log/postgresql.csv

    The log_destination file is rebuilt when log rotation creates a new file or when current_logfiles is reloaded. It is deleted when log_destination does not include stderr or csvlog, or when the log collector is disabled.

  • Note: On most Unix systems, you must modify the syslog daemon configuration to use the log_destination option with syslog. YMatrix can log to syslog facilities LOCAL0 through LOCAL7 (see syslog_facility), but default configurations on most platforms discard such messages. Add a line like local0.* /var/log/postgresql to the syslog daemon configuration to enable logging.
  • On Windows, when using the log_destination option with eventlog, register an event source and its library in the operating system so that the Windows Event Viewer can clearly display event log messages.
Data Type Default Value Valid Values Setting Scope
string stderr stderr / csvlog / syslog / eventlog (on Windows) segments; system; reload

log_directory

When logging_collector is enabled, this parameter specifies the directory where log files are created.

  • It can be an absolute path or a path relative to the cluster's data directory.
Data Type Default Value Setting Scope
string log segments; system; reload

log_file_mode

Sets the creation mode for log files.

  • On Unix systems, when logging_collector is enabled, this parameter sets log file permissions (ignored on Microsoft Windows).
  • The default permission is 0600, meaning only the server owner can read or write the log file.
  • A common alternative is 0640, which allows group members of the owner to read the file. Note: This setting takes effect only if log_directory is set to a location outside the cluster data directory.
  • Note: Making log files world-readable is unwise, as they may contain sensitive data.
Data Type Default Value Valid Values Setting Scope
int 0600 0000 – 0777 segments; system; reload

log_filename

When logging_collector is enabled, this parameter sets the filename pattern for created log files.

  • The value is treated as a strftime pattern, allowing % escapes to create time-varying filenames (if timezone-independent % escapes are used, calculations occur in the timezone specified by log_timezone below). Supported % escapes are similar to those listed in the Open Group's strftime specification. Note: The system's strftime is not used directly, so platform-specific (non-standard) extensions will not work.
  • If no escapes are used, plan to use a log rotation tool to avoid filling the disk.
  • If CSV format output is enabled in log_destination, .csv is appended to timestamped log filenames for CSV output (if log_filename ends with .log, the suffix is replaced).
Data Type Default Value Setting Scope
string gpdb-%Y-%m-%d_%H%M%S.csv segments; system; reload

log_rotation_age

Determines how long (in minutes) YMatrix Database writes to an active log file.

  • After this period, the file is closed and a new one is created.
  • Set to 0 to disable time-based log file creation.
  • Default is 1440分钟, i.e., 1 day.
Data Type Default Value Valid Values Setting Scope
int 1440 0 – (INT_MAX/60) master; system; restart

log_rotation_size

Determines the size (in KB) that triggers log rotation.

  • When a log file reaches or exceeds this size, it is closed and a new one is created.
  • Set to zero to disable size-based log file creation.
  • Maximum value is INT_MAX. Invalid values revert to the default.
  • Default is 1048576KB, i.e., 1 GB.
Data Type Default Value Valid Values Setting Scope
int 1048576 0 – (INT_MAX/1024) master; system; restart

log_truncate_on_rotation

Truncate (overwrite) any existing log file with the same name instead of appending.

  • Truncation occurs only when a new file is opened due to time-based rotation, not at server startup or size-based rotation. If disabled, existing files are always appended.
  • Example: To keep 7 days of logs, naming daily files as gpseg-%H.log 的 log_filename, server_log.Mon, etc., and automatically overwrite last week's logs, set server_log.Tue to log_filename, server_log.%a to log_truncate_on_rotation, and on to log_rotation_age.
  • Example: To keep 24 hours of logs, one file per hour, but rotate when file size exceeds 1 GB, set 7d to log_filename, server_log.%H%M to log_truncate_on_rotation, on to log_rotation_age, and 1h to log_rotation_size. Including 10MB in log_filename allows size-driven rotations to use a different filename from the initial hourly one.
Data Type Default Value Setting Scope
boolean off master; system; restart

syslog_facility

When logging to syslog is enabled, this parameter determines the syslog facility to use.

Data Type Default Value Valid Values Setting Scope
enum LOCAL0 LOCAL0 / LOCAL1 / LOCAL2 / LOCAL3 / LOCAL4 / LOCAL5 / LOCAL6 / LOCAL7 segments; system; reload

syslog_ident

When logging to syslog is enabled, this parameter determines the program name used to identify YMatrix messages in syslog.

Data Type Default Value Setting Scope
string postgres segments; system; reload

syslog_sequence_numbers

When logging to syslog and this setting is %M (default), each message is prefixed with an incrementing sequence number.

  • This avoids the "last message repeated N times" format used by many syslog implementations by default. In modern syslog implementations (e.g., rsyslog with on), suppressing duplicate messages is configurable, so this parameter may not be necessary.
  • To avoid duplicate messages, set this parameter to $RepeatedMsgReduction.
Data Type Default Value Setting Scope
boolean on segments; system; reload

syslog_split_messages

When logging to syslog is enabled, this parameter determines how messages are delivered.

  • When set to off (default), messages are split into lines, and long lines are segmented to fit within 1024 bytes, a typical limit in traditional syslog implementations.
  • When set to on, YMatrix server log messages are sent unmodified to the syslog service, which then handles large messages.
  • If syslog is ultimately written to a text file, both settings have similar effects, but off is preferred. Most syslog implementations cannot handle large messages or require special configuration. However, if syslog writes to another medium, keeping messages logically intact may be necessary and more useful.
Data Type Default Value Setting Scope
boolean on segments; system; reload


When to Log

gp_interconnect_debug_retry_interval

Specifies the interval (in seconds) for logging YMatrix database interconnect debug messages when the server configuration parameter on is set to gp_log_interconnect.

  • Log messages contain information about interconnect communication between YMatrix database Segment instance worker processes.
  • This information may help debug network issues between Segment instances.
Data Type Default Value Valid Values Setting Scope
int 10 1 – 4096 master; session; reload

log_min_duration_statement

Logs SQL statements and their durations in a single log line if the statement's execution time is greater than or equal to the specified value (in milliseconds).

  • Setting this to debug logs all statements and their durations.
  • 0 disables this feature.
  • For example, setting it to -1 logs all SQL statements running 250 ms or longer.
  • Enabling this option helps track unoptimized queries in applications.
Data Type Default Value Valid Values Setting Scope
int -1 -1 – INT_MAX master; session; reload; superuser

log_min_error_statement

Controls whether SQL statements causing error conditions are also logged in the server log.

  • Logs all SQL statements that cause errors at the specified level or higher.
  • Enabling this helps trace the source of errors appearing in the server log.
Data Type Default Value Valid Values Setting Scope
enum error debug5 / debug4 / debug3 / debug2 / debug1 / info / notice / warning / error / fatal / panic
Each level includes all subsequent levels
Higher levels result in fewer messages		 master; session; reload; superuser

log_min_messages

Controls which message levels are written to the server log.

  • Note: 250 has a different ranking in this parameter than in log.
Data Type Default Value Valid Values Setting Scope
enum warning debug5 / debug4 / debug3 / debug2 / debug1 / info / notice / warning / error / log / fatal / panic
Each level includes all subsequent levels
Higher levels result in fewer messages		 master; session; reload; superuser

log_statement_sample_rate

Sets the proportion of statements with duration exceeding client_min_messages that are logged.

  • Sampling is random; e.g., log_min_duration_statement means each statement has a 50% chance of being logged.
  • Default is 0.5, meaning all qualifying statements are logged. 1.0 disables sampled statement duration logging, equivalent to setting 0.0 to log_min_duration_sample.
  • Only superusers and users with appropriate -1 privileges can change this setting.
Data Type Default Value Valid Values Setting Scope
floating point 1.0 0.0 – 1.0 segments; session; reload; superuser

log_transaction_sample_rate

Sets the fraction of transactions for which all statements are logged, regardless of other conditions.

  • Applies to each new transaction, independent of statement duration.
  • SET means no additional transaction statements are logged. 0 means all statements in all transactions are logged.
  • This parameter helps track transaction samples.
  • Note: Like all statement-logging options, this may add significant overhead.
Data Type Default Value Valid Values Setting Scope
real 0.001 0.0 – 1.0 segments; session; reload; superuser

The following table explains the severity levels used by YMatrix. If log output is sent to syslog or Windows eventlog, severity levels are mapped as shown.

Severity Usage syslog eventlog
DEBUG1..DEBUG5 Increasingly detailed information for developers DEBUG INFORMATION
INFO Information implicitly requested by users, e.g., output from 1 INFO INFORMATION
NOTICE Potentially useful information for users, e.g., truncation hints for long identifiers NOTICE INFORMATION
WARNING Warnings about possible issues, e.g., VACUUM VERBOSE outside a transaction block NOTICE WARNING
ERROR Reports an error that aborts the current command WARNING ERROR
LOG Information of interest to administrators, e.g., checkpoint activity INFO INFORMATION
FATAL Reports an error that aborts the current session ERR ERROR
PANIC Reports an error that aborts all database sessions CRIT ERROR

optimizer_minidump

Greenplum's GPORCA optimizer generates COMMIT files to describe the optimization context of a given query.

  • The format of information in these files is not easily debuggable or suitable for troubleshooting. minidump files are located in the master data directory and follow this naming format: minidump.
  • A Minidump_date_time.mdp file contains the following query-related information:
    • Catalog objects, including data types, tables, operators, and statistics required by the optimizer
    • Internal representation of the query (DXL)
    • Internal representation of the plan formulated by the optimizer (DXL)
    • System configuration information passed to the optimizer, such as server configuration parameters, cost and statistics settings, and number of Segments
    • Stack trace of errors generated during query optimization
  • Setting this parameter to minidump generates a always for every query; set to minidump to minimize total optimization time.
Data Type Default Value Valid Values Setting Scope
enum onerror onerror / always master; session; reload


What to Log

application_name

Sets the application name for the client session.

  • For example, when connecting via psql, it is set to onerror.
  • Setting the application name allows it to be reported in log messages and statistics views.
Data Type Default Value Setting Scope
string master; session; reload

debug_pretty_print

Indents debug output to produce a more readable but longer format.

  • When enabled, psql indents output from debug_pretty_print, debug_print_parse, or debug_print_rewritten.
  • debug_print_plan or client_min_messages must be log_min_messages or lower.
  • This results in more readable but longer output than the "compact" mode used when the parameter is disabled.
Data Type Default Value Setting Scope
boolean on master; session; reload

debug_print_parse

For each executed query, prints the resulting parse tree.

  • DEBUG1 or client_min_messages must be log_min_messages or lower.
Data Type Default Value Setting Scope
boolean off master; session; reload

debug_print_plan

For each executed query, prints the YMatrix parallel query execution plan.

  • DEBUG1 or client_min_messages must be log_min_messages or lower.
  • When enabled, prints the generated parse tree, query rewrite output, or execution plan for each executed query. These messages are emitted at the DEBUG1 level and thus appear in the server log by default, but are not sent to the client.
Data Type Default Value Setting Scope
boolean off master; session; reload

debug_print_prelim_plan

For each executed query, prints the preliminary query plan.

  • log or client_min_messages must be log_min_messages or lower.
Data Type Default Value Setting Scope
boolean off master; session; reload

debug_print_rewritten

For each executed query, prints the query rewrite output.

  • DEBUG1 or client_min_messages must be log_min_messages or lower.
Data Type Default Value Setting Scope
boolean off master; session; reload

debug_print_slice_table

For each executed query, prints the query slice plan.

  • DEBUG1 or client_min_messages must be log_min_messages or lower.
Data Type Default Value Setting Scope
boolean off master; session; reload

gp_debug_linger

Specifies how long (in seconds) a YMatrix process lingers after a DEBUG1 error.

Data Type Default Value Valid Values Setting Scope
int 0 0 – 3600 master; session; reload

gp_log_format

Specifies the format of server log files.

  • If using fatal management mode, log files must be in gp_toolkit format.
Data Type Default Value Valid Values Setting Scope
enum csv csv / text segments; system; restart

gp_log_interconnect

Controls the amount of information about communication between YMatrix database Segment instance worker processes written to log files.

  • Log information is written to both Master and Segment instance logs.
  • Increasing log volume may affect performance and increase disk space usage.
Data Type Default Value Valid Values Setting Scope
enum terse terse / off / verbose / debug master; session; reload

gp_reraise_signal

If enabled, attempts to generate a core file when a fatal server error occurs.

Data Type Default Value Setting Scope
boolean off master; session; reload

log_checkpoints

Logs checkpoints and restart points in the server log.

  • Some statistics are also included, such as the number of buffers written and the time taken.
Data Type Default Value Setting Scope
boolean off segments; system; reload

log_connections

Outputs a line to the server log detailing each successful connection.

  • Only superusers can change this parameter at session start; it cannot be changed during a session.
  • Note: Some client programs (e.g., psql) may attempt to connect twice when requesting a password, so duplicate "received connection" messages do not necessarily indicate an error.
Data Type Default Value Setting Scope
boolean off segments; system; restart; superuser

log_disconnections

Outputs a line to the server log when a client session ends, including the session duration.

  • Only superusers can change this parameter at session start; it cannot be changed during a session.
Data Type Default Value Setting Scope
boolean off segments; system; restart; superuser

log_dispatch_stats

When set to CSV, adds a log message containing detailed information about statement dispatch.

Data Type Default Value Setting Scope
boolean off segments; system; restart

log_duration

Logs the duration of each completed statement that meets on.

  • For clients using the extended query protocol, durations of parse, bind, and execute steps are logged separately.
  • Note: The difference between enabling log_statement and setting log_duration to log_min_duration_statement is that exceeding 0 forces the query text to be logged, while this option does not. Thus, if log_min_duration_statement is log_duration and on is positive, all durations are logged, but only statements exceeding the threshold have their query text logged. This behavior helps collect statistics in high-load environments.
Data Type Default Value Setting Scope
boolean off master; session; reload; superuser

log_error_verbosity

Controls the amount of detail written to the server log for each message.

  • Each option adds more fields: log_min_duration_statement excludes DETAIL, HINT, QUERY, and CONTEXT error information. terse includes the SQLSTATE error code (see Appendix A), and the source code filename, function name, and line number where the error occurred.
Data Type Default Value Valid Values Setting Scope
enum default terse / default / verbose master; session; reload; superuser

log_hostname

By default, connection log messages show only the IP address of the connecting host.

  • Enabling this parameter also logs the hostname.
  • Note: Depending on your hostname resolution setup, this may cause significant performance overhead.
Data Type Default Value Setting Scope
boolean off master; system; restart

--- SPLIT ---

log_line_prefix

This is a printf-style string that is output at the beginning of each log line.

  • The % character starts an "escape sequence", which will be replaced with state information as described below. Unrecognized escapes are ignored.
  • Other characters are copied verbatim to the log line. Some escapes are recognized only by session processes and treated as empty by background processes such as the master server process.
  • Specifying a number between % and the option aligns the state information either left or right.
  • Negative values right-pad the state information with spaces to the minimum width, while positive values left-pad it. Padding improves readability of log files.
  • The default value is %m [%p], which logs the timestamp and process ID.
Data Type Default Value Setting Category
string %m [%p] segments; system; reload
Escape Effect Session Only
%a Application name Yes
%u User name Yes
%d Database name Yes
%r Remote host name or IP address, and remote port Yes
%h Remote host name or IP address Yes
%p Process ID No
%t Timestamp without milliseconds No
%m Timestamp with milliseconds No
%n Timestamp with milliseconds (as Unix timestamp) No
%i Command tag: type of the session's current command Yes
%e SQLSTATE error code No
%c Session ID: see below No
%l Log line number for each session or process, starting from 1 No
%s Process start timestamp No
%v Virtual transaction ID (backendID/localXID) No
%x Transaction ID (0 if not assigned) No
%q Produces no output, but tells non-session processes to stop at this point in the string; session processes ignore it No
%% Literal % No

The %c escape prints a quasi-unique session identifier composed of two 4-byte hexadecimal numbers (without leading zeros) separated by a dot. These numbers are the process start time and process ID. Thus, %c can also be used as a space-saving way to log these items. For example, to generate the session ID from %c, use this query:

SELECT to_hex(trunc(EXTRACT(EPOCH FROM backend_start))::integer) || '.' ||
       to_hex(pid)
FROM pg_stat_activity;
  • Note: If you set log_line_prefix to a non-empty value, you should usually make its last character a space to visually separate it from the rest of the log line. Punctuation may also be used.
  • Note: syslog generates its own timestamp and process ID information. Therefore, if logging to syslog, you may not want to include these escape sequences.
  • Note: The log_line_prefix escape is useful when including information available only in a session (backend) context, such as the user name or database name. For example: %u@%d %r %m [%p].

log_lock_waits

Controls whether a log message is generated when a session waits longer than deadlock_timeout to acquire a lock.

  • This helps identify performance issues caused by lock waits.
  • The deadlock_timeout value must be greater than or equal to 1ms.
Data Type Default Value Setting Category
boolean off segments; session; reload; superuser

log_replication_commands

Causes each replication command to be logged in the server log.

Data Type Default Value Setting Category
boolean off segments; session; reload; superuser

log_statement

Controls which SQL statements are logged.

  • ddl logs all data definition commands, such as CREATE, ALTER, and DROP commands.
  • mod logs all DDL statements, plus data modification statements such as INSERT, UPDATE, DELETE, TRUNCATE, and COPY FROM.
  • If the included command is of the appropriate type, CREATE and ALTER statements are also logged.
  • all logs all statements.
  • For clients using the extended query protocol, log entries are generated upon receiving an Execute message and include the values of bound parameters (any embedded single quotes are doubled).
  • Note: Even with log_statement = all, statements containing simple syntax errors are not logged. This is because log messages are emitted only after basic parsing is complete and the statement type is determined. For the extended query protocol, statements that fail before the execution stage (e.g., during parse analysis or planning) are not logged. Set log_min_error_statement to error (or lower) to log such statements.
Data Type Default Value Valid Values Setting Category
enum none none / ddl / mod / all master; session; reload; superuser

log_temp_files

Controls logging of temporary file names and sizes.

  • Temporary files may be created for sorting, hashing, and storing temporary query results.
  • If enabled, a log entry is generated when each temporary file is deleted.
  • If set to -1, all temporary file information is logged. Positive values log only files with size greater than or equal to the specified amount.
  • The default value is -1, which disables logging.
Data Type Default Value Valid Values Setting Category
int -1 -1 ~ INT_MAX segments; system; restart; superuser

log_timezone

Sets the time zone to use when writing timestamps to log files.

  • Unlike TimeZone, this value is system-wide, so all sessions will report timestamps consistently.
Data Type Default Value Setting Category
string Asia/Shanghai segments; system; restart


Process Title

These parameters control how server processes modify their process titles. Process titles can typically be viewed using programs such as ps or the process browser on Windows.

cluster_name

Sets the name that identifies this database cluster (instance) for various purposes. This cluster name appears in the process title of all server processes within the cluster.

  • Additionally, it serves as the default application name for standby connections. (See synchronous_standby_names)
  • The name can be any string up to NAMEDATALEN characters (64 characters in standard builds).
  • Only printable ASCII characters are allowed in this parameter value. Other characters are replaced with a question mark (?).
  • If this parameter is set to an empty string '' (the default), no name is displayed.
  • This parameter can only be set at server startup.
Data Type Default Value Setting Category
string segments; system; restart

update_process_title

Enables updating of the process title, which updates every time the server receives a new SQL command.

  • On most platforms, this setting defaults to on, but due to higher overhead on Windows, it defaults to off on that platform.
Data Type Default Value Setting Category
boolean on segments; session; reload
← Previous
Client connection defaults
Next →
Resource consumption