From c7f4b0edbc35aebfd278d49f8d84c6fdeb1e1fe3 Mon Sep 17 00:00:00 2001
From: Bo Peng <pengbo@sraoss.co.jp>
Date: Wed, 18 Jun 2025 18:12:13 +0900
Subject: [PATCH] Doc: enhance pcp_node_info document.

Clarify that each backend_application_nameX must match the value specified
in the application_name of primary_conninfo to correctly display
"replication_state" and "replication_sync_state".
---
 doc.ja/src/sgml/ref/pcp_node_info.sgml | 51 +++++++++++++++++----
 doc/src/sgml/ref/pcp_node_info.sgml    | 61 +++++++++++++++++++++-----
 2 files changed, 92 insertions(+), 20 deletions(-)

diff --git a/doc.ja/src/sgml/ref/pcp_node_info.sgml b/doc.ja/src/sgml/ref/pcp_node_info.sgml
index 0e24eaae1..dc146cec3 100644
--- a/doc.ja/src/sgml/ref/pcp_node_info.sgml
+++ b/doc.ja/src/sgml/ref/pcp_node_info.sgml
@@ -136,7 +136,7 @@ $ pcp_node_info -w -p 11001 -n 1
 2. ノードのポート番号
 3. ステータス
 4. ロードバランスウェイト
-5. バックエンド状態名
+5. バックエンドステータス名
 6. 実際のバックエンドの状態 (Pgpool-II 4.3以降。PQpingParamsで取得)
 7. バックエンドの役割
 8. 実際のバックエンドの役割(Pgpool-II 4.3以降。pg_is_in_recoveryで取得)
@@ -148,9 +148,9 @@ $ pcp_node_info -w -p 11001 -n 1
   </para>
   <para>
    <!--
-    3 (status) is represented by a digit from [0 to 3].
+   <emphasis>3 (status)</> is represented by a digit from [0 to 3].
    -->
-   3 (ステータス)は [0..3] までの数字で表わされます。各数字の意味は以下のとおりです。
+   <emphasis>3（ステータス）</>は [0..3] までの数字で表わされます。各数字の意味は以下のとおりです。
   </para>
   <para>
    <itemizedlist>
@@ -170,10 +170,21 @@ $ pcp_node_info -w -p 11001 -n 1
    <!--
    4 (load balance weight) is displayed in normalized format.
    -->
-   4 (ロードバランスウェイト)は0から1に正規化されたフォーマットで出力されます。
+   <emphasis>4（ロードバランスウェイト）</>は0から1に正規化されたフォーマットで出力されます。
   </para>
   <para>
-   6は実際のバックエンドの状態をリアルタイムで取得して表示します。
+   <!--
+   <emphasis>5 (status name)</> indicates the status of a
+   <productname>PostgreSQL</productname> node as recognized by
+   <productname>Pgpool-II</productname>. It corresponds to the numeric value
+   shown in "<emphasis>3 (status)</>" and represents the node's internal state
+   in a human-readable format maintained by <productname>Pgpool-II</productname>.
+   -->
+   <emphasis>5（バックエンドステータス名）</>は<productname>Pgpool-II</productname>から見た<productname>PostgreSQL</productname>ノードのステータス名を示します。
+   これは、上記「<emphasis>3（ステータス）</>」の数値に対応する状態名（文字列）であり、<productname>Pgpool-II</productname>が内部的に保持しているノードの状態を、可読性の高い形式で表現したものです。
+  </para>
+  <para>
+   <emphasis>6（実際のバックエンドの状態）</>は実際のバックエンドの状態をリアルタイムで取得して表示します。
    情報の取得は、このコマンドが実行された時に<function>PQpingParams</function>を呼び出すことによって行われます。
    <function>PQpingParams</function>は<productname>PostgreSQL</productname> 9.1以降でのみサポートされています。
    <productname>Pgpool-II</productname>が<productname>PostgreSQL</productname> 9.0以前とともに構築されると、この列は"unknown"と表示されます。
@@ -182,7 +193,10 @@ $ pcp_node_info -w -p 11001 -n 1
     逆に、5が"up"なのに、6が"down"というのは起こらないはずです。
   </para>
   <para>
