Log Reference

Log Overview

During database running, a large number of logs are generated, including write-ahead logs (WALs, also called Xlogs) for ensuring database security and reliability and run logs and operation logs for daily database maintenance. If the database is faulty, you can refer to these logs to locate the fault and restore the database.

Log Type

The following table describes details about log types.

Table 1 Log types

Type	Description
System log	Logs generated during database running. They are used to record abnormal process information.
Operation log	Logs generated when a client tool (such as gs_guc) is operating databases.
Trace log	After the database instance on which the trace function is enabled is specified using the gstrace tool, a large number of trace logs are recorded. They are used to analyze database exceptions.
Black box log	Logs generated when the database system breaks down. You can analyze the process context when the fault occurs based on the heap and stack information in the logs to facilitate fault locating. A black box dumps stack, heap, and register information about processes and threads when a system breaks down.
Audit log	Logs used to record some of the database user operations after the database audit function is enabled.
WAL	Logs used to restore a damaged database. They are also called redo logs. You are advised to routinely back up WALs.
Performance log	Logs used to record the status of physical resources and the performance of access to external resources (such as disks).

System Log

System logs include those generated by database nodes when openGauss is running, and those generated when openGauss is deployed. If an error occurs during openGauss running, you can locate the cause and troubleshoot it based on system logs.

Log Storage Directory

The run logs of database nodes are stored in the corresponding folders in the /var/log/gaussdb/username/pg_log directory.

Logs generated during the installation and uninstallation of openGauss are stored in the same directory as the installation and uninstallation script.

Log Naming Rules

The name format of database node run logs is:
postgresql-creation time.log
By default, a new log file is generated at 0:00 every day, or when the size of the latest log file exceeds 16 MB or a database instance (database node) is restarted.
The name formats of CM run logs are:
- cm_agent logs: cm_agent-creation time.log, cm_agent-creation time-current.log, system_call-creation time.log, and system_call-creation time-current.log
- cm_server logs: cm_server-creation time.log, cm_servercreation time-current.log, key_event-creation time.log, and key_event-creation time-current.log
- om_monitor logs: om_monitor-creation time.log and om_monitor-creation time-current.log
Logs whose names do not contain current are historical log files. Logs whose names contain current are current log files. When a process is called for the first time, a log file whose name contains current is created. If the size of this file exceeds 16 MB, the file is renamed in the historical log file name format, and a new log file is generated at the current time point.

Log Content Description

Content of a line in a database node log:
Date+Time+Time zone+Username+Database name+Session ID+Log level+Log content
By default, a line in a cm_agent, cm_server, om_monitor log is arranged in the following format:
Time+Time zone+Session ID+Log content
The SYSTEM_CALL log records tool commands called by cm_agent.
By default, a line in a key_event log is arranged in the following format: Time+Thread ID+Thread name:Key event type+Arbitration object instance ID+Arbitration details

Operation Log

Operation logs are generated when database tools are used by a database administrator or called by openGauss. If openGauss is faulty, you can backtrack user operations on the database and reproduce the fault based on the operation logs.

Log Storage Directory

The default path is $GAUSSLOG/bin. If the environmental variable $GAUSSLOG does not exist or its value is empty, the log information generated for a tool will be displayed, but not recorded in the log file of the tool.

Log Naming Rules

The log file name format is as follows:

tool name-log creation time.log
tool name-log creation time-current.log

tool name-log creation time.log is a historical log file, and tool name-log creation time-current.log is a current log file.

If the size of a log file exceeds 16 MB, the next time the tool is called, the log file is renamed in the historical log file name format, and a new log file is generated at the current time point.

For example, gs_guc-2015-01-16_183728-current.log is renamed as gs_guc-2015-01-16_183728.log, and gs_guc-2015-01-17_142216-current.log is generated.

Maintenance Suggestions

You are advised to dump expired logs periodically to save disk space and prevent important logs from being lost.

Audit Log

After the audit function is enabled, a large number of audit logs will be generated, which occupy large storage space. You can customize an audit log maintenance policy based on the size of available storage space.

For details, see Maintaining Audit Logs.

WAL

In a system using write-ahead logs (WALs or Xlogs), all data file modifications are written to a log before they are applied. That is, the corresponding log must be written into a permanent memory before a data file is modified. You can use WALs to restore openGauss if the system crashes.

