[Doc] Add pulsar-perf txn (#12336)
diff --git a/site2/docs/performance-pulsar-perf.md b/site2/docs/performance-pulsar-perf.md
index c5aafaf..bda24fb 100644
--- a/site2/docs/performance-pulsar-perf.md
+++ b/site2/docs/performance-pulsar-perf.md
@@ -8,151 +8,176 @@
## Produce messages
-This example shows how the Pulsar Perf produces messages with default options. For all configuration options available for the `pulsar-perf produce` command, see [configuration options](#configuration-options-for-pulsar-perf-produce).
+> **Tip**
+>
+> For the latest and complete information about `pulsar-perf`, including commands, flags, descriptions, and more, see [`pulsar-perf`](https://pulsar.apache.org/tools/pulsar-perf/) or [here](reference-cli-tools.md#pulsar-perf).
-```
-bin/pulsar-perf produce my-topic
-```
+- This example shows how the Pulsar Perf produces messages with **default** options.
-After the command is executed, the test data is continuously output on the Console.
+ **Input**
+
+ ```
+ bin/pulsar-perf produce my-topic
+ ```
-**Output**
+ After the command is executed, the test data is continuously output on the Console.
-```
-19:53:31.459 [pulsar-perf-producer-exec-1-1] INFO org.apache.pulsar.testclient.PerformanceProducer - Created 1 producers
-19:53:31.482 [pulsar-timer-5-1] WARN com.scurrilous.circe.checksum.Crc32cIntChecksum - Failed to load Circe JNI library. Falling back to Java based CRC32c provider
-19:53:40.861 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 93.7 msg/s --- 0.7 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.575 ms - med: 3.460 - 95pct: 4.790 - 99pct: 5.308 - 99.9pct: 5.834 - 99.99pct: 6.609 - Max: 6.609
-19:53:50.909 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.437 ms - med: 3.328 - 95pct: 4.656 - 99pct: 5.071 - 99.9pct: 5.519 - 99.99pct: 5.588 - Max: 5.588
-19:54:00.926 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.376 ms - med: 3.276 - 95pct: 4.520 - 99pct: 4.939 - 99.9pct: 5.440 - 99.99pct: 5.490 - Max: 5.490
-19:54:10.940 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.298 ms - med: 3.220 - 95pct: 4.474 - 99pct: 4.926 - 99.9pct: 5.645 - 99.99pct: 5.654 - Max: 5.654
-19:54:20.956 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.1 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.308 ms - med: 3.199 - 95pct: 4.532 - 99pct: 4.871 - 99.9pct: 5.291 - 99.99pct: 5.323 - Max: 5.323
-19:54:30.972 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.249 ms - med: 3.144 - 95pct: 4.437 - 99pct: 4.970 - 99.9pct: 5.329 - 99.99pct: 5.414 - Max: 5.414
-19:54:40.987 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.435 ms - med: 3.361 - 95pct: 4.772 - 99pct: 5.150 - 99.9pct: 5.373 - 99.99pct: 5.837 - Max: 5.837
-^C19:54:44.325 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceProducer - Aggregated throughput stats --- 7286 records sent --- 99.140 msg/s --- 0.775 Mbit/s
-19:54:44.336 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceProducer - Aggregated latency stats --- Latency: mean: 3.383 ms - med: 3.293 - 95pct: 4.610 - 99pct: 5.059 - 99.9pct: 5.588 - 99.99pct: 5.837 - 99.999pct: 6.609 - Max: 6.609
-```
+ **Output**
-From the above test data, you can get the throughput statistics and the write latency statistics. The aggregated statistics is printed when the Pulsar Perf is stopped. You can press **Ctrl**+**C** to stop the Pulsar Perf. If you specify a filename with the `--histogram-file` parameter, a file with the [HdrHistogram](http://hdrhistogram.github.io/HdrHistogram/) formatted test result appears under your directory after Pulsar Perf is stopped. You can also check the test result through [HdrHistogram Plotter](https://hdrhistogram.github.io/HdrHistogram/plotFiles.html). For details about how to check the test result through [HdrHistogram Plotter](https://hdrhistogram.github.io/HdrHistogram/plotFiles.html), see [HdrHistogram Plotter](#hdrhistogram-plotter).
+ ```
+ 19:53:31.459 [pulsar-perf-producer-exec-1-1] INFO org.apache.pulsar.testclient.PerformanceProducer - Created 1 producers
+ 19:53:31.482 [pulsar-timer-5-1] WARN com.scurrilous.circe.checksum.Crc32cIntChecksum - Failed to load Circe JNI library. Falling back to Java based CRC32c provider
+ 19:53:40.861 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 93.7 msg/s --- 0.7 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.575 ms - med: 3.460 - 95pct: 4.790 - 99pct: 5.308 - 99.9pct: 5.834 - 99.99pct: 6.609 - Max: 6.609
+ 19:53:50.909 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.437 ms - med: 3.328 - 95pct: 4.656 - 99pct: 5.071 - 99.9pct: 5.519 - 99.99pct: 5.588 - Max: 5.588
+ 19:54:00.926 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.376 ms - med: 3.276 - 95pct: 4.520 - 99pct: 4.939 - 99.9pct: 5.440 - 99.99pct: 5.490 - Max: 5.490
+ 19:54:10.940 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.298 ms - med: 3.220 - 95pct: 4.474 - 99pct: 4.926 - 99.9pct: 5.645 - 99.99pct: 5.654 - Max: 5.654
+ 19:54:20.956 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.1 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.308 ms - med: 3.199 - 95pct: 4.532 - 99pct: 4.871 - 99.9pct: 5.291 - 99.99pct: 5.323 - Max: 5.323
+ 19:54:30.972 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.249 ms - med: 3.144 - 95pct: 4.437 - 99pct: 4.970 - 99.9pct: 5.329 - 99.99pct: 5.414 - Max: 5.414
+ 19:54:40.987 [main] INFO org.apache.pulsar.testclient.PerformanceProducer - Throughput produced: 100.0 msg/s --- 0.8 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.435 ms - med: 3.361 - 95pct: 4.772 - 99pct: 5.150 - 99.9pct: 5.373 - 99.99pct: 5.837 - Max: 5.837
+ ^C19:54:44.325 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceProducer - Aggregated throughput stats --- 7286 records sent --- 99.140 msg/s --- 0.775 Mbit/s
+ 19:54:44.336 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceProducer - Aggregated latency stats --- Latency: mean: 3.383 ms - med: 3.293 - 95pct: 4.610 - 99pct: 5.059 - 99.9pct: 5.588 - 99.99pct: 5.837 - 99.999pct: 6.609 - Max: 6.609
+ ```
-### Configuration options for `pulsar-perf produce`
+ From the above test data, you can get the throughput statistics and the write latency statistics. The aggregated statistics is printed when the Pulsar Perf is stopped. You can press **Ctrl**+**C** to stop the Pulsar Perf. After the Pulsar Perf is stopped, the [HdrHistogram](http://hdrhistogram.github.io/HdrHistogram/) formatted test result appears under your directory. The document looks like `perf-producer-1589370810837.hgrm`. You can also check the test result through [HdrHistogram Plotter](https://hdrhistogram.github.io/HdrHistogram/plotFiles.html). For details about how to check the test result through [HdrHistogram Plotter](https://hdrhistogram.github.io/HdrHistogram/plotFiles.html), see [HdrHistogram Plotter](#hdrhistogram-plotter).
-You can get all options by executing the `bin/pulsar-perf produce -h` command. Therefore, you can modify these options as required.
+- This example shows how the Pulsar Perf produces messages with `transaction` option.
-The following table lists configuration options available for the `pulsar-perf produce` command.
+ **Input**
+
+ ```shell
+ bin/pulsar-perf produce my-topic -r 10 -m 100 -txn
+ ```
-| Option | Description | Default value|
-|----|----|----|
-| access-mode | Set the producer access mode. Valid values are `Shared`, `Exclusive` and `WaitForExclusive`. | Shared |
-| admin-url | Set the Pulsar admin URL. | N/A |
-| auth-params | Set the authentication parameters, whose format is determined by the implementation of the `configure` method in the authentication plugin class, such as "key1:val1,key2:val2" or "{"key1":"val1","key2":"val2"}". | N/A |
-| auth-plugin | Set the authentication plugin class name. | N/A |
-| listener-name | Set the listener name for the broker. | N/A |
-| batch-max-bytes | Set the maximum number of bytes for each batch. | 4194304 |
-| batch-max-messages | Set the maximum number of messages for each batch. | 1000 |
-| batch-time-window | Set a window for a batch of messages. | 1 ms |
-| busy-wait | Enable or disable Busy-Wait on the Pulsar client. | false |
-| chunking | Configure whether to split the message and publish in chunks if message size is larger than allowed max size. | false |
-| compression | Compress the message payload. | N/A |
-| conf-file | Set the configuration file. | N/A |
-| delay | Mark messages with a given delay. | 0s |
-| encryption-key-name | Set the name of the public key used to encrypt the payload. | N/A |
-| encryption-key-value-file | Set the file which contains the public key used to encrypt the payload. | N/A |
-| exit-on-failure | Configure whether to exit from the process on publish failure. | false |
-| format-class | Set the custom formatter class name. | org.apache.pulsar.testclient.DefaultMessageFormatter |
-| format-payload | Configure whether to format %i as a message index in the stream from producer and/or %t as the timestamp nanoseconds. | false |
-| help | Configure the help message. | false |
-| histogram-file | HdrHistogram output file | N/A |
-| max-connections | Set the maximum number of TCP connections to a single broker. | 100 |
-| max-outstanding | Set the maximum number of outstanding messages. | 1000 |
-| max-outstanding-across-partitions | Set the maximum number of outstanding messages across partitions. | 50000 |
-| message-key-generation-mode | Set the generation mode of message key. Valid options are `autoIncrement`, `random`. | N/A |
-| num-io-threads | Set the number of threads to be used for handling connections to brokers. | 1 |
-| num-messages | Set the number of messages to be published in total. If it is set to 0, it keeps publishing messages. | 0 |
-| num-producers | Set the number of producers for each topic. | 1 |
-| num-test-threads | Set the number of test threads. | 1 |
-| num-topic | Set the number of topics. | 1 |
-| partitions | Configure whether to create partitioned topics with the given number of partitions. | N/A |
-| payload-delimiter | Set the delimiter used to split lines when using payload from a file. | \n |
-| payload-file | Use the payload from an UTF-8 encoded text file and a payload is randomly selected when messages are published. | N/A |
-| producer-name | Set the producer name. | N/A |
-| rate | Set the publish rate of messages across topics. | 100 |
-| send-timeout | Set the sendTimeout. | 0 |
-| separator | Set the separator between the topic and topic number. | - |
-| service-url | Set the Pulsar service URL. | |
-| size | Set the message size. | 1024 bytes |
-| stats-interval-seconds | Set the statistics interval. If it is set to 0, statistics is disabled. | 0 |
-| test-duration | Set the test duration. If it is set to 0, it keeps publishing tests. | 0s |
-| trust-cert-file | Set the path for the trusted TLS certificate file. | <empty string> |
-| warmup-time | Set the warm-up time. | 1s |
-| tls-allow-insecure | Set the allowed insecure TLS connection. | N/A |
+ **Output**
+ ```shell
+ 2021-10-11T13:36:15,595+0800 INFO [Thread-3] o.a.p.t.PerformanceProducer@499 - --- Transaction : 2 transaction end successfully ---0 transaction end failed --- 0.200 Txn/s
+
+ 2021-10-11T13:36:15,614+0800 INFO [Thread-3] o.a.p.t.PerformanceProducer@503 - Throughput produced: 100 msg --- 0.0 msg/s --- 0.1 Mbit/s --- failure 0.0 msg/s --- Latency: mean: 3.067 ms - med: 3.104 - 95pct: 3.747 - 99pct: 4.619 - 99.9pct: 6.760 - 99.99pct: 6.760 - Max: 6.760
+
+ 2021-10-11T13:36:15,710+0800 INFO [pulsar-perf-producer-exec-46-1] o.a.p.t.PerformanceProducer@834 - Aggregated latency stats --- Latency: mean: 3.067 ms - med: 3.104 - 95pct: 3.747 - 99pct: 4.619 - 99.9pct: 6.760 - 99.99pct: 6.760 - 99.999pct: 6.760 - Max: 6.760
+
+ 2021-10-11T13:36:29,976+0800 INFO [Thread-4] o.a.p.t.PerformanceProducer@815 - --- Transaction : 2 transaction end successfully --- 0 transaction end failed --- 2 transaction open successfully --- 0 transaction open failed --- 12.237 Txn/s
+
+ 2021-10-11T13:36:29,976+0800 INFO [Thread-4] o.a.p.t.PerformanceProducer@824 - Aggregated throughput stats --- 102 records sent --- 4.168 msg/s --- 0.033 Mbit/s
+ ```
+
## Consume messages
-This example shows how the Pulsar Perf consumes messages with default options.
+> **Tip**
+>
+> For the latest and complete information about `pulsar-perf`, including commands, flags, descriptions, and more, see [`pulsar-perf`](https://pulsar.apache.org/tools/pulsar-perf/) or [here](reference-cli-tools.md#pulsar-perf).
-```
-bin/pulsar-perf consume my-topic
+- This example shows how the Pulsar Perf consumes messages with **default** options.
+
+ **Input**
+
+ > **Note**
+ >
+ > If you have not created a topic (in this example, it is _my-topic_) before, the broker creates a new topic without partitions and messages, then the consumer can not receive any messages. Consequently, before using `pulsar-perf consume`, make sure your topic has enough messages to consume.
+
+ ```
+ bin/pulsar-perf consume my-topic
+ ```
+
+ After the command is executed, the test data is continuously output on the Console.
+
+ **Output**
+
+ ```
+ 20:35:37.071 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Start receiving from 1 consumers on 1 topics
+ 20:35:41.150 [pulsar-client-io-1-9] WARN com.scurrilous.circe.checksum.Crc32cIntChecksum - Failed to load Circe JNI library. Falling back to Java based CRC32c provider
+ 20:35:47.092 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 59.572 msg/s -- 0.465 Mbit/s --- Latency: mean: 11.298 ms - med: 10 - 95pct: 15 - 99pct: 98 - 99.9pct: 137 - 99.99pct: 152 - Max: 152
+ 20:35:57.104 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 99.958 msg/s -- 0.781 Mbit/s --- Latency: mean: 9.176 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 18 - Max: 18
+ 20:36:07.115 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 100.006 msg/s -- 0.781 Mbit/s --- Latency: mean: 9.316 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
+ 20:36:17.125 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 100.085 msg/s -- 0.782 Mbit/s --- Latency: mean: 9.327 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
+ 20:36:27.136 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 99.900 msg/s -- 0.780 Mbit/s --- Latency: mean: 9.404 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
+ 20:36:37.147 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 99.985 msg/s -- 0.781 Mbit/s --- Latency: mean: 8.998 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
+ ^C20:36:42.755 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceConsumer - Aggregated throughput stats --- 6051 records received --- 92.125 msg/s --- 0.720 Mbit/s
+ 20:36:42.759 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceConsumer - Aggregated latency stats --- Latency: mean: 9.422 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 98 - 99.99pct: 137 - 99.999pct: 152 - Max: 152
+ ```
+
+ From the output test data, you can get the throughput statistics and the end-to-end latency statistics. The aggregated statistics is printed after the Pulsar Perf is stopped. You can press **Ctrl**+**C** to stop the Pulsar Perf.
+
+- This example shows how the Pulsar Perf consumes messages with `transaction` option.
+
+ **Input**
+
+ ```shell
+ bin/pulsar-perf consume my-topic -r 10 -txn -ss mysubName -st Exclusive -sp Earliest -ntxn 10
+ ```
+
+ > **Note**
+ >
+ > If you have not created a topic (in this example, it is _my-topic_) before, the broker creates a new topic without partitions and messages, then the consumer can not receive any messages. Consequently, before using `pulsar-perf consume`, make sure your topic has enough messages to consume.
+
+ **Output**
+
+ ```shell
+ 2021-10-11T13:43:36,052+0800 INFO [Thread-3] o.a.p.t.PerformanceConsumer@538 - --- Transaction: 6 transaction end successfully --- 0 transaction end failed --- 0.199 Txn/s --- AckRate: 9.952 msg/s
+
+ 2021-10-11T13:43:36,065+0800 INFO [Thread-3] o.a.p.t.PerformanceConsumer@545 - Throughput received: 306 msg --- 9.952 msg/s -- 0.000 Mbit/s --- Latency: mean: 26177.380 ms - med: 26128 - 95pct: 30531 - 99pct: 30923 - 99.9pct: 31021 - 99.99pct: 31021 - Max: 31021
+
+ 2021-10-11T13:43:59,854+0800 INFO [Thread-5] o.a.p.t.PerformanceConsumer@579 - -- Transaction: 10 transaction end successfully --- 0 transaction end failed --- 10 transaction open successfully --- 0 transaction open failed --- 0.185 Txn/s
+
+ 2021-10-11T13:43:59,854+0800 INFO [Thread-5] o.a.p.t.PerformanceConsumer@588 - Aggregated throughput stats --- 505 records received --- 9.345 msg/s --- 0.000 Mbit/s--- AckRate: 9.27065308842743 msg/s --- ack failed 4 msg
+
+ 2021-10-11T13:43:59,882+0800 INFO [Thread-5] o.a.p.t.PerformanceConsumer@601 - Aggregated latency stats --- Latency: mean: 50593.000 ms - med: 50593 - 95pct: 50593 - 99pct: 50593 - 99.9pct: 50593 - 99.99pct: 50593 - 99.999pct: 50593 - Max: 50593
+ ```
+
+## Transactions
+
+This section shows how Pulsar Perf runs transactions. For more information, see [Pulsar transactions](txn-why.md).
+
+### Use transaction
+
+This example executes 50 transactions. Each transaction sends and receives 1 message (default).
+
+**Input**
+
+```shell
+bin/pulsar-perf transaction --topics-c myConsumerTopic --topics-p MyproduceTopic -threads 1 -ntxn 50 -ss testSub -nmp 1 -nmc 1
```
-After the command is executed, the test data is continuously output on the Console.
+> **Note**
+>
+> If you have not created a topic (in this example, it is _myConsumerTopic_) before, the broker creates a new topic without partitions and messages, then the consumer can not receive any messages. Consequently, before using `pulsar-perf transaction`, make sure your topic has enough messages to consume.
**Output**
-```
-20:35:37.071 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Start receiving from 1 consumers on 1 topics
-20:35:41.150 [pulsar-client-io-1-9] WARN com.scurrilous.circe.checksum.Crc32cIntChecksum - Failed to load Circe JNI library. Falling back to Java based CRC32c provider
-20:35:47.092 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 59.572 msg/s -- 0.465 Mbit/s --- Latency: mean: 11.298 ms - med: 10 - 95pct: 15 - 99pct: 98 - 99.9pct: 137 - 99.99pct: 152 - Max: 152
-20:35:57.104 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 99.958 msg/s -- 0.781 Mbit/s --- Latency: mean: 9.176 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 18 - Max: 18
-20:36:07.115 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 100.006 msg/s -- 0.781 Mbit/s --- Latency: mean: 9.316 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
-20:36:17.125 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 100.085 msg/s -- 0.782 Mbit/s --- Latency: mean: 9.327 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
-20:36:27.136 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 99.900 msg/s -- 0.780 Mbit/s --- Latency: mean: 9.404 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
-20:36:37.147 [main] INFO org.apache.pulsar.testclient.PerformanceConsumer - Throughput received: 99.985 msg/s -- 0.781 Mbit/s --- Latency: mean: 8.998 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 17 - 99.99pct: 17 - Max: 17
-^C20:36:42.755 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceConsumer - Aggregated throughput stats --- 6051 records received --- 92.125 msg/s --- 0.720 Mbit/s
-20:36:42.759 [Thread-1] INFO org.apache.pulsar.testclient.PerformanceConsumer - Aggregated latency stats --- Latency: mean: 9.422 ms - med: 9 - 95pct: 15 - 99pct: 16 - 99.9pct: 98 - 99.99pct: 137 - 99.999pct: 152 - Max: 152
+```shell
+2021-10-11T14:37:27,863+0800 INFO [Thread-5] o.a.p.t.PerformanceProducer@613 - Messages ack aggregated latency stats --- Latency: mean: 29.239 ms - med: 26.799 - 95pct: 46.696 - 99pct: 55.660 - 99.9pct: 55.660 - 99.99pct: 55.660 - 99.999pct: 55.660 - Max: 55.660 {}
+
+2021-10-11T14:37:19,391+0800 INFO [Thread-4] o.a.p.t.PerformanceProducer@525 - Throughput transaction: 50 transaction executes --- 4.999 transaction/s ---send Latency: mean: 31.368 ms - med: 28.369 - 95pct: 55.631 - 99pct: 57.764 - 99.9pct: 57.764 - 99.99pct: 57.764 - Max: 57.764---ack Latency: mean: 29.239 ms - med: 26.799 - 95pct: 46.696 - 99pct: 55.660 - 99.9pct: 55.660 - 99.99pct: 55.660 - Max: 55.660 {}
+
+2021-10-11T14:37:26,625+0800 INFO [Thread-5] o.a.p.t.PerformanceProducer@571 - Aggregated throughput stats --- 50 transaction executed --- 2.718 transaction/s --- 50 transaction open successfully --- 0 transaction open failed --- 50 transaction end successfully --- 0 transaction end failed--- 0 message ack failed --- 0 message send failed--- 50 message ack success --- 50 message send success {}
```
-From the output test data, you can get the throughput statistics and the end-to-end latency statistics. The aggregated statistics is printed after the Pulsar Perf is stopped. You can press **Ctrl**+**C** to stop the Pulsar Perf.
+### Disable Transaction
-### Configuration options for `pulsar-perf consume`
+This example disables transactions.
-You can get all options by executing the `bin/pulsar-perf consume -h` command. Therefore, you can modify these options as required.
+**Input**
-The following table lists configuration options available for the `pulsar-perf consume` command.
+```shell
+bin/pulsar-perf transaction --topics-c myConsumerTopic --topics-p myproduceTopic -threads 1 -ntxn 50 -ss testSub --txn-disEnable
+```
-| Option | Description | Default value |
-|----|----|----|
-| acks-delay-millis | Set the acknowledgment grouping delay in milliseconds. | 100 ms |
-| auth-params | Set the authentication parameters, whose format is determined by the implementation of the `configure` method in the authentication plugin class, such as "key1:val1,key2:val2" or "{"key1":"val1","key2":"val2"}". | N/A |
-| auth-plugin | Set the authentication plugin class name. | N/A |
-| auto_ack_chunk_q_full | Configure whether to automatically ack for the oldest message in receiver queue if the queue is full. | false |
-| listener-name | Set the listener name for the broker. | N/A |
-| batch-index-ack | Enable or disable the batch index acknowledgment. | false |
-| busy-wait | Enable or disable Busy-Wait on the Pulsar client. | false |
-| conf-file | Set the configuration file. | N/A |
-| encryption-key-name | Set the name of the public key used to encrypt the payload. | N/A |
-| encryption-key-value-file | Set the file which contains the public key used to encrypt the payload. | N/A |
-| help | Configure the help message. | false |
-| histogram-file | HdrHistogram output file | N/A |
-| expire_time_incomplete_chunked_messages | Set the expiration time for incomplete chunk messages (in milliseconds). | 0 |
-| max-connections | Set the maximum number of TCP connections to a single broker. | 100 |
-| max_chunked_msg | Set the max pending chunk messages. | 0 |
-| num-consumers | Set the number of consumers for each topic. | 1 |
-| num-io-threads |Set the number of threads to be used for handling connections to brokers. | 1 |
-| num-subscriptions | Set the number of subscriptions (per topic). | 1 |
-| num-topic | Set the number of topics. | 1 |
-| pool-messages | Configure whether to use the pooled message. | true |
-| rate | Simulate a slow message consumer (rate in msg/s). | 0.0 |
-| receiver-queue-size | Set the size of the receiver queue. | 1000 |
-| receiver-queue-size-across-partitions | Set the max total size of the receiver queue across partitions. | 50000 |
-| replicated | Configure whether the subscription status should be replicated. | false |
-| service-url | Set the Pulsar service URL. | |
-| stats-interval-seconds | Set the statistics interval. If it is set to 0, statistics is disabled. | 0 |
-| subscriber-name | Set the subscriber name prefix. | |
-| subscription-position | Set the subscription position. Valid values are `Latest`, `Earliest`.| Latest |
-| subscription-type | Set the subscription type. <li> Exclusive <li> Shared <li> Failover <li> Key_Shared | Exclusive |
-| test-duration | Set the test duration (in seconds). If the value is 0 or smaller than 0, it keeps consuming messages. | 0 |
-| tls-allow-insecure | Set the allowed insecure TLS connection. | N/A |
-| trust-cert-file | Set the path for the trusted TLS certificate file. | <empty string> |
+> **Note**
+>
+> If you have not created a topic (in this example, it is _myConsumerTopic_) before, the broker creates a new topic without partitions and messages, then the consumer can not receive any messages. Consequently, before using `pulsar-perf transaction --txn-disEnable`, make sure your topic has enough messages to consume.
+
+**Output**
+
+```shell
+2021-10-11T16:48:26,876+0800 INFO [Thread-4] o.a.p.t.PerformanceProducer@529 - Throughput task: 50 task executes --- 4.999 task/s ---send Latency: mean: 10.002 ms - med: 9.875 - 95pct: 11.733 - 99pct: 15.995 - 99.9pct: 15.995 - 99.99pct: 15.995 - Max: 15.995---ack Latency: mean: 0.051 ms - med: 0.020 - 95pct: 0.059 - 99pct: 1.377 - 99.9pct: 1.377 - 99.99pct: 1.377 - Max: 1.377
+
+2021-10-11T16:48:29,222+0800 INFO [Thread-5] o.a.p.t.PerformanceProducer@617 - Messages ack aggregated latency stats --- Latency: mean: 0.051 ms - med: 0.020 - 95pct: 0.059 - 99pct: 1.377 - 99.9pct: 1.377 - 99.99pct: 1.377 - 99.999pct: 1.377 - Max: 1.377
+
+2021-10-11T16:48:29,246+0800 INFO [Thread-5] o.a.p.t.PerformanceProducer@629 - Messages send aggregated latency stats --- Latency: mean: 10.002 ms - med: 9.875 - 95pct: 11.733 - 99pct: 15.995 - 99.9pct: 15.995 - 99.99pct: 15.995 - 99.999pct: 15.995 - Max: 15.995
+
+2021-10-11T16:48:29,117+0800 INFO [Thread-5] o.a.p.t.PerformanceProducer@602 - Aggregated throughput stats --- 50 task executed --- 4.025 task/s --- 0 message ack failed --- 0 message send failed--- 50 message ack success --- 50 message send success
+```
## Configurations
diff --git a/site2/docs/reference-cli-tools.md b/site2/docs/reference-cli-tools.md
index f1196ba..a8bb205 100644
--- a/site2/docs/reference-cli-tools.md
+++ b/site2/docs/reference-cli-tools.md
@@ -430,6 +430,7 @@
* `monitor-brokers`
* `simulation-client`
* `simulation-controller`
+* `transaction`
* `help`
Environment variables
@@ -491,6 +492,17 @@
|`--trust-cert-file`|Path for the trusted TLS certificate file||
|`--tls-allow-insecure`|Allow insecure TLS connection||
+Below are **transaction** related options.
+
+If you want `--txn-timeout`, `--numMessage-perTransaction`, `-nmt`, `-ntxn`, or `-abort` take effect, set `--txn-enable` to true.
+
+|Flag|Description|Default|
+|---|---|---|
+`-tto`, `--txn-timeout`|Set the time of transaction timeout (in second). |10
+`-nmt`, `--numMessage-perTransaction`|The number of messages acknowledged by a transaction. |50
+`-txn`, `--txn-enable`|Enable or disable a transaction.|false
+`-ntxn`|The number of opened transactions. 0 means the number of transactions is unlimited. |0
+`-abort`|Abort a transaction. |true
### `produce`
Run a producer
@@ -547,6 +559,16 @@
|`--warmup-time`|Warm-up time in seconds|1|
|`--tls-allow-insecure`|Allow insecure TLS connection||
+Below are **transaction** related options.
+
+If you want `--txn-timeout`, `--numMessage-perTransaction`, or `-abort` take effect, set `--txn-enable` to true.
+
+|Flag|Description|Default|
+|---|---|---|
+`-tto`, `--txn-timeout`|Set the time of transaction timeout (in second). |5
+`-nmt`, `--numMessage-perTransaction`|The number of messages acknowledged by a transaction. |50
+`-txn`, `--txn-enable`|Enable or disable a transaction.|true
+`-abort`|Abort a transaction. |true
### `read`
Run a topic reader
@@ -685,6 +707,43 @@
|`--cluster`|The cluster to test on||
|`-h`, `--help`|Help message|false|
+### `transaction`
+
+Run a transaction. For more information, see [Pulsar transactions](txn-why.md).
+
+**Usage**
+
+```bash
+$ pulsar-perf transaction options
+```
+
+**Options**
+
+|Flag|Description|Default|
+|---|---|---|
+`-au`, `--admin-url`|Pulsar admin URL.|N/A
+`--conf-file`|Configuration file.|N/A
+`-h`, `--help`|Help messages.|N/A
+`-c`, `--max-connections`|Maximum number of TCP connections to a single broker.|100
+`-ioThreads`, `--num-io-threads`|Set the number of threads to be used for handling connections to brokers. |1
+`-ns`, `--num-subscriptions`|Number of subscriptions per topic.|1
+`-threads`, `--num-test-threads`|Number of test threads. <br /><br />This thread is for a new transaction to ack messages from consumer topics, produce messages to producer topics, and commit or abort this transaction. <br /><br /> Increasing the number of threads increases the parallelism of the performance test, consequently, it increases the intensity of the stress test.|1
+`-nmc`, `--numMessage-perTransaction-consume`|Set the number of messages consumed in a transaction. <br /><br /> If transaction is disabled, it means the number of messages consumed in a task instead of in a transaction.|1
+`-nmp`, `--numMessage-perTransaction-produce`|Set the number of messages produced in a transaction. <br /><br />If transaction is disabled, it means the number of messages produced in a task instead of in a transaction.|1
+`-ntxn`, `--number-txn`|Set the number of transactions. <br /><br /> 0 means the number of transactions is unlimited. <br /><br /> If transaction is disabled, it means the number of tasks instead of transactions. |0
+`-np`, `--partitions`|Create partitioned topics with a given number of partitions. <br /><br /> 0 means not trying to create a topic.
+`-q`, `--receiver-queue-size`|Size of the receiver queue.|1000
+`-u`, `--service-url`|Pulsar service URL.|N/A
+`-sp`, `--subscription-position`|Subscription position.|Earliest
+`-st`, `--subscription-type`|Subscription type.|Shared
+`-ss`, `--subscriptions`|A list of subscriptions to consume. <br /><br /> For example, sub1,sub2.|[sub]
+`-time`, `--test-duration`|Test duration (in second). <br /><br /> 0 means keeping publishing messages.|0
+`--topics-c`|All topics assigned to consumers.|[test-consume]
+`--topics-p`|All topics assigned to producers . |[test-produce]
+`--txn-disEnable`|Disable transaction.|true
+`-tto`, `--txn-timeout`|Set the time of transaction timeout (in second). <br /><br /> If you want `--txn-timeout` takes effect, set `--txn-enable` to true.|5
+`-abort`|Abort the transaction. <br /><br /> If you want `-abort` takes effect, set `--txn-disEnable` to false.|true
+`-txnRate`|Set the rate of opened transactions or tasks. <br /><br /> 0 means no limit.|0
### `help`
This help message
