On Sun, 27 Mar 2022 15:28:41 +0900 (JST)
Tatsuo Ishii <is...@sraoss.co.jp> wrote:
> > This patch has caused the PDF documentation to fail to build cleanly:
> >
> > [WARN] FOUserAgent - The contents of fo:block line 1 exceed the available
> > area in the inline-progression direction by more than 50 points. (See
> > position 125066:375)
> >
> > It's complaining about this:
> >
> > <synopsis>
> > <replaceable>interval_start</replaceable>
> > <replaceable>num_transactions</replaceable>
> > <replaceable>sum_latency</replaceable>
> > <replaceable>sum_latency_2</replaceable>
> > <replaceable>min_latency</replaceable>
> > <replaceable>max_latency</replaceable> {
> > <replaceable>failures</replaceable> |
> > <replaceable>serialization_failures</replaceable>
> > <replaceable>deadlock_failures</replaceable> } <optional>
> > <replaceable>sum_lag</replaceable> <replaceable>sum_lag_2</replaceable>
> > <replaceable>min_lag</replaceable> <replaceable>max_lag</replaceable>
> > <optional> <replaceable>skipped</replaceable> </optional> </optional>
> > <optional> <replaceable>retried</replaceable>
> > <replaceable>retries</replaceable> </optional>
> > </synopsis>
> >
> > which runs much too wide in HTML format too, even though that toolchain
> > doesn't tell you so.
>
> Yeah.
>
> > We could silence the warning by inserting an arbitrary line break or two,
> > or refactoring the syntax description into multiple parts. Either way
> > seems to create a risk of confusion.
>
> I think we can fold the line nicely. Here is the rendered image.
>
> Before:
> interval_start num_transactions sum_latency sum_latency_2 min_latency
> max_latency { failures | serialization_failures deadlock_failures } [ sum_lag
> sum_lag_2 min_lag max_lag [ skipped ] ] [ retried retries ]
>
> After:
> interval_start num_transactions sum_latency sum_latency_2 min_latency
> max_latency
> { failures | serialization_failures deadlock_failures } [ sum_lag sum_lag_2
> min_lag max_lag [ skipped ] ] [ retried retries ]
>
> Note that before it was like this:
>
> interval_start num_transactions sum_latency sum_latency_2 min_latency
> max_latency [ sum_lag sum_lag_2 min_lag max_lag [ skipped ] ]
>
> So newly added items are "{ failures | serialization_failures
> deadlock_failures }" and " [ retried retries ]".
>
> > TBH, I think the *real* problem is that the complexity of this log format
> > has blown past "out of hand". Can't we simplify it? Who is really going
> > to use all these numbers? I pity the poor sucker who tries to write a
> > log analysis tool that will handle all the variants.
>
> Well, the extra logging items above only appear when the retry feature
> is enabled. For those who do not use the feature the only new logging
> item is "failures". For those who use the feature, the extra logging
> items are apparently necessary. For example if we write an application
> using repeatable read or serializable transaction isolation mode,
> retrying failed transactions due to srialization error is an essential
> technique. Also the retry rate of transactions will deeply affect the
> performance and in such use cases the newly added items will be
> precisou information. I would suggest leave the log items as it is.
>
> Patch attached.
Even applying this patch, "make postgres-A4.pdf" arises the warning on my
machine. After some investigations, I found that previous document had a break
after 'num_transactions', but it has been removed due to this commit. So,
I would like to get back this as it was. I attached the patch.
Regards,
Yugo Nagata
--
Yugo NAGATA <nag...@sraoss.co.jp>
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ebdb4b3f46..4437d5ef53 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2401,7 +2401,7 @@ END;
format is used for the log files:
<synopsis>
-<replaceable>interval_start</replaceable> <replaceable>num_transactions</replaceable> <replaceable>sum_latency</replaceable> <replaceable>sum_latency_2</replaceable> <replaceable>min_latency</replaceable> <replaceable>max_latency</replaceable> { <replaceable>failures</replaceable> | <replaceable>serialization_failures</replaceable> <replaceable>deadlock_failures</replaceable> } <optional> <replaceable>sum_lag</replaceable> <replaceable>sum_lag_2</replaceable> <replaceable>min_lag</replaceable> <replaceable>max_lag</replaceable> <optional> <replaceable>skipped</replaceable> </optional> </optional> <optional> <replaceable>retried</replaceable> <replaceable>retries</replaceable> </optional>
+<replaceable>interval_start</replaceable> <replaceable>num_transactions</replaceable>&zwsp <replaceable>sum_latency</replaceable> <replaceable>sum_latency_2</replaceable> <replaceable>min_latency</replaceable> <replaceable>max_latency</replaceable> { <replaceable>failures</replaceable> | <replaceable>serialization_failures</replaceable> <replaceable>deadlock_failures</replaceable> } <optional> <replaceable>sum_lag</replaceable> <replaceable>sum_lag_2</replaceable> <replaceable>min_lag</replaceable> <replaceable>max_lag</replaceable> <optional> <replaceable>skipped</replaceable> </optional> </optional> <optional> <replaceable>retried</replaceable> <replaceable>retries</replaceable> </optional>
</synopsis>
where
