public inbox for [email protected]
help / color / mirror / Atom feedFrom: Chao Li <[email protected]>
To: Fujii Masao <[email protected]>
Cc: Yugo Nagata <[email protected]>
Cc: PostgreSQL-development <[email protected]>
Cc: Rintaro Ikeda <[email protected]>
Subject: Re: pgbench --continue-on-error: clarify TPS and failure reporting
Date: Mon, 22 Jun 2026 16:10:22 +0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <[email protected]>
References: <[email protected]>
<[email protected]>
<[email protected]>
<CAHGQGwFX6Wqdp=ZEjs6WSu3GDSpgM9qZTixBHXKB9xaVzQ+0-A@mail.gmail.com>
<[email protected]>
> On Jun 18, 2026, at 20:45, Chao Li <[email protected]> wrote:
>
>
>
>> On Jun 18, 2026, at 17:40, Fujii Masao <[email protected]> wrote:
>>
>> On Thu, Jun 18, 2026 at 3:25 PM Chao Li <[email protected]> wrote:
>>> Thanks for confirming the doc issue. The here comes a small doc patch.
>>>
>>> I also noticed there is a later paragraph about “latency” that also needs an update, it’s included in the patch as well.
>>
>> Thanks for the patch! The TPS-related changes look good to me.
>>
>> The latency of a successful transaction includes the entire time of
>> - transaction execution with rollbacks and retries. The latency is measured
>> - only for successful transactions and commands but not for failed
>> transactions
>> - or commands.
>> + transaction execution with rollbacks and retries. The latency is measured
>> + only for successful transactions and commands, except that failed
>> + transactions are included in the simple average latency when the
>> + <option>--continue-on-error</option> option is used.
>>
>> It doesn't seem that the behavior of the latency average in the main
>> report depends on --continue-on-error itself. Instead, when neither
>> --progress, --rate, nor --latency-limit is specified, the main
>> report shows a simple latency average computed as the total benchmark
>> duration divided by the number of successful and failed transactions,
>> so failed transactions are included.
>>
>> On the other hand, when any of those options is specified, the
>> latency average and latency stddev in the main report are based
>> only on successful transactions. Likewise, the per-script and
>> per-command latency statistics are measured only for successful
>> transactions and commands.
>>
>> So how about something like this instead?
>>
>> -------------------------------
>> <para>
>> The latency of a successful transaction includes the entire time of
>> - transaction execution with rollbacks and retries. The simple
>> - <literal>latency average</literal> shown in the main report is computed from
>> - the total benchmark duration divided by both successful and failed
>> - transactions, and therefore includes failed transactions. In contrast,
>> - detailed latency statistics, including the per-script and per-command
>> - reports, are measured only for successful transactions and commands, not
>> - for failed transactions or commands.
>> + transaction execution with rollbacks and retries. In the main report, when
>> + neither <option>--progress</option>, <option>--rate</option>, nor
>> + <option>--latency-limit</option> is specified, the
>> + <literal>latency average</literal> is computed from the total benchmark
>> + duration divided by both successful and failed transactions, and therefore
>> + includes failed transactions. Otherwise, the <literal>latency
>> average</literal>
>> + and <literal>latency stddev</literal> shown in the main report are measured
>> + only for successful transactions. Detailed latency statistics, including
>> + the per-script and per-command reports, are also measured only for
>> + successful transactions and commands, not for failed transactions or
>> + commands.
>> </para>
>> -------------------------------
>>
>
> I feel that might be too detailed. Listing these three option names here could make the doc harder to read and maintain. When failures are included, the output line already says so explicitly:
> ```
> latency average = 0.387 ms (including failures)
> ```
>
> Can we simply say something like this?
> ```
> <para>
> The latency of a successful transaction includes the entire time of
> transaction execution with rollbacks and retries. The latency is measured
> only for successful transactions and commands, not for failed transactions
> or commands, unless the report explicitly says that it includes failures.
> </para>
> ```
>
> Best regards,
> --
> Chao Li (Evan)
> HighGo Software Co., Ltd.
> https://www.highgo.com/
Thinking it over, I came up with a version that combines Fujii-san’s suggestion and my previous version:
```
<para>
The latency of a successful transaction includes the entire time of
transaction execution with rollbacks and retries. In the main report,
when none of <option>--progress</option>, <option>--rate</option>, and
<option>--latency-limit</option> is specified, <literal>latency average</literal>
is computed from both successful and failed transactions. In such cases,
this is explicitly indicated by <literal>(including failures)</literal>.
Other latency statistics, including the per-script and per-command reports,
are measured only for successful transactions and commands, not for failed
transactions or commands.
</para>
```
PFA v2.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Attachments:
[application/octet-stream] v2-0001-doc-Clarify-pgbench-reporting-with-continue-on-er.patch (2.6K, ../[email protected]/2-v2-0001-doc-Clarify-pgbench-reporting-with-continue-on-er.patch)
download | inline diff:
From 0a944fb519d8eeb74037dccbf3cf5f40ce613180 Mon Sep 17 00:00:00 2001
From: "Chao Li (Evan)" <[email protected]>
Date: Thu, 18 Jun 2026 14:21:13 +0800
Subject: [PATCH v2] doc: Clarify pgbench reporting with --continue-on-error
Clarify that transactions failed under --continue-on-error are reported
separately and are not counted as transactions actually processed or in
TPS. Also adjust the latency description to avoid implying that failed
transactions are generally included in latency measurements.
Author: Chao Li <[email protected]>
Reviewed-by: Yugo Nagata <[email protected]>
Reviewed-by: Fujii Masao <[email protected]>
Discussion: https://postgr.es/m/[email protected]
---
doc/src/sgml/ref/pgbench.sgml | 16 ++++++++++++----
1 file changed, 12 insertions(+), 4 deletions(-)
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index 2e401d1ceb8..7619b8ad743 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -770,10 +770,13 @@ pgbench <optional> <replaceable>options</replaceable> </optional> <replaceable>d
the connection to fail.
See <xref linkend="failures-and-retries"/> for more information.
</para>
+
<para>
This option is useful when your custom script may raise errors
such as unique constraint violations, but you want the benchmark
- to continue and measure performance including those failures.
+ to continue despite individual statement failures. Failed
+ transactions are reported separately, but are not counted as
+ transactions actually processed, nor are they included in TPS.
</para>
</listitem>
</varlistentry>
@@ -2933,9 +2936,14 @@ statement latencies in milliseconds, failures and retries:
<para>
The latency of a successful transaction includes the entire time of
- transaction execution with rollbacks and retries. The latency is measured
- only for successful transactions and commands but not for failed transactions
- or commands.
+ transaction execution with rollbacks and retries. In the main report,
+ when none of <option>--progress</option>, <option>--rate</option>, and
+ <option>--latency-limit</option> is specified, <literal>latency average</literal>
+ is computed from both successful and failed transactions. In such cases,
+ this is explicitly indicated by <literal>(including failures)</literal>.
+ Other latency statistics, including the per-script and per-command reports,
+ are measured only for successful transactions and commands, not for failed
+ transactions or commands.
</para>
<para>
--
2.50.1 (Apple Git-155)
view thread (6+ messages)
reply
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Reply to all the recipients using the --to and --cc options:
reply via email
To: [email protected]
Cc: [email protected], [email protected], [email protected], [email protected]
Subject: Re: pgbench --continue-on-error: clarify TPS and failure reporting
In-Reply-To: <[email protected]>
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox