---
id: performance-pulsar-perf
title: Pulsar Perf
sidebar_label: Pulsar Perf
---

The Pulsar Perf is a built-in performance test tool for Apache Pulsar. You can use the Pulsar Perf to test message writing or reading performance. For detailed information about performance tuning, see [here](https://streamnative.io/en/blog/tech/2021-01-14-pulsar-architecture-performance-tuning).

## 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).

```
bin/pulsar-perf produce my-topic
```

After the command is executed, the test data is continuously output on the Console.

**Output**

```
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
```

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).

### Configuration options for `pulsar-perf produce`

You can get all options by executing the `bin/pulsar-perf produce -h` command. Therefore, you can modify these options as required.

The following table lists configuration options available for the `pulsar-perf produce` command.

| 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 |

## Consume messages

This example shows how the Pulsar Perf consumes messages with default options.

```
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.

### Configuration options for `pulsar-perf consume`

You can get all options by executing the `bin/pulsar-perf consume -h` command. Therefore, you can modify these options as required.

The following table lists configuration options available for the `pulsar-perf consume` command.

| 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> |

## Configurations

By default, the Pulsar Perf uses `conf/client.conf` as the default configuration and uses `conf/log4j2.yaml` as the default Log4j configuration. If you want to connect to other Pulsar clusters, you can update the `brokerServiceUrl` in the client configuration.

You can use the following commands to change the configuration file and the Log4j configuration file.

```
export PULSAR_CLIENT_CONF=<your-config-file>
export PULSAR_LOG_CONF=<your-log-config-file>
```

In addition, you can use the following command to configure the JVM configuration through environment variables:

```
export PULSAR_EXTRA_OPTS='-Xms4g -Xmx4g -XX:MaxDirectMemorySize=4g'
```

## HdrHistogram Plotter

The [HdrHistogram Plotter](https://hdrhistogram.github.io/HdrHistogram/plotFiles.html) is a visualization tool for checking Pulsar Perf test results, which makes it easier to observe the test results.

To check test results through the HdrHistogram Plotter, follow these steps:

1. Clone the HdrHistogram repository from GitHub to the local.

    ```
    git clone https://github.com/HdrHistogram/HdrHistogram.git
    ```

2. Switch to the HdrHistogram folder.

    ```
    cd HdrHistogram
    ```
3. Install the HdrHistogram Plotter.

    ```
    mvn clean install -DskipTests
    ```
4. Transform the file generated by the Pulsar Perf.

    ```
    ./HistogramLogProcessor -i <hgrm file path that pulsar-perf generated> -o <output file>
    ```

5. You will get two output files. Upload the output file with the filename extension of .hgrm to the [HdrHistogram Plotter](https://hdrhistogram.github.io/HdrHistogram/plotFiles.html).

6. Check the test result through the Graphical User Interface of the HdrHistogram Plotter, as shown blow.

    ![](assets/perf-produce.png)