From cc8d41511721d25d557fc02a46c053c0a602fed0 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Mon, 1 Apr 2019 14:24:37 +0200 Subject: Unified logging system for command-line programs This unifies the various ad hoc logging (message printing, error printing) systems used throughout the command-line programs. Features: - Program name is automatically prefixed. - Message string does not end with newline. This removes a common source of inconsistencies and omissions. - Additionally, a final newline is automatically stripped, simplifying use of PQerrorMessage() etc., another common source of mistakes. - I converted error message strings to use %m where possible. - As a result of the above several points, more translatable message strings can be shared between different components and between frontends and backend, without gratuitous punctuation or whitespace differences. - There is support for setting a "log level". This is not meant to be user-facing, but can be used internally to implement debug or verbose modes. - Lazy argument evaluation, so no significant overhead if logging at some level is disabled. - Some color in the messages, similar to gcc and clang. Set PG_COLOR=auto to try it out. Some colors are predefined, but can be customized by setting PG_COLORS. - Common files (common/, fe_utils/, etc.) can handle logging much more simply by just using one API without worrying too much about the context of the calling program, requiring callbacks, or having to pass "progname" around everywhere. - Some programs called setvbuf() to make sure that stderr is unbuffered, even on Windows. But not all programs did that. This is now done centrally. Soft goals: - Reduces vertical space use and visual complexity of error reporting in the source code. - Encourages more deliberate classification of messages. For example, in some cases it wasn't clear without analyzing the surrounding code whether a message was meant as an error or just an info. - Concepts and terms are vaguely aligned with popular logging frameworks such as log4j and Python logging. This is all just about printing stuff out. Nothing affects program flow (e.g., fatal exits). The uses are just too varied to do that. Some existing code had wrappers that do some kind of print-and-exit, and I adapted those. I tried to keep the output mostly the same, but there is a lot of historical baggage to unwind and special cases to consider, and I might not always have succeeded. One significant change is that pg_rewind used to write all error messages to stdout. That is now changed to stderr. Reviewed-by: Donald Dong Reviewed-by: Arthur Zakirov Discussion: https://www.postgresql.org/message-id/flat/6a609b43-4f57-7348-6480-bd022f924310@2ndquadrant.com --- doc/src/sgml/ref/clusterdb.sgml | 11 +++++++++++ doc/src/sgml/ref/createdb.sgml | 11 +++++++++++ doc/src/sgml/ref/createuser.sgml | 11 +++++++++++ doc/src/sgml/ref/dropdb.sgml | 11 +++++++++++ doc/src/sgml/ref/dropuser.sgml | 11 +++++++++++ doc/src/sgml/ref/initdb.sgml | 11 +++++++++++ doc/src/sgml/ref/pg_basebackup.sgml | 6 ++++++ doc/src/sgml/ref/pg_checksums.sgml | 11 +++++++++++ doc/src/sgml/ref/pg_controldata.sgml | 11 +++++++++++ doc/src/sgml/ref/pg_dump.sgml | 11 +++++++++++ doc/src/sgml/ref/pg_dumpall.sgml | 11 +++++++++++ doc/src/sgml/ref/pg_isready.sgml | 7 +++++++ doc/src/sgml/ref/pg_receivewal.sgml | 6 ++++++ doc/src/sgml/ref/pg_recvlogical.sgml | 7 +++++++ doc/src/sgml/ref/pg_resetwal.sgml | 17 +++++++++++++++++ doc/src/sgml/ref/pg_restore.sgml | 11 +++++++++++ doc/src/sgml/ref/pg_rewind.sgml | 7 +++++++ doc/src/sgml/ref/pg_waldump.sgml | 26 ++++++++++++++++++++++++++ doc/src/sgml/ref/psql-ref.sgml | 11 +++++++++++ doc/src/sgml/ref/reindexdb.sgml | 11 +++++++++++ doc/src/sgml/ref/vacuumdb.sgml | 11 +++++++++++ 21 files changed, 230 insertions(+) (limited to 'doc/src') diff --git a/doc/src/sgml/ref/clusterdb.sgml b/doc/src/sgml/ref/clusterdb.sgml index ed343dd7dae..b25845ffc67 100644 --- a/doc/src/sgml/ref/clusterdb.sgml +++ b/doc/src/sgml/ref/clusterdb.sgml @@ -274,6 +274,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/createdb.sgml b/doc/src/sgml/ref/createdb.sgml index 2658efeb1a1..8fc8128bf9c 100644 --- a/doc/src/sgml/ref/createdb.sgml +++ b/doc/src/sgml/ref/createdb.sgml @@ -322,6 +322,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml index 22ee99f2cc4..abe25f17d01 100644 --- a/doc/src/sgml/ref/createuser.sgml +++ b/doc/src/sgml/ref/createuser.sgml @@ -400,6 +400,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/dropdb.sgml b/doc/src/sgml/ref/dropdb.sgml index 38f38f01ce6..3fbdb337164 100644 --- a/doc/src/sgml/ref/dropdb.sgml +++ b/doc/src/sgml/ref/dropdb.sgml @@ -228,6 +228,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/dropuser.sgml b/doc/src/sgml/ref/dropuser.sgml index 3d4e4b37b35..72bb7e8535c 100644 --- a/doc/src/sgml/ref/dropuser.sgml +++ b/doc/src/sgml/ref/dropuser.sgml @@ -220,6 +220,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 84fb37c293a..7f323103084 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -461,6 +461,17 @@ PostgreSQL documentation + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + + TZ diff --git a/doc/src/sgml/ref/pg_basebackup.sgml b/doc/src/sgml/ref/pg_basebackup.sgml index c4f3950e5bc..dd6bce57d2b 100644 --- a/doc/src/sgml/ref/pg_basebackup.sgml +++ b/doc/src/sgml/ref/pg_basebackup.sgml @@ -687,6 +687,12 @@ PostgreSQL documentation (see ). + + The environment variable PG_COLOR specifies whether to use + color in diagnostics messages. Possible values are + always, auto, + never. + diff --git a/doc/src/sgml/ref/pg_checksums.sgml b/doc/src/sgml/ref/pg_checksums.sgml index 70339eaec9c..d93793da5dd 100644 --- a/doc/src/sgml/ref/pg_checksums.sgml +++ b/doc/src/sgml/ref/pg_checksums.sgml @@ -173,6 +173,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/pg_controldata.sgml b/doc/src/sgml/ref/pg_controldata.sgml index 32081e9b91c..abac59aa500 100644 --- a/doc/src/sgml/ref/pg_controldata.sgml +++ b/doc/src/sgml/ref/pg_controldata.sgml @@ -68,6 +68,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/pg_dump.sgml b/doc/src/sgml/ref/pg_dump.sgml index e0e65f9c21c..8fa23143474 100644 --- a/doc/src/sgml/ref/pg_dump.sgml +++ b/doc/src/sgml/ref/pg_dump.sgml @@ -1224,6 +1224,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/pg_dumpall.sgml b/doc/src/sgml/ref/pg_dumpall.sgml index e3676cf811f..24c8c031d64 100644 --- a/doc/src/sgml/ref/pg_dumpall.sgml +++ b/doc/src/sgml/ref/pg_dumpall.sgml @@ -695,6 +695,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/pg_isready.sgml b/doc/src/sgml/ref/pg_isready.sgml index 9567b57ebe2..68447b5093d 100644 --- a/doc/src/sgml/ref/pg_isready.sgml +++ b/doc/src/sgml/ref/pg_isready.sgml @@ -164,6 +164,13 @@ PostgreSQL documentation also uses the environment variables supported by libpq (see ). + + + The environment variable PG_COLOR specifies whether to use + color in diagnostics messages. Possible values are + always, auto, + never. + diff --git a/doc/src/sgml/ref/pg_receivewal.sgml b/doc/src/sgml/ref/pg_receivewal.sgml index a18ddd4bff1..0506120c00b 100644 --- a/doc/src/sgml/ref/pg_receivewal.sgml +++ b/doc/src/sgml/ref/pg_receivewal.sgml @@ -408,6 +408,12 @@ PostgreSQL documentation (see ). + + The environment variable PG_COLOR specifies whether to use + color in diagnostics messages. Possible values are + always, auto, + never. + diff --git a/doc/src/sgml/ref/pg_recvlogical.sgml b/doc/src/sgml/ref/pg_recvlogical.sgml index 141c5cddce1..4c79f90414d 100644 --- a/doc/src/sgml/ref/pg_recvlogical.sgml +++ b/doc/src/sgml/ref/pg_recvlogical.sgml @@ -397,6 +397,13 @@ PostgreSQL documentation uses the environment variables supported by libpq (see ). + + + The environment variable PG_COLOR specifies whether to use + color in diagnostics messages. Possible values are + always, auto, + never. + diff --git a/doc/src/sgml/ref/pg_resetwal.sgml b/doc/src/sgml/ref/pg_resetwal.sgml index 3f885bdd620..8a9e22d050f 100644 --- a/doc/src/sgml/ref/pg_resetwal.sgml +++ b/doc/src/sgml/ref/pg_resetwal.sgml @@ -320,6 +320,23 @@ PostgreSQL documentation + + Environment + + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + + + + Notes diff --git a/doc/src/sgml/ref/pg_restore.sgml b/doc/src/sgml/ref/pg_restore.sgml index 725acb192c9..cf369a0f3b9 100644 --- a/doc/src/sgml/ref/pg_restore.sgml +++ b/doc/src/sgml/ref/pg_restore.sgml @@ -822,6 +822,17 @@ + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/pg_rewind.sgml b/doc/src/sgml/ref/pg_rewind.sgml index 53a64ee29ef..d98406c420e 100644 --- a/doc/src/sgml/ref/pg_rewind.sgml +++ b/doc/src/sgml/ref/pg_rewind.sgml @@ -234,6 +234,13 @@ PostgreSQL documentation pg_rewind also uses the environment variables supported by libpq (see ). + + + The environment variable PG_COLOR specifies whether to use + color in diagnostics messages. Possible values are + always, auto, + never. + diff --git a/doc/src/sgml/ref/pg_waldump.sgml b/doc/src/sgml/ref/pg_waldump.sgml index 389c314ef3b..329c10e4303 100644 --- a/doc/src/sgml/ref/pg_waldump.sgml +++ b/doc/src/sgml/ref/pg_waldump.sgml @@ -206,6 +206,32 @@ PostgreSQL documentation + + Environment + + + + PGDATA + + + Data directory; see also the option. + + + + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + + + + Notes diff --git a/doc/src/sgml/ref/psql-ref.sgml b/doc/src/sgml/ref/psql-ref.sgml index 1b5d82ed8ee..b29e7547c6a 100644 --- a/doc/src/sgml/ref/psql-ref.sgml +++ b/doc/src/sgml/ref/psql-ref.sgml @@ -4333,6 +4333,17 @@ $endif + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + + PSQL_EDITOR EDITOR diff --git a/doc/src/sgml/ref/reindexdb.sgml b/doc/src/sgml/ref/reindexdb.sgml index cdfac3fe4f9..25b5a727705 100644 --- a/doc/src/sgml/ref/reindexdb.sgml +++ b/doc/src/sgml/ref/reindexdb.sgml @@ -352,6 +352,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + diff --git a/doc/src/sgml/ref/vacuumdb.sgml b/doc/src/sgml/ref/vacuumdb.sgml index 41c7f3df793..47d93456f86 100644 --- a/doc/src/sgml/ref/vacuumdb.sgml +++ b/doc/src/sgml/ref/vacuumdb.sgml @@ -451,6 +451,17 @@ PostgreSQL documentation + + + PG_COLOR + + + Specifies whether to use color in diagnostics messages. Possible values + are always, auto, + never. + + + -- cgit v1.2.3