18.8. 錯誤報告和日志 · PostgreSQL 中文文檔 9.3

# 18.8\. 錯誤報告和日志 ## 18.8.1\. 在哪里記錄日志 `log_destination` (`string`) PostgreSQL支持多種記錄服務器日志的方法，包括stderr, csvlog和 syslog。在Windows里，還支持eventlog。把這個選項設置為一個逗號分隔的日志目標的列表。缺省是只記錄到stderr。這個選項只能在`postgresql.conf`文件或者服務器命令行設置。如果csvlog包含在`log_destination`中，日志項是用"逗號分隔"(CSV)格式的輸出，這便于加載日志到程序。參見[Section 18.8.4](#calibre_link-1424)獲取更多詳情。 [logging_collector](#calibre_link-1443)必須能夠產生CSV格式的日志輸出。 > **Note:** 在大多數Unix系統上，你將需要改變您的系統syslog守護進程的配置，以便充分利用`log_destination`的syslog選項。 PostgreSQL可以通過`LOCAL7`(參見[syslog_facility](#calibre_link-1444))記錄syslog設施`LOCAL0`，但缺省大多數平臺上syslog配置將忽略所有這樣的消息。你將需要添加類似于下面的信息： > > ``` > local0.* /var/log/postgresql > ``` > > 到syslog守護程序的配置文件中，使其工作。 > > 在Windows上，當您使用`log_destination`的`eventlog`選項，你應該注冊一個事件源及其操作系統作業庫，使Windows事件查看器可以有規則的顯示事件日志信息。參見[Section 17.11](#calibre_link-1240)獲取更多詳細信息。 `logging_collector` (`boolean`) 這個參數啟動_日志收集_，這是一個后臺進程，抓取發送到stderr的日志消息，并會將他們重定向到日志文件。這個方法通常比記錄到syslog更有用，因為有些消息類型可能不會出現在syslog輸出中 (一個常見的例子是動態連接失敗的消息；另外一個是通過腳本比如`archive_command` 產生的錯誤消息。）這個值只能在服務器啟動的時候設置。 > **Note:** 不使用日志收集器可以登錄到stderr; 無論服務器的stderr被定向到哪，則日志消息就定位到那里。然而，該方法是只適用于低日志卷，因為它沒有提供方便的方式來旋轉日志文件。另外，在某些平臺上不使用日志收集器可能會導致丟失或亂碼日志輸出，因為多個進程同時寫入同一個日志文件可能覆蓋彼此的輸出。 > **Note:** 日志收集器設計永遠不會丟失消息。這意味著在非常高的負載情況下，當收集器已經落后而試圖發送額外的日志消息的時候，封鎖服務器進程。與此相反，syslog更喜歡忽略消息，如果它無法寫入，這意味著它可能無法記錄這些消息，這種情況下，但它不會阻止該系統的其余部分。 `log_directory` (`string`) 在打開了`logging_collector`的時候，這個選項判斷日志文件在哪個目錄里創建。它可以聲明成絕對路徑，或者是與集群的數據目錄相對的路徑。這個選項只能在`postgresql.conf`文件里或者服務器命令行設置。 `log_filename` (`string`) 在打開了`logging_collector`的時候，這個選項設置所創建的日志文件的文件名。這個數值將被當作`strftime`模式看待。因此可以用`%`逃逸聲明隨時間而變的文件名。（注意，如果有任何時區相關`%`逃逸，由[log_timezone](#calibre_link-803)聲明的時區進行計算。）支持的`%`逃逸類似于Open Group上的[strftime](http://pubs.opengroup.org/onlinepubs/009695399/functions/strftime.html)規范列表中的。注意，不直接使用這個系統的strftime，所以特定平臺的（非標準）擴展不起作用。如果您沒有逃逸指定文件名，你應該計劃使用日志旋轉程序以避免最終填充整個磁盤。在8.4之前的版本中，如果沒有`%`的轉義符出現， PostgreSQL將追加新日志文件創建時間的時間戳，但是不再是這種情況了。如果啟用`log_destination`中的CSV格式輸出， `.csv`將追加時間戳日志文件名來創建CSV格式輸出的文件名。（如果`log_filename`以`.log`為結束，后綴代替）。在上面的例子情況下，CSV文件名是`server_log.1093827753.csv`。這個參數只能在`postgresql.conf`文件里或者服務器命令行上設置。 `log_file_mode` (`integer`) 在Unix系統上，當`logging_collector`已啟用時（在Microsoft Windows上將忽略此參數），此參數用于設置日志文件的權限。該參數值預期為通過`chmod`和`umask` 系統調用接受的格式指定的數字模式。（為了使用習慣八進制格式的數字必須以`0`(zero)開始）。默認的權限`0600`，只意味著服務器擁有者可以讀取或寫入日志文件。其他較普遍有用的設置是`0640`，讓擁有者組成員來讀取文件。但是請注意，為了充分使用這種設置，你需要改變[log_directory](#calibre_link-1445)到集群數據目錄之外的某處存儲這些文件。無論如何，使日志文件全局可讀是不明智的，因為它們可能包含敏感數據。這個參數可以在`postgresql.conf`文件或者服務器命令行上設置。 `log_rotation_age` (`integer`) 在打開了`logging_collector`的時候，這個選項設置一個獨立日志文件的最大生存期。在數值指定的分鐘過去之后，將創建一個新的日志文件。設置為零可以關閉以時間為基礎的新日志文件的創建。這個選項只能在`postgresql.conf`文件里或者服務器命令行設置。 `log_rotation_size` (`integer`) 在打開了`logging_collector`的時候，這個選項設置一個獨立的日志文件的最大尺寸。在數值指定的千字節寫入日志文件之后，將會創建一個新的日志文件。設置為零可以關閉以尺寸為基礎的新日志文件的創建。這個選項只能在`postgresql.conf`文件里或者服務器命令行上設置。 `log_truncate_on_rotation` (`boolean`) 在打開了`logging_collector`的時候，這個選項將導致PostgreSQL 覆蓋而不是附加到任何同名的現有日志文件上。不過，覆蓋只是發生在基于時間滾動而創建的新文件上，而不是在服務器啟動的時候或者以尺寸為基礎的滾動上。如果為 off ，將始終向已存在的文件結尾追加。比如，使用這個選項和類似`postgresql-%H.log`這樣的`log_filename`設置將導致生成 24個按小時生成的日志文件然后在這些文件上循環。這個選項只能在`postgresql.conf`文件里或者在服務器啟動的時候設置。例子：保留 7 天的日志，每天一個日志文件，叫做`server_log.Mon`, `server_log.Tue`等等，并且上周的日志會自動被這周的日志覆蓋。把`log_filename`設置為`server_log.%a`, 把`log_truncate_on_rotation`設置為`on`，并且把 `log_rotation_age`設置為`1440`。例子：保留 24 小時的日志，每小時一個日志，但是如果日志文件尺寸大于 1GB 也旋轉日志。把`log_filename`設置為`server_log.%H%M`, `log_truncate_on_rotation`設置為`on`, `log_rotation_age`設置為`60`并且把 `log_rotation_size`設置為`1000000`。在`log_filename`里包含`%M` 允許任何尺寸驅動的旋轉選取一個和開始的文件名同小時數但是名字不同的文件。 `syslog_facility` (`enum`) 如果向syslog進行記錄，那么這個選項判斷要使用的syslog"設施"。你可以從`LOCAL0`, `LOCAL1`, `LOCAL2`, `LOCAL3`, `LOCAL4`, `LOCAL5`, `LOCAL6`, `LOCAL7`中選擇。缺省是`LOCAL0`。又見你的系統的syslog守護進程文檔。這個選項只能在`postgresql.conf`文件里或者服務器啟動的時候設置。 `syslog_ident` (`string`) 如果向syslog進行記錄，這個選項決定用于在syslog日志中標識PostgreSQL的程序名。缺省是`postgres`。這個選項只能在`postgresql.conf`文件里或者服務器啟動的時候設置。 `event_source` (`string`) 當啟用記錄event log時，此參數確定用于識別PostgreSQL消息日志的程序名稱。缺省是`PostgreSQL`。該參數只能在`postgresql.conf`文件或者服務器命令行上設置。 ## 18.8.2\. 什么時候記錄日志 `client_min_messages` (`enum`) 這個選項控制哪些信息發送到客戶端。有效的數值是`DEBUG5`, `DEBUG4`, `DEBUG3`, `DEBUG2`, `DEBUG1`, `LOG`, `NOTICE`, `WARNING`, `ERROR`, `FATAL`, 和`PANIC`。每個級別包含所有它后面的級別，級別越靠后，發送的信息越少。缺省是`NOTICE`。需要注意的是這里的`LOG`和`log_min_messages`里的級別不同。 `log_min_messages` (`enum`) 控制寫到服務器日志里的信息的詳細程度。有效值是`DEBUG5`, `DEBUG4`, `DEBUG3`, `DEBUG2`, `DEBUG1`, `INFO`, `NOTICE`, `WARNING`, `ERROR`, `LOG`, `FATAL`和 `PANIC`。每個級別都包含它后面的級別。越靠后的數值發往服務器日志的信息越少。缺省是`WARNING`。需要注意的是這里的`LOG`和`client_min_messages`里的級別不同。只有超級用戶可以修改這個設置。 `log_min_error_statement` (`enum`) 控制在服務器日志里輸出哪一條導致錯誤條件的SQL語句。所有導致一個特定級別(或者更高級別)錯誤的 SQL 語句都要被記錄。有效的值有`DEBUG5`, `DEBUG4`, `DEBUG3`, `DEBUG2`, `DEBUG1`, `INFO`, `NOTICE`, `WARNING`, `ERROR`, `LOG`, `FATAL`和`PANIC`。缺省是`ERROR`，表示所有導致錯誤、日志信息，致命錯誤、恐慌的SQL語句都將被記錄。設置為`PANIC`表示把這個特性關閉。只有超級用戶可以改變這個設置。 `log_min_duration_statement` (`integer`) 如果某個語句的持續時間大于或者等于這個毫秒數，那么在日志行上記錄該語句及其持續時間。設置為零將打印所有查詢和他們的持續時間。設置為-1(缺省值)關閉這個功能。比如，如果你把它設置為`250ms`，那么所有運行時間等于或者超過 250ms 的 SQL 語句都會被記錄。打開這個選項可以很方便地跟蹤需要優化的查詢。只有超級用戶可以改變這個設置。對于使用擴展查詢協議的客戶端，語法分析、邦定、執行每一步所花時間都分別記錄。 > **Note:** 當此選項與[log_statement](#calibre_link-1446)同時使用時，已經被`log_statement`記錄的語句文本不會被重復記錄。如果沒有使用syslog的話，推薦使用[log_line_prefix](#calibre_link-1054)記錄 PID 或會話ID，這樣就可以使用它們將語句消息連接耗時消息。 [Table 18-1](#calibre_link-1447)解釋了PostgreSQL使用的信息嚴重程度。如果日志輸出發送到syslog或者Windows的 eventlog，則嚴重程度如下表所示。 **Table 18-1\. 信息嚴重級別** | 嚴重級別 | 用法 | syslog | eventlog | | --- | --- | --- | --- | | `DEBUG1..DEBUG5` | 提供開發人員使用的連續更多詳細信息 | `DEBUG` | `INFORMATION` | | `INFO` | 提供用戶隱含要求的信息，比如在`VACUUM VERBOSE`過程輸出的信息。 | `INFO` | `INFORMATION` | | `NOTICE` | 提供可能對用戶有幫助的信息，比如，長標識符的截斷 | `NOTICE` | `INFORMATION` | | `WARNING` | 提供可能問題的警告，比如在事務塊范圍之外的`COMMIT` | `NOTICE` | `WARNING` | | `ERROR` | 報告導致當前命令退出的錯誤。 | `WARNING` | `ERROR` | | `LOG` | 報告一些管理員感興趣的信息，比如，檢查點活躍性。 | `INFO` | `INFORMATION` | | `FATAL` | 報告導致當前會話終止的錯誤。 | `ERR` | `ERROR` | | `PANIC` | 報告導致所有數據庫會話退出的錯誤。 | `CRIT` | `ERROR` | ## 18.8.3\. 記錄什么 `application_name` (`string`) 該`application_name`可以是小于`NAMEDATALEN`字符（標準構建64個字符）的任何字符串。它通常是由應用程序連接到服務器設置。該名稱將顯示在`pg_stat_activity`視圖中并包含在CSV格式的日志項中。它也可以被包括在通過[log_line_prefix](#calibre_link-1054)參數的常規日志項中。只有可打印的ASCII字符可能用在`application_name`值中。其它字符會用問號(`?`)代替。 `debug_print_parse` (`boolean`) `debug_print_rewritten` (`boolean`) `debug_print_plan` (`boolean`) 這些選項打開各種調試輸出。當設置，它們打印生成的解析樹，查詢重寫輸出，或每個執行查詢的執行計劃。這些消息在`LOG`消息級別發出的，所以默認情況下它們會出現在服務器日志中，但不會被發送到客戶端。您可以通過調整[client_min_messages](#calibre_link-1448)和/或 [log_min_messages](#calibre_link-1449)改變。這些參數缺省都是關閉的。 `debug_pretty_print` (`boolean`) 當設置時，`debug_pretty_print`縮進`debug_print_parse`, `debug_print_rewritten`或者`debug_print_plan`產生的消息，這樣更加可讀，但是，當關閉它時，比"緊湊型"格式更長的輸出，缺省是打開的。 `log_checkpoints` (`boolean`) 導致檢查點和重啟點被記錄在服務器日志中。一些統計都包含在日志信息中，包括緩沖區寫入數量和編寫它們的花費的時間。這些參數只能在`postgresql.conf`文件或者服務器命令行上設置，缺省是off。 `log_connections` (`boolean`) 導致記錄到服務器的每個嘗試連接，以及成功完成客戶端認證。該參數在會話開始之后不能改變，缺省是off。 > **Note:** 某些客戶端程序，如psql當確定是否需要密碼的時候，企圖連接兩次。所以復制"連接收到"的消息不一定表示有問題。 `log_disconnections` (`boolean`) 這個選項類似`log_connections`，但是在會話結束的時候在服務器日志里輸出一行。并且包含會話持續時間。缺省是關閉的。這個參數在會話開始之后不能被改變。 `log_duration` (`boolean`) 記錄每個已完成語句的持續時間。默認值是`off`。只有超級用戶可以改變這個設置。對于使用擴展查詢協議的客戶端，語法分析、邦定、執行每一步所花時間都分別記錄。 > **Note:** 設置為0時該選項與[log_min_duration_statement](#calibre_link-1450) 的不同之處在于`log_min_duration_statement` 強制記錄查詢文本。但是這個選項不可以。因此，如果`log_duration`為`on`并且`log_min_duration_statement` 大于零將記錄所有持續時間，但是僅記錄那些超過閾值的語句。這可以用于在高負載情況下搜集統計信息。 `log_error_verbosity` (`enum`) 控制記錄的每條信息寫到服務器日志里的詳細程度。有效的值是`TERSE`,`DEFAULT`和`VERBOSE`，逐個向顯示的信息里增加更多的字段。`TERSE`包含 `DETAIL`的記錄, `HINT`,`QUERY`和`CONTEXT`錯誤信息。 `VERBOSE`輸出包含`SQLSTATE`錯誤代碼 (參見[Appendix A](#calibre_link-120))以及源代碼文件名稱，函數名稱，以及產生錯誤的行數。只有超級用戶可以改變這個設置。 `log_hostname` (`boolean`) 缺省時，連接日志只記錄所連接主機的IP地址。打開這個選項導致同時記錄主機名。請注意，這樣有可能帶來一些不可忽略的性能損失(取決于你的名字解析的設置)。這個選項只能在`postgresql.conf`文件里或者服務器命令行設置。 `log_line_prefix` (`string`) 這是一個`printf`風格的字符串，在日志的每行開頭輸出。 `%`字符開始"轉義序列"被如下所述狀態信息替換。無法識別的轉義被忽略。其它字符都直接拷貝到日志行中。有些逃逸只被會話進程識別，被后端進程忽略，比如主服務器進程。這個選項只能在`postgresql.conf`文件里或者服務器命令行設置。缺省是空字符串。 | 逃逸 | 效果 | 僅用于會話 | | --- | --- | --- | | `%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` | Time stamp without milliseconds | no | | `%m` | Time stamp with milliseconds | no | | `%i` | Command tag: type of session's current command | yes | | `%e` | SQLSTATE error code | no | | `%c` | Session ID: see below | no | | `%l` | Number of the log line for each session or process, starting at 1 | no | | `%s` | Process start time stamp | no | | `%v` | Virtual transaction ID (backendID/localXID) | no | | `%x` | Transaction ID (0 if none is assigned) | no | | `%q` | Produces no output, but tells non-session processes to stop at this point in the string; ignored by session processes | no | | `%%` | Literal `%` | no | `%c`逃逸打印唯一會話標識符，由兩個點號分隔的4字節的十六進制數字（沒有前導零）組成。數字是該過程的開始時間和進程ID，所以`%c`也可以用做一種打印這些項目的節約空間的方法。例如，為了從`pg_stat_activity`中生成會話標識符，使用這個查詢： ``` SELECT to_hex(EXTRACT(EPOCH FROM backend_start)::integer) || '.' || to_hex(pid) FROM pg_stat_activity; ``` > **Tip:** 如果你設置`log_line_prefix`的非空值，你應該經常使其最后一個字符是一個空格，提供來自日志行的其余部分的視覺分離。一個標點符號也可以使用。 > **Tip:** Syslog產生自身時間戳和進程ID信息，如果你記錄到syslog，所以你可能不想包括那些逃脫。 `log_lock_waits` (`boolean`) 當會話等待比[deadlock_timeout](#calibre_link-1451)獲得鎖更長的時間時，控制是否產生一個日志消息。決定如果鎖等待造成很差的性能，這是很有用處的。默認是`off`。 `log_statement` (`enum`) 控制記錄哪些SQL語句。有效的值是`none` (off), `ddl`, `mod`和 `all` (所有語句)。`ddl`記錄所有數據定義命令，比如`CREATE`, `ALTER`和`DROP`語句。 `mod`記錄所有`ddl`語句，加上數據修改語句`INSERT`,`UPDATE`, `DELETE`, `TRUNCATE`, 和`COPY FROM`。如果所包含的命令類型吻合，那么`PREPARE`, `EXECUTE`和 `EXPLAIN ANALYZE`語句也同樣被記錄。對于使用擴展查詢協議的客戶端，記錄發生在接受到擴展信息并包含邦定參數(內置單引號要雙寫)的時候。缺省是`none`。只有超級用戶可以改變這個設置。 > **Note:** 即使設置了`log_statement` = `all`，包含簡單語法錯誤的語句也不會被記錄。因為僅在完成基本的語法分析并確定了語句類型之后才記錄日志。在使用擴展查詢協議的情況下，在執行階段之前(語法分析或規劃階段)同樣不會記錄。將`log_min_error_statement`設為`ERROR`或更低才能記錄這些語句。 `log_temp_files` (`integer`) 控件的臨時文件名稱和大小。臨時文件可以創建的分類，哈希，和臨時的查詢結果。當它被刪除時，一個日志項有利于每個臨時文件。零值記錄所有臨時文件的信息，同時正值記錄文件大小大于或等于千字節指定數量。默認設置是-1，禁用這樣的日志。只有超級用戶可以更改此設置。 `log_timezone` (`string`) 設置用于寫入服務器日志的時間戳的時區。不像[TimeZone](#calibre_link-793)，這個值是簇范圍，因此，所有會話將持續報告時間戳。默認值`GMT`，但這通常被 `postgresql.conf`覆蓋；initdb 將安裝與其系統環境一致的設置。參見[Section 8.5.3](#calibre_link-792)獲取更多信息。這個參數只能在`postgresql.conf`文件或者服務器命令行上進行。 ## 18.8.4\. 使用CSV-格式日志輸出在`log_destination`列表中包含`csvlog` 提供了一種便捷的方式導入日志文件到一個數據庫表。此選項在逗號分隔值(CSV)中發出日志行，這些列為： time stamp with milliseconds, user name, database name, process ID, client host:port number, session ID, per-session line number, command tag, session start time, virtual transaction ID, regular transaction ID, error severity, SQLSTATE code, error message, error message detail, hint, 導致錯誤的內部查詢（如果有），字符計算錯誤位置，包含錯誤文本，導致錯誤的用戶查詢（如果有并且通過`log_min_error_statement`啟動），字符計算錯誤位置。其中有PostgreSQL源代碼錯誤的位置（如果`log_error_verbosity`設置為`verbose`），以及應用程序的名稱。這是一個用于存儲CSV格式的日志輸出樣本表定義： ``` CREATE TABLE postgres_log ( log_time timestamp(3) with time zone, user_name text, database_name text, process_id integer, connection_from text, session_id text, session_line_num bigint, command_tag text, session_start_time timestamp with time zone, virtual_transaction_id text, transaction_id bigint, error_severity text, sql_state_code text, message text, detail text, hint text, internal_query text, internal_query_pos integer, context text, query text, query_pos integer, location text, application_name text, PRIMARY KEY (session_id, session_line_num) ); ``` 使用`COPY FROM`命令，將日志文件導入到這個表中： ``` COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv; ``` 你需要做幾件事情簡化導入CSV日志文件： 1. 設置`log_filename`和 `log_rotation_age`為你的日志文件提供一個一致的，可預見的命名方式。這讓你預測哪些文件的名稱以及獨立日志文件是完整的，因此可以準備導入。 2. 設置`log_rotation_size`為0以禁用基于大小的日志旋轉，因為它很難預測日志文件名。 3. 設置`log_truncate_on_rotation`到`on`，以致于舊的日志數據不與同一文件的新數據混合。 4. 上面表定義包括主密鑰規范。這是為了防止意外導入相同的有用信息兩次。 `COPY`命令要求所有的數據一次導入，所以任何錯誤都將導致整個導入過程失敗。如果你導入部分日志文件，當它完成時，然后再導入該文件，主鍵沖突會導致導入過程失敗。等待直到日志是完整的，并且導入之前關閉。該程序也將防止意外導入尚未完全寫入的局部行，這也將導致`COPY`失敗。