Doc: clarify the log message level of the VERBOSE option

Started by Masahiro Ikedaabout 1 year ago8 messages

ikedamsh@oss.nttdata.com

about 1 year ago

1 attachment(s)

Hi,

I'd like to clarify the log message level of the VERBOSE option
because I misunderstood that VACUUM VERBOSE messages cannot be
printed in the server log.

Although the hint is mentioned in "Table 19.2. Message Severity Levels",
it is not addressed for other commands.

INFO Provides information implicitly requested by the user, e.g.,
output from VACUUM VERBOSE.

https://www.postgresql.org/docs/devel/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS

IIUC, the following SQL commands support the VERBOSE option:
* VACUUM
* ANALYZE
* REINDEX
* COPY
* EXPALIN

The VERBOSE option for EXPLAIN is not related to the log message level,
and COPY already specifies the log message level. Therefore, I'd like to
add descriptions for the VERBOSE option in the ANALYZE, VACUUM, and
REINDEX commands.

What do you think?

Regards,
--
Masahiro Ikeda
NTT DATA CORPORATION

Attachments:

v1-0001-Doc-clarify-the-log-message-level-of-the-VERBOSE-.patchtext/x-diff; name=v1-0001-Doc-clarify-the-log-message-level-of-the-VERBOSE-.patchDownload

From 8534196181b1684a83bf1e47a8b3e0506a589087 Mon Sep 17 00:00:00 2001
From: Masahiro Ikeda <ikedamsh@oss.nttdata.com>
Date: Tue, 3 Dec 2024 18:02:10 +0900
Subject: [PATCH v1] Doc: clarify the log message level of the VERBOSE option

