|author||Christian Grothoff <firstname.lastname@example.org>||2020-03-20 18:54:44 +0100|
|committer||Christian Grothoff <email@example.com>||2020-03-20 18:54:57 +0100|
document how to run benchmark tool
2 files changed, 66 insertions, 2 deletions
diff --git a/manpages/taler-exchange-benchmark.1.rst b/manpages/taler-exchange-benchmark.1.rst
index 4ea2378..9bc0c8d 100644
@@ -15,7 +15,7 @@ Synopsis
[**-c** *CONFIG_FILENAME* | **--config=**\ \ *CONFIG_FILENAME*]
-[**-b** *BANK_URL* | **—bank-url=**\ \ *BANK_URL*]
+[**-b** *BANK_URL* | **—bank-url=**\ \ *BANK_URL*] [-f] [-K]
[**-n** *HOWMANY_COINS* | **--coins-number=**\ \ *HOWMANY_COINS*]
[**-l** *LOGLEVEL* | **--log-level=**\ \ *LOGLEVEL*]
[**-h** | **--help**]
@@ -37,6 +37,16 @@ that table are always erased during a single benchmark run.
(Mandatory) The URL where the fakebank listens at. Must match the
host component in the exchange’s escrow account “payto” URL.
+**-f** \| **--fakebank**
+ Launch a fakebank instead of the Python bank. Only meaningful if the
+ mode is to launch more than just a client. Note that using the
+ fakebank will cause the benchmark application to reset all databases
+ as the fakebank is stateless and thus previous database state would
+ inherently cause trouble.
+**-K** \| **--linger**
+ Linger around until keypress after the benchmark is done.
**-n** *HOWMANY_COINS* \| **--coins-number=**\ \ *HOWMANY_COINS*
Defaults to 1. Specifies how many coins this benchmark should
withdraw and spend. After being spent, each coin will be refreshed
@@ -53,7 +63,7 @@ that table are always erased during a single benchmark run.
+taler-exchange-dbinit(1), taler-exchange-keyup(1), taler-merchant-benchmark(1),
diff --git a/taler-exchange-manual.rst b/taler-exchange-manual.rst
index af5eea5..432a4b8 100644
@@ -909,3 +909,57 @@ TALER_SIGNATURE_AUDITOR_EXCHANGE_KEYS purpose.
+This chapter describes how to run the Taler exchange benchmark.
+The benchmark can be used to measure the performance of the exchange
+by running a (possibly large) number of simulated clients against one
+Taler deployment with a bank, exchange and auditor. For the bank, both
+a "fakebank" (``-f``) and a "Pythonbank" deployment are currently supported.
+The taler-exchange-benchmark program can launch all required services
+and clients, or only launch the parallel clients (``-m``), for example for
+distributed testing over a network.
+For each *parallel* (``-p``) client, a number of *reserves* (``-r``) is first established by
+**transfering** money from a "user" account (42) to the Exchange's account
+with the respective reserve public key as wire subject. Next, the
+client will **withdraw** a *number of coins* (``-n``) from the reserve and
+**deposit** them. Additionally, a *fraction* (``-R``) of the dirty coins will then be
+subject to **refreshing**. For some deposits, the auditor will receive
+Operations that are not covered today include closing reserves, refunds and
+The existing ``benchmark.conf`` file in ``src/benchmark/`` can be used as a
+starting point for a configuration to run the benchmark. The existing
+configuration file only requires that the ``talercheck`` database already
+exists and will launch all required services locally as needed.
+Note that by default the benchmark requires that the database is already
+initialized using ``taler-exchange-keyup``.
+You can run a first simple benchmark using:
+ $ taler-exchange-benchmark -c benchmark.conf -p 4 -r 1 -n 10
+This will run 4 parallel clients withdrawing 10 coins from 1 reserve and then
+depositing those coins. The default refresh probability is 10 percent. Note
+that the tiny run should only take a few seconds, most of it will be spent in
+the setup of the original key material. For meaningful runs, all three values
+should likely be increased.
+The output of ``taler-exchange-benchmark`` will include for each parallel
+client the total time spent in each of the major operations, possible
+repetitions (i.e. if the operation failed the first time), total execution
+time (operating system and user space) and other details.
+Naturally, additional instrumentation (including using features of the
+Postgres database itself) may help discover performance issues.