Pulsar command-line tools
Pulsar version 2.0
The documentation that you’re reading is for the 2.0 release of Apache Pulsar. For more information on Pulsar 2.0, see this guide.
Pulsar offers several command-line tools that you can use for managing Pulsar installations, performance testing, using command-line producers and consumers, and more.
All Pulsar command-line tools can be run from the bin
directory of your installed Pulsar package. The following tools are currently documented:
Getting help
You can get help for any CLI tool, command, or subcommand using the --help
flag, or -h
for short. Here’s an example:
$ bin/pulsar-admin clusters --help
pulsar
The pulsar
tool is used to start Pulsar components, such as bookies and ZooKeeper, in the foreground.
These processes can also be started in the background, using nohup, using the pulsar-daemon
tool, which has the same command interface as pulsar
.
Usage
$ pulsar command
Commands
-
bookie
-
broker
-
compact-topic
-
discovery
-
configuration-store
-
initialize-cluster-metadata
-
proxy
-
standalone
-
websocket
-
zookeeper
-
zookeeper-shell
-
zookeeper-shell
Example
$ pulsar broker \
--conf /path/to/broker.conf
Environment variables
The table below lists the environment variables that you can use to configure the pulsar
tool.
Variable | Description | Default |
---|---|---|
PULSAR_LOG_CONF |
Log4j configuration file | conf/log4j2.yaml |
PULSAR_BROKER_CONF |
Configuration file for broker | conf/broker.conf |
PULSAR_BOOKKEEPER_CONF |
Configuration file for bookie | conf/bookkeeper.conf |
PULSAR_ZK_CONF |
Configuration file for zookeeper | conf/zookeeper.conf |
PULSAR_CONFIGURATION_STORE_CONF |
Configuration file for the configuration store | conf/global_zookeeper.conf |
PULSAR_DISCOVERY_CONF |
Configuration file for discovery service | conf/discovery.conf |
PULSAR_WEBSOCKET_CONF |
Configuration file for websocket proxy | conf/websocket.conf |
PULSAR_STANDALONE_CONF |
Configuration file for standalone | conf/standalone.conf |
PULSAR_EXTRA_OPTS |
Extra options to be passed to the jvm | |
PULSAR_EXTRA_CLASSPATH |
Extra paths for Pulsar's classpath | |
PULSAR_PID_DIR |
Folder where the pulsar server PID file should be stored | |
PULSAR_STOP_TIMEOUT |
Wait time before forcefully killing the Bookie server instance if attempts to stop it are not successful |
bookie
Starts up a bookie server
Usage
$ pulsar bookie
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration for the bookie server |
|
-readOnly
|
Force start a read-only bookie server |
false |
-withAutoRecovery
|
Start auto-recovery service bookie server |
false |
Example
$ pulsar bookie \
-readOnly \
-withAutoRecovery \
--conf /path/to/bookkeeper.conf
broker
Starts up a Pulsar broker
Usage
$ pulsar broker
Options
Flag | Description | Default |
---|---|---|
-c
,
--broker-conf
|
Configuration file for the broker |
|
-bc
,
--bookie-conf
|
Configuration file for BookKeeper |
|
-rb
,
--run-bookie
|
Run a BookKeeper bookie on the same host as the Pulsar broker |
false |
-ra
,
--run-bookie-autorecovery
|
Run a BookKeeper autorecovery daemon on the same host as the Pulsar broker |
false |
Example
$ pulsar broker \
--conf /path/to/broker.conf
compact-topic
Run compaction against a Pulsar topic
Usage
$ pulsar compact-topic
Options
Flag | Description | Default |
---|---|---|
-t
,
--topic
|
The Pulsar topic that you would like to compact |
Example
$ pulsar compact-topic \
--topic topic-to-compact
discovery
Run a discovery server
Usage
$ pulsar discovery
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration file for the discovery service |
Example
$ pulsar discovery \
--conf /path/to/discovery.conf
configuration-store
Starts up the Pulsar configuration store
Usage
$ pulsar configuration-store
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration file for the configuration store |
initialize-cluster-metadata
One-time cluster metadata initialization
Usage
$ pulsar initialize-cluster-metadata
Options
Flag | Description | Default |
---|---|---|
-ub
,
--broker-service-url
|
The broker service URL for the new cluster |
|
-tb
,
--broker-service-url-tls
|
The broker service URL for the new cluster with TLS encryption |
|
-c
,
--cluster
|
Cluster name |
|
--configuration-store
|
The configuration store quorum connection string |
|
-uw
,
--web-service-url
|
The web service URL for the new cluster |
|
-tw
,
--web-service-url-tls
|
The web service URL for the new cluster with TLS encryption |
|
-zk
,
--zookeeper
|
The local ZooKeeper quorum connection string |
proxy
Manages the Pulsar proxy
Usage
$ pulsar proxy
Options
Flag | Description | Default |
---|---|---|
-c
,
--config
|
Path to a Pulsar proxy configuration file |
|
--configuration-store
|
Configuration store connection string |
|
-zk
,
--zookeeper-servers
|
Local ZooKeeper connection string |
Example
$ pulsar proxy \
--zookeeper-servers zk-0,zk-1,zk2 \
--configuration-store zk-0,zk-1,zk-2
standalone
Run a broker service with local bookies and local ZooKeeper
Usage
$ pulsar standalone
Options
Flag | Description | Default |
---|---|---|
-a
,
--advertised-address
|
The standalone broker advertised address |
|
--bookkeeper-dir
|
Local bookies’ base data directory |
data/standalone/bookeeper |
--bookkeeper-port
|
Local bookies’ base port |
3181 |
-c
,
--config
|
Configuration file path |
|
--no-broker
|
Only start ZooKeeper and BookKeeper services, not the broker |
false |
--num-bookies
|
The number of local bookies |
1 |
--only-broker
|
Only start the Pulsar broker service (not ZooKeeper or BookKeeper) |
|
--wipe-data
|
Clean up previous ZooKeeper/BookKeeper data |
|
--zookeeper-dir
|
Local ZooKeeper’s data directory |
data/standalone/zookeeper |
--zookeeper-port
|
Local ZooKeeper’s port |
2181 |
websocket
Usage
$ pulsar websocket
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration file for WebSocket service |
zookeeper
Starts up a ZooKeeper cluster
Usage
$ pulsar zookeeper
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration file for ZooKeeper |
zookeeper-shell
Connects to a running ZooKeeper cluster using the ZooKeeper shell
Usage
$ pulsar zookeeper-shell
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration file for ZooKeeper |
zookeeper-shell
Opens up a shell client to the ZooKeeper cluster used by Pulsar
Usage
$ pulsar zookeeper-shell
pulsar-admin
The pulsar-admin
tool enables you to manage Pulsar installations, including clusters, brokers, namespaces, tenants, and more.
Usage
$ pulsar-admin command
Commands
-
broker-stats
-
brokers
-
clusters
-
functions
-
namespaces
-
ns-isolation-policy
-
topics
-
tenants
-
resource-quotas
broker-stats
Operations to collect broker statistics
Usage
$ pulsar-admin broker-stats subcommand
Subcommands
allocator-stats
Dump allocator stats
Usage
$ pulsar-admin broker-stats allocator-stats allocator-name
destinations
Dump topic stats
Usage
$ pulsar-admin broker-stats destinations
Options
Flag | Description | Default |
---|---|---|
-i
,
--indent
|
Indent JSON output |
false |
mbeans
Dump Mbean stats
Usage
$ pulsar-admin broker-stats mbeans
Options
Flag | Description | Default |
---|---|---|
-i
,
--indent
|
Indent JSON output |
false |
monitoring-metrics
dump metrics for Monitoring
Usage
$ pulsar-admin broker-stats monitoring-metrics
Options
Flag | Description | Default |
---|---|---|
-i
,
--indent
|
Indent JSON output |
false |
topics
Dump topic stats
Usage
$ pulsar-admin broker-stats topics
Options
Flag | Description | Default |
---|---|---|
-i
,
--indent
|
Indent JSON output |
false |
brokers
Operations about brokers
Usage
$ pulsar-admin brokers subcommand
Subcommands
-
list
-
namespaces
-
update-dynamic-config
-
list-dynamic-config
-
get-all-dynamic-config
-
get-internal-config
list
List active brokers of the cluster
Usage
$ pulsar-admin brokers list cluster-name
namespaces
List namespaces owned by the broker
Usage
$ pulsar-admin brokers namespaces cluster-name
Options
Flag | Description | Default |
---|---|---|
--url
|
The URL for the broker |
update-dynamic-config
Update a broker's dynamic service configuration
Usage
$ pulsar-admin brokers update-dynamic-config
Options
Flag | Description | Default |
---|---|---|
--config
|
Service configuration parameter name |
|
--value
|
Value for the configuration parameter value specified using the |
list-dynamic-config
Get list of updatable configuration name
Usage
$ pulsar-admin brokers list-dynamic-config
get-all-dynamic-config
Get all overridden dynamic-configuration values
Usage
$ pulsar-admin brokers get-all-dynamic-config
get-internal-config
Get internal configuration information
Usage
$ pulsar-admin brokers get-internal-config
clusters
Operations about clusters
Usage
$ pulsar-admin clusters subcommand
Subcommands
get
Get the configuration data for the specified cluster
Usage
$ pulsar-admin clusters get cluster-name
create
Provisions a new cluster. This operation requires Pulsar super-user privileges.
Usage
$ pulsar-admin clusters create cluster-name
Options
Flag | Description | Default |
---|---|---|
--broker-url
|
The URL for the broker service. |
|
--broker-url-secure
|
The broker service URL for a secure connection |
|
--url
|
service-url |
|
--url-secure
|
service-url for secure connection |
update
Update the configuration for a cluster
Usage
$ pulsar-admin clusters update cluster-name
Options
Flag | Description | Default |
---|---|---|
--broker-url
|
The URL for the broker service. |
|
--broker-url-secure
|
The broker service URL for a secure connection |
|
--url
|
service-url |
|
--url-secure
|
service-url for secure connection |
delete
Deletes an existing cluster
Usage
$ pulsar-admin clusters delete cluster-name
list
List the existing clusters
Usage
$ pulsar-admin clusters list
update-peer-clusters
Update peer cluster names
Usage
$ pulsar-admin clusters update-peer-clusters peer-cluster-names
functions
A command-line interface for Pulsar Functions
Usage
$ pulsar-admin functions subcommand
Subcommands
localrun
Run a Pulsar Function locally
Usage
$ pulsar-admin functions localrun
Options
Flag | Description | Default |
---|---|---|
--brokerServiceUrl
|
The URL of the Pulsar broker |
|
--className
|
The name of the function’s class |
|
--customSerdeInputs
|
A map of the input topic to SerDe name |
|
--functionConfigFile
|
The path of the YAML config file used to configure the function |
|
--inputs
|
The input topics for the function (as a comma-separated list if more than one topic is desired) |
|
--logTopic
|
The topic to which logs from this function are published |
|
--jar
|
A path to the JAR file for the function (if the function is written in Java) |
|
--name
|
The name of the function |
The value specified by |
--namespace
|
The function’s namespace |
|
--output
|
The name of the topic to which the function publishes its output (if any) |
|
--outputSerdeClassName
|
The SerDe class used for the function’s output |
|
--parallelism
|
The function’s parallelism factor, i.e. the number of instances of the function to run |
1 |
--processingGuarantees
|
The processing guarantees applied to the function. Can be one of: |
ATLEAST_ONCE |
--py
|
The path of the Python file containing the function’s processing logic (if the function is written in Python) |
|
--stateStorageServiceUrl
|
The service URL for the function’s state storage (if the function uses a storage system different from the Apache BookKeeper cluster used by Pulsar) |
|
--subscriptionType
|
The subscription type used by the function when consuming messages on the input topic(s). Can be either |
SHARED |
--tenant
|
The function’s tenant |
|
--userConfig
|
A user-supplied config value, set as a key/value pair. You can set multiple user config values. |
create
Creates a new Pulsar Function on the target infrastructure
Usage
$ pulsar-admin functions create
Options
Flag | Description | Default |
---|---|---|
--className
|
The name of the function’s class |
|
--customSerdeInputs
|
A map of the input topic to SerDe name |
|
--functionConfigFile
|
The path of the YAML config file used to configure the function |
|
--inputs
|
The input topics for the function (as a comma-separated list if more than one topic is desired) |
|
--jar
|
A path to the JAR file for the function (if the function is written in Java) |
|
--name
|
The name of the function |
The value specified by |
--namespace
|
The function’s namespace |
|
--logTopic
|
The topic to which logs from this function are published |
|
--output
|
The name of the topic to which the function publishes its output (if any) |
|
--outputSerdeClassName
|
The SerDe class used for the function’s output |
|
--parallelism
|
The function’s parallelism factor, i.e. the number of instances of the function to run |
1 |
--processingGuarantees
|
The processing guarantees applied to the function. Can be one of: |
ATLEAST_ONCE |
--py
|
The path of the Python file containing the function’s processing logic (if the function is written in Python) |
|
--subscriptionType
|
The subscription type used by the function when consuming messages on the input topic(s). Can be either |
SHARED |
--tenant
|
The function’s tenant |
|
--userConfig
|
A user-supplied config value, set as a key/value pair. You can set multiple user config values. |
delete
Deletes an existing Pulsar Function
Usage
$ pulsar-admin functions delete
Options
Flag | Description | Default |
---|---|---|
--name
|
The name of the function to delete |
|
--namespace
|
The namespace of the function to delete |
|
--tenant
|
The tenant of the function to delete |
update
Updates an existing Pulsar Function
Usage
$ pulsar-admin functions update
Options
Flag | Description | Default |
---|---|---|
--className
|
The name of the function’s class |
|
--customSerdeInputs
|
A map of the input topic to SerDe name |
|
--functionConfigFile
|
The path of the YAML config file used to configure the function |
|
--inputs
|
The input topics for the function (as a comma-separated list if more than one topic is desired) |
|
--jar
|
A path to the JAR file for the function (if the function is written in Java) |
|
--name
|
The name of the function |
The value specified by |
--namespace
|
The function’s namespace |
|
--logTopic
|
The topic to which logs from this function are published |
|
--output
|
The name of the topic to which the function publishes its output (if any) |
|
--outputSerdeClassName
|
The SerDe class used for the function’s output |
|
--parallelism
|
The function’s parallelism factor, i.e. the number of instances of the function to run |
1 |
--processingGuarantees
|
The processing guarantees applied to the function. Can be one of: |
ATLEAST_ONCE |
--py
|
The path of the Python file containing the function’s processing logic (if the function is written in Python) |
|
--subscriptionType
|
The subscription type used by the function when consuming messages on the input topic(s). Can be either |
SHARED |
--tenant
|
The function’s tenant |
|
--userConfig
|
A user-supplied config value, set as a key/value pair. You can set multiple user config values. |
get
Fetch information about an existing Pulsar Function
Usage
$ pulsar-admin functions get
Options
Flag | Description | Default |
---|---|---|
--name
|
The name of the function about which you want to fetch information |
|
--namespace
|
The namespace of the function about which you want to fetch information |
|
--tenant
|
The tenant of the function about which you want to fetch information |
getstatus
Get the status of an existing Pulsar Function
Usage
$ pulsar-admin functions getstatus
Options
Flag | Description | Default |
---|---|---|
--name
|
The name of the function about which you want to fetch status information |
|
--namespace
|
The namespace of the function about which you want to fetch status information |
|
--tenant
|
The tenant of the function about which you want to fetch status information |
list
List all Pulsar Functions for a specific tenant and namespace
Usage
$ pulsar-admin functions list
Options
Flag | Description | Default |
---|---|---|
--namespace
|
The namespace of the functions you want to list |
|
--tenant
|
The tenant of the functions you want to list |
querystate
Retrieve the current state of a Pulsar Function by key
Usage
$ pulsar-admin functions querystate
Options
Flag | Description | Default |
---|---|---|
-k
,
--key
|
The key for the state you want to fetch |
|
--name
|
The name of the function whose state you want to query |
|
--namespace
|
The namespace of the function whose state you want to query |
|
--tenant
|
The tenant of the function whose state you want to query |
|
-u
,
--storage-service-url
|
The service URL for the function’s state storage (if the function uses a storage system different from the Apache BookKeeper cluster used by Pulsar) |
|
-w
,
--watch
|
If set, watching for state changes is enabled |
false |
trigger
Triggers the specified Pulsar Function with a supplied value or file data
Usage
$ pulsar-admin functions trigger
Options
Flag | Description | Default |
---|---|---|
--name
|
The name of the Pulsar Function to trigger |
|
--namespace
|
The namespace of the Pulsar Function to trigger |
|
--tenant
|
The tenant of the Pulsar Function to trigger |
|
--triggerFile
|
The path to the file containing the data with which the Pulsar Function is to be triggered |
|
--triggerValue
|
The value with which the Pulsar Function is to be triggered |
namespaces
Operations for managing namespaces
Usage
$ pulsar-admin namespaces subcommand
Subcommands
-
list
-
list-cluster
-
destinations
-
policies
-
create
-
delete
-
set-deduplication
-
permissions
-
grant-permission
-
revoke-permission
-
set-clusters
-
get-clusters
-
get-backlog-quotas
-
set-backlog-quota
-
remove-backlog-quota
-
get-persistence
-
set-persistence
-
get-message-ttl
-
set-message-ttl
-
get-retention
-
set-retention
-
unload
-
clear-backlog
-
unsubscribe
list
Get the namespaces for a tenant
Usage
$ pulsar-admin namespaces list tenant-name
list-cluster
Get the namespaces for a tenant in the cluster
Usage
$ pulsar-admin namespaces list-cluster tenant/cluster
destinations
Get the destinations for a namespace
Usage
$ pulsar-admin namespaces destinations tenant/cluster/namespace
policies
Get the policies of a namespace
Usage
$ pulsar-admin namespaces policies tenant/cluster/namespace
create
Create a new namespace
Usage
$ pulsar-admin namespaces create tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundles
|
The number of bundles to activate |
0 |
delete
Deletes a namespace
Usage
$ pulsar-admin namespaces delete tenant/cluster/namespace
set-deduplication
Enable or disable message deduplication on a namespace
Usage
$ pulsar-admin namespaces set-deduplication tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
--enable
,
-e
|
Enable message deduplication on the specified namespace |
false |
--disable
,
-d
|
Disable message deduplication on the specified namespace |
false |
permissions
Get the permissions on a namespace
Usage
$ pulsar-admin namespaces permissions tenant/cluster/namespace
grant-permission
Grant permissions on a namespace
Usage
$ pulsar-admin namespaces grant-permission tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
--actions
|
Actions to be granted ( |
|
--role
|
The client role to which to grant the permissions |
revoke-permission
Revoke permissions on a namespace
Usage
$ pulsar-admin namespaces revoke-permission tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
--role
|
The client role from which to revoke the permissions |
set-clusters
Set replication clusters for a namespace
Usage
$ pulsar-admin namespaces set-clusters tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-c
,
--clusters
|
Replication clusters ID list (comma-separated values) |
get-clusters
Get replication clusters for a namespace
Usage
$ pulsar-admin namespaces get-clusters tenant/cluster/namespace
get-backlog-quotas
Get the backlog quota policies for a namespace
Usage
$ pulsar-admin namespaces get-backlog-quotas tenant/cluster/namespace
set-backlog-quota
Set a backlog quota for a namespace
Usage
$ pulsar-admin namespaces set-backlog-quota tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-l
,
--limit
|
The backlog size limit (for example |
|
-p
,
--policy
|
The retention policy to enforce when the limit is reached. The valid options are:
|
Example
$ pulsar-admin namespaces set-backlog-quota my-prop/my-cluster/my-ns \
--limit 2G \
--policy producer_request_hold
remove-backlog-quota
Remove a backlog quota policy from a namespace
Usage
$ pulsar-admin namespaces remove-backlog-quota tenant/cluster/namespace
get-persistence
Get the persistence policies for a namespace
Usage
$ pulsar-admin namespaces get-persistence tenant/cluster/namespace
set-persistence
Set the persistence policies for a namespace
Usage
$ pulsar-admin namespaces set-persistence tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-a
,
--bookkeeper-ack-quorom
|
The number of acks (guaranteed copies) to wait for each entry |
0 |
-e
,
--bookkeeper-ensemble
|
The number of bookies to use for a topic |
0 |
-w
,
--bookkeeper-write-quorum
|
How many writes to make of each entry |
0 |
-r
,
--ml-mark-delete-max-rate
|
Throttling rate of mark-delete operation (0 means no throttle) |
get-message-ttl
Get the message TTL for a namespace
Usage
$ pulsar-admin namespaces get-message-ttl tenant/cluster/namespace
set-message-ttl
Set the message TTL for a namespace
Usage
$ pulsar-admin namespaces set-message-ttl
Options
Flag | Description | Default |
---|---|---|
-ttl
,
--messageTTL
|
Message TTL in seconds |
0 |
get-retention
Get the retention policy for a namespace
Usage
$ pulsar-admin namespaces get-retention tenant/cluster/namespace
set-retention
Set the retention policy for a namespace
Usage
$ pulsar-admin namespaces set-retention tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-s
,
--size
|
The retention size limits (for example |
|
-t
,
--time
|
The retention time in minutes, hours, days, or weeks. Examples: |
unload
Unload a namespace or namespace bundle from the current serving broker.
Usage
$ pulsar-admin namespaces unload tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundle
|
clear-backlog
Clear the backlog for a namespace
Usage
$ pulsar-admin namespaces clear-backlog tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundle
|
||
-f
,
--force
|
Whether to force a clear backlog without prompt |
false |
-s
,
--sub
|
The subscription name |
unsubscribe
Unsubscribe the given subscription on all destinations on a namespace
Usage
$ pulsar-admin namespaces unsubscribe tenant/cluster/namespace
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundle
|
||
-s
,
--sub
|
The subscription name |
ns-isolation-policy
Operations for managing namespace isolation policies.
Usage
$ pulsar-admin ns-isolation-policy subcommand
Subcommands
set
Create/update a namespace isolation policy for a cluster. This operation requires Pulsar superuser privileges.
Usage
$ pulsar-admin ns-isolation-policy set cluster-name policy-name
Options
Flag | Description | Default |
---|---|---|
--auto-failover-policy-params
|
Comma-separated |
[] |
--auto-failover-policy-type
|
Auto failover policy type name. Currently available options: |
[] |
--namespaces
|
Comma-separated namespaces regex list |
[] |
--primary
|
Comma-separated primary broker regex list |
[] |
--secondary
|
Comma-separated secondary broker regex list |
[] |
get
Get the namespace isolation policy of a cluster. This operation requires Pulsar superuser privileges.
Usage
$ pulsar-admin ns-isolation-policy get cluster-name policy-name
list
List all namespace isolation policies of a cluster. This operation requires Pulsar superuser privileges.
Usage
$ pulsar-admin ns-isolation-policy list cluster-name
delete
Delete namespace isolation policy of a cluster. This operation requires superuser privileges.
Usage
$ pulsar-admin ns-isolation-policy delete
topics
Operations for managing Pulsar topics (both persistent and non persistent)
Usage
$ pulsar-admin topics subcommand
Subcommands
-
compact
-
compaction-status
-
create-partitioned-topic
-
delete-partitioned-topic
-
get-partitioned-topic-metadata
-
list
-
list-in-bundle
-
terminate
-
permissions
-
grant-permission
-
revoke-permission
-
lookup
-
bundle-range
-
delete
-
unload
-
subscriptions
-
unsubscribe
-
stats
-
stats-internal
-
info-internal
-
partitioned-stats
-
skip
-
skip-all
-
expire-messages
-
expire-messages-all-subscriptions
-
peek-messages
-
reset-cursor
compact
Run compaction on the specified topic (persistent topics only)
Usage
$ pulsar-admin topics compact persistent://tenant/namespace/topic
compaction-status
Check the status of a topic compaction (persistent topics only)
Usage
$ pulsar-admin topics compaction-status persistent://tenant/namespace/topic
Options
Flag | Description | Default |
---|---|---|
-w
,
--wait-complete
|
Wait for compaction to complete |
false |
create-partitioned-topic
Create a partitioned topic. A partitioned topic must be created before producers can publish to it.
Usage
$ pulsar-admin topics create-partitioned-topic {persistent|non-persistent}://tenant/namespace/topic
Options
Flag | Description | Default |
---|---|---|
-p
,
--partitions
|
The number of partitions for the topic |
0 |
delete-partitioned-topic
Delete a partitioned topic. This will also delete all the partitions of the topic if they exist.
Usage
$ pulsar-admin topics delete-partitioned-topic {persistent|non-persistent}://tenant/namespace/topic
get-partitioned-topic-metadata
Get the partitioned topic metadata. If the topic is not created or is a non-partitioned topic, this will return an empty topic with zero partitions.
Usage
$ pulsar-admin topics get-partitioned-topic-metadata {persistent|non-persistent}://tenant/namespace/topic
list
Get the list of topics under a namespace
Usage
$ pulsar-admin topics list tenant/cluster/namespace
list-in-bundle
Get a list of non-persistent topics present under a namespace bundle
Usage
$ pulsar-admin topics list-in-bundle tenant/namespace
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundle
|
The bundle range |
terminate
Terminate a topic (disallow further messages from being published on the topic)
Usage
$ pulsar-admin topics terminate {persistent|non-persistent}://tenant/namespace/topic
permissions
Get the permissions on a topic. Retrieve the effective permissions for a desination. These permissions are defined by the permissions set at the namespace level combined (union) with any eventual specific permissions set on the topic.
Usage
$ pulsar-admin topics permissions topic
grant-permission
Grant a new permission to a client role on a single topic
Usage
$ pulsar-admin topics grant-permission {persistent|non-persistent}://tenant/namespace/topic
Options
Flag | Description | Default |
---|---|---|
--actions
|
Actions to be granted ( |
|
--role
|
The client role to which permissions are to be granted |
revoke-permission
Revoke permissions to a client role on a single topic. If the permission was not set at the topic level, but rather at the namespace level, this operation will return an error (HTTP status code 412).
Usage
$ pulsar-admin topics revoke-permission topic
lookup
Look up a topic from the current serving broker
Usage
$ pulsar-admin topics lookup topic
bundle-range
Get the namespace bundle which contains the given topic
Usage
$ pulsar-admin topics bundle-range topic
delete
Delete a topic. The topic cannot be deleted if there are any active subscriptions or producers connected to the topic.
Usage
$ pulsar-admin topics delete topic
unload
Unload a topic
Usage
$ pulsar-admin topics unload topic
subscriptions
Get the list of subscriptions on the topic
Usage
$ pulsar-admin topics subscriptions topic
unsubscribe
Delete a durable subscriber from a topic
Usage
$ pulsar-admin topics unsubscribe topic
Options
Flag | Description | Default |
---|---|---|
-s
,
--subscription
|
The subscription to delete |
stats
Get the stats for the topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.
Usage
$ pulsar-admin topics stats topic
stats-internal
Get the internal stats for the topic
Usage
$ pulsar-admin topics stats-internal topic
info-internal
Get the internal metadata info for the topic
Usage
$ pulsar-admin topics info-internal topic
partitioned-stats
Get the stats for the partitioned topic and its connected producers and consumers. All rates are computed over a 1-minute window and are relative to the last completed 1-minute period.
Usage
$ pulsar-admin topics partitioned-stats topic
Options
Flag | Description | Default |
---|---|---|
--per-partition
|
Get per-partition stats |
false |
skip
Skip some messages for the subscription
Usage
$ pulsar-admin topics skip topic
Options
Flag | Description | Default |
---|---|---|
-n
,
--count
|
The number of messages to skip |
0 |
-s
,
--subscription
|
The subscription on which to skip messages |
skip-all
Skip all the messages for the subscription
Usage
$ pulsar-admin topics skip-all topic
Options
Flag | Description | Default |
---|---|---|
-s
,
--subscription
|
The subscription to clear |
expire-messages
Expire messages that are older than the given expiry time (in seconds) for the subscription.
Usage
$ pulsar-admin topics expire-messages topic
Options
Flag | Description | Default |
---|---|---|
-t
,
--expireTime
|
Expire messages older than the time (in seconds) |
0 |
-s
,
--subscription
|
The subscription to skip messages on |
expire-messages-all-subscriptions
Expire messages older than the given expiry time (in seconds) for all subscriptions
Usage
$ pulsar-admin topics expire-messages-all-subscriptions topic
Options
Flag | Description | Default |
---|---|---|
-t
,
--expireTime
|
Expire messages older than the time (in seconds) |
0 |
peek-messages
Peek some messages for the subscription.
Usage
$ pulsar-admin topics peek-messages topic
Options
Flag | Description | Default |
---|---|---|
-n
,
--count
|
The number of messages |
1 |
-s
,
--subscription
|
Subscription to get messages from |
reset-cursor
Reset position for subscription to closest to timestamp
Usage
$ pulsar-admin topics reset-cursor topic
Options
Flag | Description | Default |
---|---|---|
-s
,
--subscription
|
Subscription to reset position on |
|
-t
,
--time
|
The time, in minutes, to reset back to (or minutes, hours, days, weeks, etc.). Examples: |
tenants
Operations for managing tenants
Usage
$ pulsar-admin tenants subcommand
Subcommands
list
List the existing tenants
Usage
$ pulsar-admin tenants list
get
Gets the configuration of a tenant
Usage
$ pulsar-admin tenants get tenant-name
create
Creates a new tenant
Usage
$ pulsar-admin tenants create tenant-name
Options
Flag | Description | Default |
---|---|---|
-r
,
--admin-roles
|
Comma-separated admin roles |
|
-c
,
--allowed-clusters
|
Comma-separated allowed clusters |
update
Updates a tenant
Usage
$ pulsar-admin tenants update tenant-name
Options
Flag | Description | Default |
---|---|---|
-r
,
--admin-roles
|
Comma-separated admin roles |
|
-c
,
--allowed-clusters
|
Comma-separated allowed clusters |
delete
Deletes an existing tenant
Usage
$ pulsar-admin tenants delete tenant-name
resource-quotas
Operations for managing resource quotas
Usage
$ pulsar-admin resource-quotas subcommand
Subcommands
get
Get the resource quota for a specified namespace bundle, or default quota if no namespace/bundle is specified.
Usage
$ pulsar-admin resource-quotas get
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundle
|
A bundle of the form |
|
-n
,
--namespace
|
The namespace |
set
Set the resource quota for the specified namespace bundle, or default quota if no namespace/bundle is specified.
Usage
$ pulsar-admin resource-quotas set
Options
Flag | Description | Default |
---|---|---|
-bi
,
--bandwidthIn
|
The expected inbound bandwidth (in bytes/second) |
0 |
-bo
,
--bandwidthOut
|
Expected outbound bandwidth (in bytes/second) |
0 |
-b
,
--bundle
|
A bundle of the form |
|
-d
,
--dynamic
|
Allow to be dynamically re-calculated (or not) |
false |
-mem
,
--memory
|
Expectred memory usage (in megabytes) |
0 |
-mi
,
--msgRateIn
|
Expected incoming messages per second |
0 |
-mo
,
--msgRateOut
|
Expected outgoing messages per second |
0 |
-n
,
--namespace
|
The namespace as |
reset-namespace-bundle-quota
Reset the specifed namespace bundle's resource quota to a default value.
Usage
$ pulsar-admin resource-quotas reset-namespace-bundle-quota
Options
Flag | Description | Default |
---|---|---|
-b
,
--bundle
|
A bundle of the form |
|
-n
,
--namespace
|
The namespace as |
pulsar-client
The pulsar-client
tool
Usage
$ pulsar-client command
Commands
Options
Flag | Description | Default |
---|---|---|
--auth-params
|
Authentication parameters, for example |
|
--auth-plugin
|
Authentication plugin class name |
|
--url
|
Broker URL to which to connect |
pulsar://localhost:6650/ |
produce
Send a message or messages to a specific broker and topic
Usage
$ pulsar-client produce topic
Options
Flag | Description | Default |
---|---|---|
-f
,
--files
|
Comma-separated file paths to send; either |
[] |
-m
,
--messages
|
Comma-separated string of messages to send; either |
[] |
-n
,
--num-produce
|
The number of times to send the message(s); the count of |
1 |
-r
,
--rate
|
Rate (in messages per second) at which to produce; a value 0 means to produce messages as fast as possible |
0.0 |
consume
Consume messages from a specific broker and topic
Usage
$ pulsar-client consume topic
Options
Flag | Description | Default |
---|---|---|
--hex
|
Display binary messages in hexadecimal format. |
false |
-n
,
--num-messages
|
Number of messages to consume, 0 means to consume forever. |
0 |
-r
,
--rate
|
Rate (in messages per second) at which to produce; a value 0 means to produce messages as fast as possible |
0.0 |
-s
,
--subscription-name
|
Subscription name |
|
-t
,
--subscription-type
|
The type of the subscription. Possible values: |
exclusive |
pulsar-daemon
A wrapper around the pulsar
tool that’s used to start and stop processes, such as ZooKeeper, bookies, and Pulsar brokers, in the background using nohup.
pulsar-daemon
has a similar interface to the pulsar
command but adds start
and stop
commands for various services. For a listing of those services, run pulsar-daemon
to see the help output or see the documentation for the pulsar
command.
Usage
$ pulsar-daemon command
Commands
start
Start a service in the background using nohup.
Usage
$ pulsar-daemon start service
stop
Stop a service that’s already been started using start
.
Usage
$ pulsar-daemon stop service
Options
Flag | Description | Default |
---|---|---|
-force
|
Stop the service forcefully if not stopped by normal shutdown. |
false |
pulsar-perf
A tool for performance testing a Pulsar broker.
Usage
$ pulsar-perf command
Commands
Environment variables
The table below lists the environment variables that you can use to configure the pulsar-perf
tool.
Variable | Description | Default |
---|---|---|
PULSAR_LOG_CONF |
Log4j configuration file | conf/log4j2.yaml |
PULSAR_CLIENT_CONF |
Configuration file for the client | conf/client.conf |
PULSAR_EXTRA_OPTS |
Extra options to be passed to the JVM | |
PULSAR_EXTRA_CLASSPATH |
Extra paths for Pulsar's classpath |
consume
Run a consumer
Usage
$ pulsar-perf consume
Options
Flag | Description | Default |
---|---|---|
--auth_params
|
Authentication parameters in the form of |
|
--auth_plugin
|
Authentication plugin class name |
|
-b
,
--batch-time-window
|
Batch messages in a window of the specified number of milliseconds |
1 |
-z
,
--compression
|
Compress messages’ payload. Possible values are |
|
--conf-file
|
Configuration file |
|
-c
,
--max-connections
|
Max number of TCP connections to a single broker |
0 |
-o
,
--max-outstanding
|
Max number of outstanding messages |
1000 |
-m
,
--num-messages
|
Number of messages to publish in total. If set to 0, it will keep publishing. |
0 |
-n
,
--num-producers
|
The number of producers (per topic) |
1 |
-t
,
--num-topic
|
The number of topics |
1 |
-f
,
--payload-file
|
Use payload from a file instead of an empty buffer |
|
-r
,
--rate
|
Publish rate msg/s across topics |
100 |
-u
,
--service-url
|
Pulsar service URL |
|
-s
,
--size
|
Message size (in bytes) |
1024 |
-i
,
--stats-interval-seconds
|
Statistics interval seconds. If 0, statistics will be disabled. |
0 |
-time
,
--test-duration
|
Test duration in secs. If set to 0, it will keep publishing. |
0 |
produce
Run a producer
Usage
$ pulsar-perf produce
Options
Flag | Description | Default |
---|---|---|
--auth_params
|
Authentication parameters in the form of |
|
--auth_plugin
|
Authentication plugin class name |
|
-b
,
--batch-time-window
|
Batch messages in a window of the specified number of milliseconds |
1 |
-z
,
--compression
|
Compress messages’ payload. Possible values are |
|
["--conf-file"]
|
Configuration file |
|
-c
,
--max-connections
|
Max number of TCP connections to a single broker |
0 |
-o
,
--max-outstanding
|
Max number of outstanding messages |
1000 |
-m
,
--num-messages
|
Number of messages to publish in total. If set to 0, it will keep publishing. |
0 |
-n
,
--num-producers
|
The number of producers (per topic) |
1 |
-t
,
--num-topic
|
The number of topics |
1 |
-f
,
--payload-file
|
Use payload from a file instead of an empty buffer |
|
-r
,
--rate
|
Publish rate msg/s across topics |
100 |
-u
,
--service-url
|
Pulsar service URL |
|
-s
,
--size
|
Message size (in bytes) |
1024 |
-i
,
--stats-interval-seconds
|
Statistics interval seconds. If 0, statistics will be disabled. |
0 |
-time
,
--test-duration
|
Test duration in secs. If set to 0, it will keep publishing. |
0 |
monitor-brokers
Continuously receive broker data and/or load reports
Usage
$ pulsar-perf monitor-brokers
Options
Flag | Description | Default |
---|---|---|
--connect-string
|
A connection string for one or more ZooKeeper servers |
simulation-client
Run a simulation server acting as a Pulsar client. Uses the client configuration specified in conf/client.conf
.
Usage
$ pulsar-perf simulation-client
simulation-controller
Run a simulation controller to give commands to servers
Usage
$ pulsar-perf simulation-controller
Options
Flag | Description | Default |
---|---|---|
--client-port
|
The port that the clients are listening on |
0 |
--clients
|
Comma-separated list of client hostnames |
|
--cluster
|
The cluster to test on |
bookkeeper
A tool for managing BookKeeper.
Usage
$ bookkeeper command
Commands
Environment variables
The table below lists the environment variables that you can use to configure the bookkeeper
tool.
Variable | Description | Default |
---|---|---|
BOOKIE_LOG_CONF |
Log4j configuration file | conf/log4j2.yaml |
BOOKIE_CONF |
BookKeeper configuration file | conf/bk_server.conf |
BOOKIE_EXTRA_OPTS |
Extra options to be passed to the JVM | |
BOOKIE_EXTRA_CLASSPATH |
Extra paths for BookKeeper's classpath | |
ENTRY_FORMATTER_CLASS |
The Java class used to format entries | |
BOOKIE_PID_DIR |
Folder where the BookKeeper server PID file should be stored | |
BOOKIE_STOP_TIMEOUT |
Wait time before forcefully killing the Bookie server instance if attempts to stop it are not successful |
auto-recovery
Runs an auto-recovery service daemon
Usage
$ bookkeeper auto-recovery
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration for the auto-recovery daemon |
bookie
Starts up a BookKeeper server (aka bookie)
Usage
$ bookkeeper bookie
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration for the bookie server |
|
-readOnly
|
Force start a read-only bookie server |
false |
-withAutoRecovery
|
Start auto-recovery service bookie server |
false |
localbookie
Runs a test ensemble of N bookies locally
Usage
$ bookkeeper localbookie N
upgrade
Upgrade the bookie’s filesystem
Usage
$ bookkeeper upgrade
Options
Flag | Description | Default |
---|---|---|
-c
,
--conf
|
Configuration for the bookie server |
|
-c
,
--conf
|
Finalize the upgrade |
|
-c
,
--conf
|
Roll the upgrade back |
|
-u
,
--upgrade
|
Upgrade the bookie’s directories |
shell
Run shell for admin commands. To see a full listing of those commands, run bookkeeper shell
without an argument.
Usage
$ bookkeeper shell
Example
$ $ bookkeeper shell bookiesanity