---
 doc/src/sgml/ref/analyze.sgml | 3 ++-
 doc/src/sgml/ref/reindex.sgml | 3 ++-
 doc/src/sgml/ref/vacuum.sgml  | 3 ++-
 3 files changed, 6 insertions(+), 3 deletions(-)

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index a0db56ae74..7b9fc76372 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,8 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Enables display of progress messages.
+      Prints a detailed analyze activity report for each table as
+      <literal>INFO</literal> messages.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index dcf70d14bc..8d476751a0 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -194,7 +194,8 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { DA
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a progress report as each index is reindexed.
+      Prints a detailed <command>REINDEX</command> activity report for
+      each index as <literal>INFO</literal> messages.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 9110938fab..62430730a2 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -129,7 +129,8 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a detailed vacuum activity report for each table.
+      Prints a detailed vacuum activity report for each table as
+      <literal>INFO</literal> messages.
      </para>
     </listitem>
    </varlistentry>
-- 
2.34.1

Yugo Nagata

nagata@sraoss.co.jp

about 1 year ago

In reply to: Masahiro Ikeda (#1)

Re: Doc: clarify the log message level of the VERBOSE option

On Tue, 03 Dec 2024 18:23:11 +0900
Masahiro Ikeda <ikedamsh@oss.nttdata.com> wrote:

Hi,

I'd like to clarify the log message level of the VERBOSE option
because I misunderstood that VACUUM VERBOSE messages cannot be
printed in the server log.

Although the hint is mentioned in "Table 19.2. Message Severity Levels",
it is not addressed for other commands.

INFO Provides information implicitly requested by the user, e.g.,
output from VACUUM VERBOSE.

https://www.postgresql.org/docs/devel/runtime-config-logging.html#RUNTIME-CONFIG-SEVERITY-LEVELS

IIUC, the following SQL commands support the VERBOSE option:
* VACUUM
* ANALYZE
* REINDEX
* COPY
* EXPALIN

The VERBOSE option for EXPLAIN is not related to the log message level,
and COPY already specifies the log message level. Therefore, I'd like to
add descriptions for the VERBOSE option in the ANALYZE, VACUUM, and
REINDEX commands.

What do you think?

This would prevent other users from make a misunderstanding as you did.

I found the description on amvalidate also explains a message is output at INFO level.
( https://www.postgresql.org/docs/devel/index-functions.html )

Problems should be reported with ereport messages, typically at INFO level.

I don't know the actual intention to mention the message level here, but
this might have the same purpose of you.

Should we add the description for CLUSTER command, since
it also has the VERBOSE options?

-      Enables display of progress messages.
+      Prints a detailed analyze activity report for each table as
+      <literal>INFO</literal> messages.

Do we need rewrite the description in addition to mentioning the message level?

Regards,
Yugo Nagata

--
Yugo Nagata <nagata@sraoss.co.jp>

Masahiro Ikeda

ikedamsh@oss.nttdata.com

about 1 year ago

In reply to: Yugo Nagata (#2)

1 attachment(s)

Re: Doc: clarify the log message level of the VERBOSE option

On 2024-12-04 21:08, Yugo Nagata wrote:

This would prevent other users from make a misunderstanding as you did.

I found the description on amvalidate also explains a message is
output at INFO level.
( https://www.postgresql.org/docs/devel/index-functions.html )

Problems should be reported with ereport messages, typically at INFO
level.

I don't know the actual intention to mention the message level here,
but
this might have the same purpose of you.

Thanks for your response!

Should we add the description for CLUSTER command, since
it also has the VERBOSE options?

Yes, you're right. I missed it.

-      Enables display of progress messages.
+      Prints a detailed analyze activity report for each table as
+      <literal>INFO</literal> messages.
Do we need rewrite the description in addition to mentioning the
message level?

Since the messages for the VERBOSE options look similar, I unified the
descriptions
for VACUUM, ANALYZE, and REINDEX. However, I don’t have a strong opinion
on this.
I’ve fixed it in the v2 patch.

Regards,
--
Masahiro Ikeda
NTT DATA CORPORATION

Attachments:

v2-0001-Doc-clarify-the-log-message-level-of-the-VERBOSE-.patchtext/x-diff; name=v2-0001-Doc-clarify-the-log-message-level-of-the-VERBOSE-.patchDownload

From f45982c314bda79904cbdcfee962040a1d30ae7e Mon Sep 17 00:00:00 2001
From: Masahiro Ikeda <ikedamsh@oss.nttdata.com>
Date: Thu, 5 Dec 2024 10:00:16 +0900
Subject: [PATCH v2] Doc: clarify the log message level of the VERBOSE option

---
 doc/src/sgml/ref/analyze.sgml | 2 +-
 doc/src/sgml/ref/cluster.sgml | 3 ++-
 doc/src/sgml/ref/reindex.sgml | 3 ++-
 doc/src/sgml/ref/vacuum.sgml  | 3 ++-
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index a0db56ae74..ec81f00fec 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,7 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Enables display of progress messages.
+      Enables display of progress messages at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index c5760244e6..434e3973ee 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -106,7 +106,8 @@ CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered,
+      at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index dcf70d14bc..60da4c38e1 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -194,7 +194,8 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { DA
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a progress report as each index is reindexed.
+      Prints a progress report as each index is reindexed,
+      at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 9110938fab..fd4de921dd 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -129,7 +129,8 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a detailed vacuum activity report for each table.
+      Prints a detailed vacuum activity report for each table,
+      at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
-- 
2.34.1

Yugo NAGATA

nagata@sraoss.co.jp

about 1 year ago

In reply to: Masahiro Ikeda (#3)

Re: Doc: clarify the log message level of the VERBOSE option

On Thu, 05 Dec 2024 10:39:22 +0900
Masahiro Ikeda <ikedamsh@oss.nttdata.com> wrote:

On 2024-12-04 21:08, Yugo Nagata wrote:

This would prevent other users from make a misunderstanding as you did.

I found the description on amvalidate also explains a message is
output at INFO level.
( https://www.postgresql.org/docs/devel/index-functions.html )

Problems should be reported with ereport messages, typically at INFO
level.

I don't know the actual intention to mention the message level here,
but
this might have the same purpose of you.

Thanks for your response!

Should we add the description for CLUSTER command, since
it also has the VERBOSE options?

Yes, you're right. I missed it.
-      Enables display of progress messages.
+      Prints a detailed analyze activity report for each table as
+      <literal>INFO</literal> messages.
Do we need rewrite the description in addition to mentioning the
message level?
Since the messages for the VERBOSE options look similar, I unified the
descriptions
for VACUUM, ANALYZE, and REINDEX. However, I don’t have a strong opinion
on this.
I’ve fixed it in the v2 patch.

-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered,
+      at <literal>INFO</literal> level.

I feel like the comma could not be necessary here like the fix for
the ANALYZE document, but it might be better to wait for a review
from a native English speaker.

Regards,
Yugo Nagata

--
Yugo NAGATA <nagata@sraoss.co.jp>

Masahiro Ikeda

ikedamsh@oss.nttdata.com

about 1 year ago

In reply to: Yugo NAGATA (#4)

Re: Doc: clarify the log message level of the VERBOSE option

On 2024-12-05 16:23, Yugo NAGATA wrote:

-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered,
+      at <literal>INFO</literal> level.
I feel like the comma could not be necessary here like the fix for
the ANALYZE document, but it might be better to wait for a review
from a native English speaker.

Thanks. OK, I'll wait.

Regards,
--
Masahiro Ikeda
NTT DATA CORPORATION

Fujii Masao

masao.fujii@oss.nttdata.com

about 1 year ago

In reply to: Masahiro Ikeda (#5)

1 attachment(s)

Re: Doc: clarify the log message level of the VERBOSE option

On 2024/12/05 16:48, Masahiro Ikeda wrote:

On 2024-12-05 16:23, Yugo NAGATA wrote:
-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered,
+      at <literal>INFO</literal> level.
I feel like the comma could not be necessary here like the fix for
the ANALYZE document, but it might be better to wait for a review
from a native English speaker.
Thanks. OK, I'll wait.

I'm not a native English speaker, but barring any objection,
I'd like to commit the attached patch. In this patch,
I've just removed a comma and updated the commit log message.

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION

Attachments:

v3-0001-doc-Clarify-log-level-for-VERBOSE-messages-in-mai.patchtext/plain; charset=UTF-8; name=v3-0001-doc-Clarify-log-level-for-VERBOSE-messages-in-mai.patchDownload

From a05585f5362f22a3272c9308868f215995a281d1 Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Fri, 20 Dec 2024 02:02:28 +0900
Subject: [PATCH v3] doc: Clarify log level for VERBOSE messages in maintenance
 commands.

VERBOSE messages from ANALYZE, CLUSTER, REINDEX, and VACUUM are logged
at the INFO level, but this detail was missing from the documentation.
This commit updates the docs to mention the log level for these messages.

Author: Masahiro Ikeda
Reviewed-by: Yugo Nagata
Discussion: https://postgr.es/m/b4a4b7916982dccd9607c8efb3ce5116@oss.nttdata.com
---
 doc/src/sgml/ref/analyze.sgml | 2 +-
 doc/src/sgml/ref/cluster.sgml | 3 ++-
 doc/src/sgml/ref/reindex.sgml | 3 ++-
 doc/src/sgml/ref/vacuum.sgml  | 3 ++-
 4 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/doc/src/sgml/ref/analyze.sgml b/doc/src/sgml/ref/analyze.sgml
index a0db56ae74..ec81f00fec 100644
--- a/doc/src/sgml/ref/analyze.sgml
+++ b/doc/src/sgml/ref/analyze.sgml
@@ -65,7 +65,7 @@ ANALYZE [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Enables display of progress messages.
+      Enables display of progress messages at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/cluster.sgml b/doc/src/sgml/ref/cluster.sgml
index c5760244e6..8811f169ea 100644
--- a/doc/src/sgml/ref/cluster.sgml
+++ b/doc/src/sgml/ref/cluster.sgml
@@ -106,7 +106,8 @@ CLUSTER [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <r
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered
+      at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/reindex.sgml b/doc/src/sgml/ref/reindex.sgml
index dcf70d14bc..5b3c769800 100644
--- a/doc/src/sgml/ref/reindex.sgml
+++ b/doc/src/sgml/ref/reindex.sgml
@@ -194,7 +194,8 @@ REINDEX [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] { DA
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a progress report as each index is reindexed.
+      Prints a progress report as each index is reindexed
+      at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
diff --git a/doc/src/sgml/ref/vacuum.sgml b/doc/src/sgml/ref/vacuum.sgml
index 9110938fab..971b1237d4 100644
--- a/doc/src/sgml/ref/vacuum.sgml
+++ b/doc/src/sgml/ref/vacuum.sgml
@@ -129,7 +129,8 @@ VACUUM [ ( <replaceable class="parameter">option</replaceable> [, ...] ) ] [ <re
     <term><literal>VERBOSE</literal></term>
     <listitem>
      <para>
-      Prints a detailed vacuum activity report for each table.
+      Prints a detailed vacuum activity report for each table
+      at <literal>INFO</literal> level.
      </para>
     </listitem>
    </varlistentry>
-- 
2.47.0

Masahiro Ikeda

ikedamsh@oss.nttdata.com

about 1 year ago

In reply to: Fujii Masao (#6)

Re: Doc: clarify the log message level of the VERBOSE option

On 2024-12-20 02:57, Fujii Masao wrote:

On 2024/12/05 16:48, Masahiro Ikeda wrote:
On 2024-12-05 16:23, Yugo NAGATA wrote:
-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered,
+      at <literal>INFO</literal> level.
I feel like the comma could not be necessary here like the fix for
the ANALYZE document, but it might be better to wait for a review
from a native English speaker.
Thanks. OK, I'll wait.
I'm not a native English speaker, but barring any objection,
I'd like to commit the attached patch. In this patch,
I've just removed a comma and updated the commit log message.

Regards,

Sorry for the late reply. It's okay with me.
Thank you!

Regards,
--
Masahiro Ikeda
NTT DATA CORPORATION

Fujii Masao

masao.fujii@oss.nttdata.com

about 1 year ago

In reply to: Masahiro Ikeda (#7)

Re: Doc: clarify the log message level of the VERBOSE option

On 2025/01/06 16:17, Masahiro Ikeda wrote:

On 2024-12-20 02:57, Fujii Masao wrote:
On 2024/12/05 16:48, Masahiro Ikeda wrote:
On 2024-12-05 16:23, Yugo NAGATA wrote:
-      Prints a progress report as each table is clustered.
+      Prints a progress report as each table is clustered,
+      at <literal>INFO</literal> level.
I feel like the comma could not be necessary here like the fix for
the ANALYZE document, but it might be better to wait for a review
from a native English speaker.
Thanks. OK, I'll wait.
I'm not a native English speaker, but barring any objection,
I'd like to commit the attached patch. In this patch,
I've just removed a comma and updated the commit log message.

Regards,
Sorry for the late reply. It's okay with me.

Thanks for checking that! Pushed.

Regards,

--
Fujii Masao
Advanced Computing Technology Center
Research and Development Headquarters
NTT DATA CORPORATION