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. 更多性能优化细节，请参阅 这里。

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.

  1. bin/pulsar-perf produce my-topic

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

输出

  1. 19:53:31.459 [pulsar-perf-producer-exec-1-1] INFO  org.apache.pulsar.testclient.PerformanceProducer - Created 1 producers
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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
  8. 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
  9. 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
  10. ^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
  11. 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. After the Pulsar Perf is stopped, the 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. For details about how to check the test result through HdrHistogram Plotter, see 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.

选项说明默认值
access-mode设置生产者访问模式。 有效值是 Shared, Exclusive 和 WaitForExclusive.Shared（共享）
admin-url设置 Pulsar admin URL。N/A
auth-params设置认证参数，格式由认证插件类中configure方法的实现决定的，如”key1:val1,key2:val2” 或 “{“key1”:”val1”,”key2”:”val2”}”。N/A
auth_plugin设置认证插件类名N/A
listener-name为broker指定监听器名称。N/A
batch-max-bytes设置每个批消息的最大字节数4194304
batch-max-messages设置每个批消息的最大消息数1000
batch-time-window设置每批消息的窗口大小1 ms
busy-wait在 Pulsar 客户端启用或禁用 Busy-Wait.false
chunking配置如果消息尺寸大于允许的最大尺寸，是否分割消息并在区块中发布。false
compression指定消息载荷（ payload）的压缩格式N/A
conf-file设置配置文件N/A
delay给消息标记延迟时间0s
encryption-key-name设置用于加密有效载荷的公钥名称N/A
encryption-key-value-file设置包含用于加密有效载荷的公钥文件N/A
exit-on-failure配置发布失败时是否退出进程false
format-classSet the custom formatter class name.org.apache.pulsar.testclient.DefaultMessageFormatter
format-payloadConfigure whether to format %i as a message index in the stream from producer and/or %t as the timestamp nanoseconds.false
help配置帮助信息false
max-connections设置单个broker的最大TCP连接数100
max-outstanding设置未处理消息的最大数量1000
max-outstanding-across-partitions设置跨分区场景下的最大未处理消息数50000
message-key-generation-modeSet the generation mode of message key. Valid options are autoIncrement, random.N/A
num-io-threadsSet the number of threads to be used for handling connections to brokers.1
num-messages设置要发布的消息总数。 如果设为0则持续发布消息0
num-producers设置每个主题的生产者数量1
num-test-threads设置测试线程数量1
num-topic设置主题数量1
分区Configure whether to create partitioned topics with the given number of partitions.N/A
payload-delimiter当使用来自文件的有效载荷（ payload）时，设置每行之间的分隔符。\n
payload-file使用 UTF-8 编码的文本文件的有效载荷（payload），会在发布消息时随机选择一个有效载荷。N/A
producer-nameSet the producer name.N/A
rate设置跨主题的消息发布速率100
send-timeoutSet the sendTimeout.0
separatorSet the separator between the topic and topic number.-
service-url设置 Pulsar 服务的 URL
size设置消息大小1024 bytes
stats-interval-seconds设置统计间隔。 如果置为0，则不统计。0
test-duration设置测试持续时间。 如果设为0则持续保持发布测试0s
trust-cert-file设置受信的TLS证书文件所在路径
warmup-time设置预热时间1s
tls-allow-insecureSet the allowed insecure TLS connection.N/A

Consume messages

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

  1. bin/pulsar-perf consume my-topic

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

输出

  1. 20:35:37.071 [main] INFO  org.apache.pulsar.testclient.PerformanceConsumer - Start receiving from 1 consumers on 1 topics
  2. 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
  3. 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
  4. 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
  5. 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
  6. 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
  7. 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
  8. 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
  9. ^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
  10. 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.

选项说明默认值
acks-delay-millis设置确认分组的延迟时间，以毫秒为单位100 ms
auth-params设置认证参数，格式由认证插件类中configure方法的实现决定的，如”key1:val1,key2:val2” 或 “{“key1”:”val1”,”key2”:”val2”}”。N/A
auth_plugin设置认证插件类名N/A
auto_ack_chunk_q_full配置如果队列满时，是否自动确认接收器队列中最旧的消息。false
listener-name为broker指定监听器名称。N/A
batch-index-ack开启或禁用批量索引确认false
busy-wait在 Pulsar 客户端启用或禁用 Busy-Wait.false
conf-file设置配置文件N/A
encryption-key-name设置用于加密有效载荷的公钥名称N/A
encryption-key-value-file设置包含用于加密有效载荷的公钥文件N/A
help配置帮助信息false
expire_time_incomplete_chunked_messagesSet the expiration time for incomplete chunk messages (in milliseconds).0
max-connections设置单个broker的最大TCP连接数100
max_chunked_msgSet the max pending chunk messages.0
num-consumers设定每个主题的消费者数量1
num-io-threadsSet the number of threads to be used for handling connections to brokers.1
num-subscriptionsSet the number of subscriptions (per topic).1
num-topic设置主题数量1
pool-messagesConfigure whether to use the pooled message.true
rate模拟一个慢速消费者消费数据(速率 消息/秒)0.0
receiver-queue-size设置接收队列大小1000
receiver-queue-size-across-partitionsSet the max total size of the receiver queue across partitions.50000
replicated配置是否复制订阅状态。false
service-url设置 Pulsar 服务的 URL
stats-interval-seconds设置统计间隔。 如果置为0，则不统计。0
subscriber-name设置订阅者名称前缀sub
subscription-positionSet the subscription position. Valid values are Latest, Earliest.Latest
subscription-type设置订阅类型
  • Exclusive
  • Shared（共享）
  • Failover（灾备）
  • Key_Shared
    		• Exclusive
    test-durationSet the test duration (in seconds). If the value is 0 or smaller than 0, it keeps consuming messages.0
    tls-allow-insecureSet the allowed insecure TLS connection.N/A
    trust-cert-file设置受信的TLS证书文件所在路径

    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.

    1. export PULSAR_CLIENT_CONF=<你的配置文件>
    2. export PULSAR_LOG_CONF=<你的日志配置文件>

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

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

    HdrHistogram Plotter

    The HdrHistogram Plotter 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. 从 GitHub 上克隆 HdrHistogram 仓库到本地

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

    2. 切换到HdrHistogram文件夹

      1. cd HdrHistogram

    3. 安装HdrHistogram 绘图器

      1. mvn clean install -DskipTests

    4. 转换 Pulsar Perf 生成的文件

      1. ./HistogramLogProcessor -i <pulsar-perf生成的hgrm文件路径> -o <输出文件>

    5. 你将获得两个文件。 将扩展名为 .hgrm 的输出文件上传到HdrHistogram Plotter。

    6. 可通过 HdrHistogram Plotter 的图形化界面检查测试结果，如图所示：

      Pulsar Perf - 图1