Log Storage Directory

Take a DN as an example. Its WALs are stored in the /gaussdb/data/data_dn**/pg_xlog** directory.

/gaussdb/data/data_dn is the data directory of a node in openGauss.

Log Naming Rules

Log files are saved as segment files. Each segment is 16 MB and is divided into multiple 8 KB pages. The name of a WAL file consists of 24 hexadecimal characters. Each name has three parts, with each part having eight hexadecimal characters. The first part indicates the time line, the second part indicates the log file identifier, and the third part indicates the file segment identifier. A time line starts from 1, and a log file identifier and a file segment identifier start from 0.

For example, the name of the first transaction log is 000000010000000000000000.

NOTE: The numbers in each part are used in ascending order in succession. Exhausting all available numbers takes a long time, and the numbers will start from zero again after they reach the maximum.

Log Content Description

The content of WALs depends on the types of recorded transactions. WALs can be used to restore a system after the system breaks down.

By default, openGauss reads WALs for system restoration during each startup.

Maintenance Suggestions

WALs are important for database restoration. You are advised to routinely back up WALs.

Performance Log

Performance logs focus on the access performance of external resources. Performance logs are used to record the status of physical resources and the performance of access to external resources (such as disks). When a performance issue occurs, you can locate the cause using performance logs, which greatly improves troubleshooting efficiency.

Log Storage Directory

The performance logs of the database node are stored in the directories under $GAUSSLOG/gs_profile.

Log Naming Rules

The name format of database node performance logs is:

postgresql-creation time.prf

By default, a new log file is generated at 0:00 every day, or when the latest log file exceeds 20 MB or a database instance (database node) is restarted.

Log Content Description

Content of a line in a database node log:

Host name+Date+Time+Instance name+Thread number+Log content

Log Translation

Logs of openGauss are written in English by default, but openGauss supports translating them into other languages including Chinese.

Procedure

Install gettext tools

Build openGauss with parameter --enable-nls

./configure --enable-nls="zh_CN" --gcc-version=7.3.0 CC=g++ CFLAGS='-O0' --prefix=$GAUSSHOME --3rd=$BINARYLIBS --enable-debug --enable-cassert --enable-thread-safety --with-readline --without-zlib && make && make install

Note that if no argument is given for option --enable-nls, openGauss will enable native language support for all languages it can support.

Make a translation
Usually there is no need to make a new translation text, except for building a new project.
```
make init-po
```
Update the translation
```
make update-po
```
Running this command creates a new translation file zh_CN.po.new based on the old file zh_CN.po. Check out new translations in zh_CN.po.new corresponding to newly added English texts. Some translations may be tagged with fuzzy, indicating these translations may be confusing, and requires manual revision. When the revision is done, rename file zh_CN.po.new to zh_CN.po, and run the following command:
```
make install
```
CAUTION： If the target language's grammar requires to swap mutiple format effectors' order, the older version of secure c that openGauss depends on does not support reordering format effectors in ways like %2$s %1$s. The latest version of secure c supports this kind of method, but you may need manually update the secure c in binarylibs to the latest version. If charsets specified by system environment variables LC_CTYPE, LC_MESSAGES, and the guc parameter lc_messages don't match with each other, it may lead to garbled codes in logs of main threads and backend threads. To avoid this, when detected mismatch between system environment variables LC_CTYPE, LC_MESSAGES, and the guc parameter lc_messages, openGauss will automatically disable its native language support. If the database is encoded by charsets other than utf-8, make sure the values of environment variable LC_CTYPE, LC_MESSAGES and guc parameter lc_messages match with it, otherwise user data that is not encoded by utf-8/ascii may also lead to garbled codes in logs. gettext will cache its translation result, whether the result meets the expectation or not. And later translation will reuse this cache as well. If the database is encoded by GBK, and when the user data encoded by GBK is written to logs, the co-existence of characters encoded by GBK and those encoded by UTF-8 may also lead to garbled codes. A guc parameter enable_nls is added to determine whether to enable native language support or not. You may set its value to off when native language support is significantly degrading the performance of openGauss (usually when logging at a low level with high concurrency). Note that for now the parameter can only control elog's translation.