-   8は実際のバックエンドの状態をリアルタイムで取得して表示します。
+   <emphasis>7（バックエンドの役割）</>は<productname>Pgpool-II</productname>から見た<productname>PostgreSQL</productname>ノードの役割（primaryまたはstandby）を示します。<productname>Pgpool-II</productname>が内部的に保持している情報に基づいて表示されます。
+  </para>
+  <para>
+   <emphasis>8（実際のバックエンドの役割）</>は実際のバックエンドの役割（primaryまたはstandby）をリアルタイムで取得して表示します。
    その結果はストリーミングレプリケーションモードでは、"primary"か"standby"ですが、情報が取得できなければ"unknown"と表示します。
    <productname>Pgpool-II</productname>はノードID順にバックエンドノードを調べ、最後に見つけたスタンバイ以外のノードをプライマリとするので、誤ってスタンバイ以外のノードが複数できたときなどには、7と8が一致しないことはありえます。
    （このコマンドはそのような状態を見つけるのに役立ちます。)
@@ -190,11 +204,30 @@ $ pcp_node_info -w -p 11001 -n 1
    ストリーミングレプリケーションモードと違って、<function>pg_is_in_recovery</function>は呼び出されず、7と8が異なる値になることはありません。
   </para>
   <para>
-   9, 10, 11は、<xref linkend="guc-sr-check-period">が0以外でなければ正しく表示されません。
-   また、10, 11は、<xref linkend="guc-sr-check-user">が<productname>PostgreSQL</productname>のスーパーユーザーであるか、"pg_monitor"グループに所属していなけれ正しく表示されません。
+   <emphasis>9, 10, 11</>を正しく表示させるに、<xref linkend="guc-sr-check-period">が0以外に設定されている必要があります。
+    さらに10, 11を正しく表示させるには、以下の追加設定が必要です。
+   <itemizedlist>
+    <listitem>
+     <para>
+      <xref linkend="guc-backend-application-name">パラメータを設定する必要があります。
+     </para>
+     <para>
+      各<varname>backend_application_nameX</varname>に設定された値が、該当ノードの<varname>primary_conninfo</varname>の<varname>application_name</varname>に指定された値と一致している必要があります。
+     </para>
+     <para>
+      特に、<productname>Pgpool-II</productname>の<xref linkend="pcp-recovery-node">コマンドを用いてスタンバイノードを構築し、コミュニティ提供のサンプルスクリプトを使用している場合は、<varname>backend_application_nameX</varname>の値を<varname>backend_hostnameX</varname>と一致させてください。
+      具体的な設定例については<xref linkend="example-cluster-pgpool-config-backend-settings">をご参照ください。
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <xref linkend="guc-sr-check-user">が<productname>PostgreSQL</productname>のスーパーユーザーであるか、もしくは<literal>pg_monitor</literal>ロールの権限が付与されている必要があります。
+     </para>
+    </listitem>
+   </itemizedlist>
    <note>
     <para>
-    <xref linkend="guc-sr-check-user">をpg_monitorグループに所属させるには、以下のSQLコマンドを<productname>PostgreSQL</productname>スーパーユーザーで実行してください（"sr_check_user"を<xref linkend="guc-sr-check-user">の設定値で置き換えてください）
+    <xref linkend="guc-sr-check-user">に<literal>pg_monitor</literal>ロールの権限を付与するには、以下のSQLコマンドを<productname>PostgreSQL</productname>スーパーユーザーで実行してください（"sr_check_user"を<xref linkend="guc-sr-check-user">の設定値で置き換えてください）
 	 <programlisting>
 GRANT pg_monitor TO sr_check_user;
 	 </programlisting>
diff --git a/doc/src/sgml/ref/pcp_node_info.sgml b/doc/src/sgml/ref/pcp_node_info.sgml
index de8348b49..c6a568699 100644
--- a/doc/src/sgml/ref/pcp_node_info.sgml
+++ b/doc/src/sgml/ref/pcp_node_info.sgml
@@ -100,7 +100,7 @@ $ pcp_node_info -w -p 11001 -n 1
    </literallayout>
   </para>
   <para>
