From 9b809157967e1498ea690e50cb4a9a39ff4a07a8 Mon Sep 17 00:00:00 2001
From: Nadav Shatz <nadav@tailorbrands.com>
Date: Mon, 8 Sep 2025 09:58:31 +0300
Subject: [PATCH 3/3] doc: document external replication delay command and
 arguments

Add English documentation for replication_delay_source ('builtin'|'cmd'),
replication_delay_source_cmd including positional instance identifier arguments
passed in Pgpool backend order, and replication_delay_source_timeout.
---
 doc/src/sgml/stream-check.sgml | 90 ++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

diff --git a/doc/src/sgml/stream-check.sgml b/doc/src/sgml/stream-check.sgml
index d2ca3ca49..12e745e76 100644
--- a/doc/src/sgml/stream-check.sgml
+++ b/doc/src/sgml/stream-check.sgml
@@ -309,6 +309,96 @@ GRANT pg_monitor TO sr_check_user;
     </listitem>
   </varlistentry>
 
+  <varlistentry id="guc-replication-delay-source" xreflabel="replication_delay_source">
+   <term><varname>replication_delay_source</varname> (<type>enum</type>)
+    <indexterm>
+     <primary><varname>replication_delay_source</varname> configuration parameter</primary>
+    </indexterm>
+   </term>
+   <listitem>
+    <para>
+     Specifies the source of replication delay information used by the
+     streaming replication delay check worker. Valid values are:
+    </para>
+    <itemizedlist>
+     <listitem>
+      <para><literal>builtin</literal> — query the primary and standbys to compute delay.</para>
+     </listitem>
+     <listitem>
+      <para><literal>cmd</literal> — run an external command to obtain delays for each backend.</para>
+     </listitem>
+    </itemizedlist>
+    <para>
+     When set to <literal>cmd</literal>, <xref linkend="guc-replication-delay-source-cmd"> must be set
+     to the command to execute, and <xref linkend="guc-replication-delay-source-timeout"> controls
+     its timeout.
+    </para>
+    <para>
+     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry id="guc-replication-delay-source-cmd" xreflabel="replication_delay_source_cmd">
+   <term><varname>replication_delay_source_cmd</varname> (<type>string</type>)
+    <indexterm>
+     <primary><varname>replication_delay_source_cmd</varname> configuration parameter</primary>
+    </indexterm>
+   </term>
+   <listitem>
+    <para>
+     Specifies the external command to execute when <xref linkend="guc-replication-delay-source">
+     is set to <literal>cmd</literal>. The command is executed as the
+     <productname>Pgpool-II</productname> process user.
+    </para>
+    <para>
+     The command receives an ordered list of instance identifiers as positional
+     arguments corresponding to Pgpool backend node indexes (0..N-1). The order
+     matches Pgpool's backend order so the script can map metrics (for example
+     from AWS CloudWatch for Aurora) back to the correct node. Each identifier is
+     one of:
+    </para>
+    <itemizedlist>
+     <listitem>
+      <para><literal>backend_application_name</literal> (if configured)</para>
+     </listitem>
+     <listitem>
+      <para><literal>&lt;hostname&gt;:&lt;port&gt;</literal> (if application name is empty)</para>
+     </listitem>
+     <listitem>
+      <para><literal>node&lt;i&gt;</literal> (fallback)</para>
+     </listitem>
+    </itemizedlist>
+    <para>
+     The command must write a single line to stdout containing one whitespace-separated
+     delay value per backend, in milliseconds, in the same order as the arguments.
+     For example: <literal>"0 25.5 100"</literal> for a 3-node cluster.
+    </para>
+    <para>
+     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
+    </para>
+   </listitem>
+  </varlistentry>
+
+  <varlistentry id="guc-replication-delay-source-timeout" xreflabel="replication_delay_source_timeout">
+   <term><varname>replication_delay_source_timeout</varname> (<type>integer</type>)
+    <indexterm>
+     <primary><varname>replication_delay_source_timeout</varname> configuration parameter</primary>
+    </indexterm>
+   </term>
+   <listitem>
+    <para>
+     Specifies the timeout in seconds for the external command executed when
+     <xref linkend="guc-replication-delay-source"> is set to <literal>cmd</literal>.
+     If the command does not finish within the timeout, Pgpool logs an error and
+     continues.
+    </para>
+    <para>
+     This parameter can be changed by reloading the <productname>Pgpool-II</> configurations.
+    </para>
+   </listitem>
+  </varlistentry>
+
   <varlistentry id="guc-log-standby-delay" xreflabel="log_standby_delay">
    <term><varname>log_standby_delay</varname> (<type>enum</type>)
     <indexterm>
-- 
2.51.0

