> 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.
Best reagards,
--
Tatsuo Ishii
SRA OSS, Inc. Japan
English: http://www.sraoss.co.jp/index_en.php
Japanese:http://www.sraoss.co.jp
diff --git a/doc/src/sgml/ref/pgbench.sgml b/doc/src/sgml/ref/pgbench.sgml
index ebdb4b3f46..b65b813ebe 100644
--- a/doc/src/sgml/ref/pgbench.sgml
+++ b/doc/src/sgml/ref/pgbench.sgml
@@ -2398,10 +2398,11 @@ END;
<para>
With the <option>--aggregate-interval</option> option, a different
- format is used for the log files:
+ format is used for the log files (note that the actual log line is not folded).
<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> <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