-   3 (status) is represented by a digit from [0 to 3].
+   <emphasis>3 (status)</> is represented by a digit from [0 to 3].
    <itemizedlist>
     <listitem><para>0 - This state is only used during the initialization. PCP will never display it. </para></listitem>
     <listitem><para>1 - Node is up. No connections yet. </para></listitem>
@@ -109,10 +109,17 @@ $ pcp_node_info -w -p 11001 -n 1
    </itemizedlist>
   </para>
   <para>
-   4 (load balance weight) is displayed in normalized format (0 - 1).
+   <emphasis>4 (load balance weight)</> is displayed in normalized format (0 - 1).
   </para>
   <para>
-   6 shows the backend status in real time.  The info is obtained by
+   <emphasis>5 (status name)</> indicates the status of a
+   <productname>PostgreSQL</productname> node as recognized by
+   <productname>Pgpool-II</productname>. It corresponds to the numeric value
+   shown in "<emphasis>3 (status)</>" and represents the node's internal state
+   in a human-readable format maintained by <productname>Pgpool-II</productname>.
+  </para>
+  <para>
+   <emphasis>6 (actual backend status)</> shows the backend status in real time.  The info is obtained by
    calling <function>PQpingParams</function> at the time when the
    command is invoked. <function>PQpingParams</function> is only
    available in <productname>PostgreSQL</productname> 9.1 or later. If
@@ -129,7 +136,13 @@ $ pcp_node_info -w -p 11001 -n 1
    is "down".
   </para>
   <para>
-   8 shows the backend status in real time. The result will be either
+   <emphasis>7 (backend role)</> indicates the role of a <productname>PostgreSQL</productname>
+   node (primary or standby) from the perspective of
+   <productname>Pgpool-II</productname>, based on its internally maintained
+   information.
+  </para>
+  <para>
+   <emphasis>8 (actual backend role)</> shows the backend status in real time. The result will be either
    "primary" or "standby", and possibly "unknown" if information
    retrieval failed. Since <productname>Pgpool-II</productname>
    searches backend nodes in the node id order and assumes the last
@@ -142,15 +155,41 @@ $ pcp_node_info -w -p 11001 -n 1
    7 and 8 will be always the same.
   </para>
   <para>
-   To correctly 9, 10, 11 are displayed, <xref linkend="guc-sr-check-period"> must not
-   be 0.  10, 11 will not be displayed
-   if <xref linkend="guc-sr-check-user"> is
-   not <productname>PostgreSQL</productname> super user nor it's not
-   in "pg_monitor" group.
+   To correctly display <emphasis>9, 10 and 11</>, <xref linkend="guc-sr-check-period">
+   must not be 0.
+   Additionally, to correctly display <emphasis>10 and 11</>, the following
+   settings are required.
+   <itemizedlist>
+    <listitem>
+     <para>
+      <xref linkend="guc-backend-application-name"> must be configured.
+     </para>
+     <para>
+      The value set for each <varname>backend_application_nameX</varname>
+      must match the value specified in <varname>application_name</varname>
+      of <varname>primary_conninfo</varname> for the corresponding node.
+     </para>
+     <para>
+      In particular, when creating standby nodes using Pgpool-II's
+      <xref linkend="pcp-recovery-node"> command and community-provided
+      sample scripts, please ensure that the value of
+      <varname>backend_application_nameX</varname> matches that of
+      <varname>backend_hostnameX</varname>. For specific configuration examples,
+      please refer to <xref linkend="example-cluster-pgpool-config-backend-settings">.
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <xref linkend="guc-sr-check-user"> must either be a
+      <productname>PostgreSQL</productname> superuser or have been granted the
+      privileges of the <literal>pg_monitor</literal> role.
+     </para>
+    </listitem>
+   </itemizedlist>
    <note>
     <para>
-     To make <xref linkend="guc-sr-check-user"> in pg_monitor
-     group, execute following SQL command
+     To grant the privileges of the <literal>pg_monitor</literal> role to
+     <xref linkend="guc-sr-check-user">, execute following SQL command
      by <productname>PostgreSQL</productname> super user (replace
      "sr_check_user" with the setting of <xref linkend="guc-sr-check-user">):
      <programlisting>
-- 
2.39.5