You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by GitBox <gi...@apache.org> on 2020/10/26 11:42:39 UTC
[GitHub] [pulsar] Jennifer88huang opened a new pull request #8375: [WIP][docs] Re-org topics in Admin API section
Jennifer88huang opened a new pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375
### Motivation
The sub-commands for persistent is changed into "topics". And persistent topics can be partitioned and non-partitioned topics.
### Modifications
1. Refactor the topic structure, will keep only one md file for the topic in the "Admin API" section.
2. Refine the commands used in the topic section from "persistent" into "topics" for both `pulsar-admin` and `REST API`.
3. Adopt switch tab for `pulsar-admin`, `REST API` and Java methods.
4. Will add partitioned and non-partitioned sections in this md file as well.
5. Check links to the 3 deleted files throughout.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] zymap commented on a change in pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
zymap commented on a change in pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#discussion_r514256993
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -1,80 +1,78 @@
---
id: admin-api-persistent-topics
-title: Managing persistent topics
-sidebar_label: Persistent topics
+title: Manage topics
+sidebar_label: Topics
---
-Persistent helps to access topic which is a logical endpoint for publishing and consuming messages. Producers publish messages to the topic and consumers subscribe to the topic, to consume messages published to the topic.
-
-In all of the instructions and commands below, the topic name structure is:
-
+Pulsar has persistent and non-persistent topics. Persistent topic is a logical endpoint for publishing and consuming messages. The topic name structure for persistent topics is:
```shell
persistent://tenant/namespace/topic
```
-## Persistent topics resources
+Non-persistent topics are used in applications that only consume real-time published messages and do not need persistent guarantee. In this way, it reduces message-publish latency by removing overhead of persisting messages. The topic name structure for non-persistent topics is:
-### List of topics
+```shell
+non-persistent://tenant/namespace/topic
+```
+## Manage topic resources
+Whether it is persistent or non-persistent topic, you can obtain the topic resources through `pulsar-admin` tool, REST API and Java.
-It provides a list of persistent topics exist under a given namespace.
+### List of topics
-#### pulsar-admin
+You can get the list of topics under a given namespace in the following ways.
-List of topics can be fetched using [`list`](../../reference/CliTools#list) command.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent list \
+$ pulsar-admin topics list \
my-tenant/my-namespace
```
-#### REST API
-
-{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace|operation/getList}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/topics/:tenant/:namespace|operation/getList}
Review comment:
I don't think we have the `topics` endpoint to get all the topics. Actually, there have two steps on the client-side, the client will get the persistent topics and non-persistent topics then combine the result at the client-side.
I am not sure how to add two REST API endpoints. @tuteng Any ideas?
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -1,80 +1,78 @@
---
id: admin-api-persistent-topics
-title: Managing persistent topics
-sidebar_label: Persistent topics
+title: Manage topics
+sidebar_label: Topics
---
-Persistent helps to access topic which is a logical endpoint for publishing and consuming messages. Producers publish messages to the topic and consumers subscribe to the topic, to consume messages published to the topic.
-
-In all of the instructions and commands below, the topic name structure is:
-
+Pulsar has persistent and non-persistent topics. Persistent topic is a logical endpoint for publishing and consuming messages. The topic name structure for persistent topics is:
```shell
persistent://tenant/namespace/topic
```
-## Persistent topics resources
+Non-persistent topics are used in applications that only consume real-time published messages and do not need persistent guarantee. In this way, it reduces message-publish latency by removing overhead of persisting messages. The topic name structure for non-persistent topics is:
-### List of topics
+```shell
+non-persistent://tenant/namespace/topic
+```
+## Manage topic resources
+Whether it is persistent or non-persistent topic, you can obtain the topic resources through `pulsar-admin` tool, REST API and Java.
-It provides a list of persistent topics exist under a given namespace.
+### List of topics
-#### pulsar-admin
+You can get the list of topics under a given namespace in the following ways.
-List of topics can be fetched using [`list`](../../reference/CliTools#list) command.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent list \
+$ pulsar-admin topics list \
my-tenant/my-namespace
```
-#### REST API
-
-{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace|operation/getList}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/topics/:tenant/:namespace|operation/getList}
+<!--Java-->
```java
String namespace = "my-tenant/my-namespace";
-admin.persistentTopics().getList(namespace);
+admin.topics().getList(namespace);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
### Grant permission
-It grants permissions on a client role to perform specific actions on a given topic.
-
-#### pulsar-admin
-
-Permission can be granted using [`grant-permission`](../../reference/CliTools#grant-permission) command.
+You can grant permissions on a client role to perform specific actions on a given topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent grant-permission \
+$ pulsar-admin topics grant-permission \
--actions produce,consume --role application1 \
persistent://test-tenant/ns1/tp1 \
-
```
-#### REST API
-
-{@inject: endpoint|POST|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/grantPermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|POST|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/grantPermissionsOnTopic}
Review comment:
similar issue with the previous comments. We don't have the `topics` endpoint. All the following REST API endpoint has the same issue.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang merged pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Jennifer88huang merged pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on pull request #8375: [WIP][docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#issuecomment-716495577
The whole PR will be a huge PR, I can add "partitioned" and "non-partitioned topics" later in another PR.
Please double check the REST API in the "Last Message Id" section.
The original one is "{% endpoint Get /admin/v2/topics/:tenant/:namespace/:topic/lastMessageId %}".
I've changed it into "{@inject: endpoint|Get|/admin/v2/topics/:tenant/:namespace/:topic/lastMessageId}".
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] tuteng commented on a change in pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
tuteng commented on a change in pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#discussion_r517241333
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -1,80 +1,78 @@
---
id: admin-api-persistent-topics
-title: Managing persistent topics
-sidebar_label: Persistent topics
+title: Manage topics
+sidebar_label: Topics
---
-Persistent helps to access topic which is a logical endpoint for publishing and consuming messages. Producers publish messages to the topic and consumers subscribe to the topic, to consume messages published to the topic.
-
-In all of the instructions and commands below, the topic name structure is:
-
+Pulsar has persistent and non-persistent topics. Persistent topic is a logical endpoint for publishing and consuming messages. The topic name structure for persistent topics is:
```shell
persistent://tenant/namespace/topic
```
-## Persistent topics resources
+Non-persistent topics are used in applications that only consume real-time published messages and do not need persistent guarantee. In this way, it reduces message-publish latency by removing overhead of persisting messages. The topic name structure for non-persistent topics is:
-### List of topics
+```shell
+non-persistent://tenant/namespace/topic
+```
+## Manage topic resources
+Whether it is persistent or non-persistent topic, you can obtain the topic resources through `pulsar-admin` tool, REST API and Java.
-It provides a list of persistent topics exist under a given namespace.
+### List of topics
-#### pulsar-admin
+You can get the list of topics under a given namespace in the following ways.
-List of topics can be fetched using [`list`](../../reference/CliTools#list) command.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent list \
+$ pulsar-admin topics list \
my-tenant/my-namespace
```
-#### REST API
-
-{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace|operation/getList}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/topics/:tenant/:namespace|operation/getList}
Review comment:
Please refer to `NON-PERSISTENT TOPIC` http://pulsar.apache.org/admin-rest-api/?version=2.6.1&apiversion=v2#operation/getList and `PERSISTENT TOPIC` http://pulsar.apache.org/admin-rest-api/?version=2.6.1&apiversion=v2#operation/getList
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Huanli-Meng commented on a change in pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Huanli-Meng commented on a change in pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#discussion_r513365145
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -117,137 +112,132 @@ $ pulsar-admin persistent revoke-permission \
}
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
String role = "test-role";
-admin.persistentTopics().revokePermissions(topic, role);
+admin.topics().revokePermissions(topic, role);
```
-### Delete topic
-
-It deletes a topic. The topic cannot be deleted if there's any active subscription or producers connected to it.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
+### Delete topic
-Topic can be deleted using [`delete`](../../reference/CliTools#delete) command.
+You can delete a topic in the following ways. You cannot delete a topic if any active subscription or producers is connected to the topic.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent delete \
+$ pulsar-admin topics delete \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic|operation/deleteTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().delete(topic);
+admin.topics().delete(topic);
```
-### Unload topic
-
-It unloads a topic.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
-
-Topic can be unloaded using [`unload`](../../reference/CliTools#unload) command.
+### Unload topic
+You can unload a topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent unload \
+$ pulsar-admin topics unload \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|PUT|/admin/v2/topics/:tenant/:namespace/:topic/unload|operation/unloadTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().unload(topic);
+admin.topics().unload(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get stats
-It shows current statistics of a given non-partitioned topic.
+You can view the following statistics of a given non-partitioned topic.
Review comment:
```suggestion
You can check the following statistics of a given non-partitioned topic.
```
check through the whole updates
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -117,137 +112,132 @@ $ pulsar-admin persistent revoke-permission \
}
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
String role = "test-role";
-admin.persistentTopics().revokePermissions(topic, role);
+admin.topics().revokePermissions(topic, role);
```
-### Delete topic
-
-It deletes a topic. The topic cannot be deleted if there's any active subscription or producers connected to it.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
+### Delete topic
-Topic can be deleted using [`delete`](../../reference/CliTools#delete) command.
+You can delete a topic in the following ways. You cannot delete a topic if any active subscription or producers is connected to the topic.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent delete \
+$ pulsar-admin topics delete \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic|operation/deleteTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().delete(topic);
+admin.topics().delete(topic);
```
-### Unload topic
-
-It unloads a topic.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
-
-Topic can be unloaded using [`unload`](../../reference/CliTools#unload) command.
+### Unload topic
+You can unload a topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent unload \
+$ pulsar-admin topics unload \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|PUT|/admin/v2/topics/:tenant/:namespace/:topic/unload|operation/unloadTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().unload(topic);
+admin.topics().unload(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get stats
-It shows current statistics of a given non-partitioned topic.
+You can view the following statistics of a given non-partitioned topic.
- - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second
+ - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second.
- - **msgThroughputIn**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputIn**: The sum of all local and replication publishers' publish rates in bytes per second.
- - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second
+ - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second.
- - **msgThroughputOut**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputOut**: The sum of all local and replication consumers' dispatch rates in bytes per second.
- - **averageMsgSize**: The average size in bytes of messages published within the last interval
+ - **averageMsgSize**: The average size(in bytes) of messages published within the last interval.
- - **storageSize**: The sum of the ledgers' storage size for this topic. Space used to store the messages for the topic
+ - **storageSize**: The sum of the ledgers' storage size for this topic. The space used to store the messages for the topic.
- - **publishers**: The list of all local publishers into the topic. There can be zero or thousands
+ - **publishers**: The list of all local publishers into the topic. The list ranges from zero to thousands.
- - **msgRateIn**: Total rate of messages published by this publisher in messages per second
+ - **msgRateIn**: The total rate of messages published by this publisher in messages per second.
- - **msgThroughputIn**: Total throughput of the messages published by this publisher in bytes per second
+ - **msgThroughputIn**: The total throughput of the messages published by this publisher in bytes per second.
- - **averageMsgSize**: Average message size in bytes from this publisher within the last interval
+ - **averageMsgSize**: The average message size in bytes from this publisher within the last interval.
- - **producerId**: Internal identifier for this producer on this topic
+ - **producerId**: The internal identifier for this producer on this topic.
- - **producerName**: Internal identifier for this producer, generated by the client library
+ - **producerName**: The internal identifier for this producer, generated by the client library.
- - **address**: IP address and source port for the connection of this producer
+ - **address**: The IP address and source port for the connection of this producer.
- - **connectedSince**: Timestamp this producer was created or last reconnected
+ - **connectedSince**: The timestamp when this producer is created or reconnected last time.
- - **subscriptions**: The list of all local subscriptions to the topic
+ - **subscriptions**: The list of all local subscriptions to the topic.
- - **my-subscription**: The name of this subscription (client defined)
+ - **my-subscription**: The name of this subscription. It is defined by the client.
- - **msgRateOut**: Total rate of messages delivered on this subscription (msg/s)
+ - **msgRateOut**: The total rate of messages delivered on this subscription (msg/s).
- - **msgThroughputOut**: Total throughput delivered on this subscription (bytes/s)
+ - **msgThroughputOut**: The total throughput delivered on this subscription (bytes/s).
- - **msgBacklog**: Number of messages in the subscription backlog
+ - **msgBacklog**: The number of messages in the subscription backlog.
- - **type**: This subscription type
+ - **type**: The subscription type.
- - **msgRateExpired**: The rate at which messages were discarded instead of dispatched from this subscription due to TTL
+ - **msgRateExpired**: The rate at which messages were discarded instead of dispatched from this subscription due to TTL.
- - **lastExpireTimestamp**: The last message expire execution timestamp
+ - **lastExpireTimestamp**: The timestamp of the last message expire execution.
- - **lastConsumedFlowTimestamp**: The last flow command received timestamp
+ - **lastConsumedFlowTimestamp**: The timestamp of the last flow command received.
- - **lastConsumedTimestamp**: The latest timestamp of all the consumed timestamp of the consumers
+ - **lastConsumedTimestamp**: The latest timestamp of all the consumed timestamp of the consumers.
- - **lastAckedTimestamp**: The latest timestamp of all the acked timestamp of the consumers
+ - **lastAckedTimestamp**: The latest timestamp of all the acked timestamp of the consumers.
- - **consumers**: The list of connected consumers for this subscription
+ - **consumers**: The list of connected consumers for this subscription.
- - **msgRateOut**: Total rate of messages delivered to the consumer (msg/s)
+ - **msgRateOut**: The total rate of messages delivered to the consumer (msg/s).
- - **msgThroughputOut**: Total throughput delivered to the consumer (bytes/s)
+ - **msgThroughputOut**: The total throughput delivered to the consumer (bytes/s).
- - **consumerName**: Internal identifier for this consumer, generated by the client library
+ - **consumerName**: The internal identifier for this consumer, generated by the client library.
- - **availablePermits**: The number of messages this consumer has space for in the client library's listen queue. A value of 0 means the client library's queue is full and receive() isn't being called. A nonzero value means this consumer is ready to be dispatched messages.
+ - **availablePermits**: The number of messages this consumer has space for in the client library's listen queue. `0` means the client library's queue is full and `receive()` isn't being called. A nonzero value means this consumer is ready to be dispatched messages.
Review comment:
```suggestion
- **availablePermits**: The number of messages that the consumer has space for in the client library's listen queue. `0` means the client library's queue is full and `receive()` isn't being called. A non-zero value means this consumer is ready for dispatched messages.
```
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -307,94 +299,95 @@ It shows current statistics of a given non-partitioned topic.
"replication": {}
}
```
+To get the status of a topic, you can use the following ways.
-#### pulsar-admin
-
-Topic stats can be fetched using [`stats`](../../reference/CliTools#stats) command.
-
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent stats \
+$ pulsar-admin topics stats \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/stats|operation/getStats}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/topics/:tenant/:namespace/:topic/stats|operation/getStats}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().getStats(topic);
+admin.topics().getStats(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get internal stats
-It shows detailed statistics of a topic.
+You can get the detailed statistics of a topic.
- - **entriesAddedCounter**: Messages published since this broker loaded this topic
+ - **entriesAddedCounter**: Messages published since this broker loaded this topic.
- - **numberOfEntries**: Total number of messages being tracked
+ - **numberOfEntries**: The total number of messages being tracked.
- - **totalSize**: Total storage size in bytes of all messages
+ - **totalSize**: The total storage size in bytes of all messages.
- - **currentLedgerEntries**: Count of messages written to the ledger currently open for writing
+ - **currentLedgerEntries**: The count of messages written to the ledger that is currently open for writing.
- - **currentLedgerSize**: Size in bytes of messages written to ledger currently open for writing
+ - **currentLedgerSize**: The size in bytes of messages written to the ledger that is currently open for writing.
- - **lastLedgerCreatedTimestamp**: time when last ledger was created
+ - **lastLedgerCreatedTimestamp**: The time when the last ledger is created.
- - **lastLedgerCreationFailureTimestamp:** time when last ledger was failed
+ - **lastLedgerCreationFailureTimestamp:** The time when the last ledger failed.
- - **waitingCursorsCount**: How many cursors are "caught up" and waiting for a new message to be published
+ - **waitingCursorsCount**: How many cursors are "caught up" and waiting for a new message to be published.
- - **pendingAddEntriesCount**: How many messages have (asynchronous) write requests we are waiting on completion
+ - **pendingAddEntriesCount**: The number of messages that complete (asynchronous) write requests.
- - **lastConfirmedEntry**: The ledgerid:entryid of the last message successfully written. If the entryid is -1, then the ledger has been opened or is currently being opened but has no entries written yet.
+ - **lastConfirmedEntry**: The ledgerid:entryid of the last message that is written successfully. If the entryid is `-1`, then the ledger is open, yet no entries are written.
- - **state**: The state of this ledger for writing. LedgerOpened means we have a ledger open for saving published messages.
+ - **state**: The state of this ledger for writing. The state `LedgerOpened` means that a ledger is open for saving published messages.
- - **ledgers**: The ordered list of all ledgers for this topic holding its messages
+ - **ledgers**: The ordered list of all ledgers for this topic holding messages.
- - **ledgerId**: Id of this ledger
+ - **ledgerId**: Id of this ledger.
- - **entries**: Total number of entries belong to this ledger
+ - **entries**: The total number of entries belong to this ledger.
- - **size**: Size of messages written to this ledger (in bytes)
+ - **size**: The size of messages written to this ledger (in bytes).
- - **offloaded**: Whether this ledger is offloaded
+ - **offloaded**: Whether this ledger is offloaded.
- **compactedLedger**: The ledgers holding un-acked messages after topic compaction.
- - **ledgerId**: Id of this ledger
+ - **ledgerId**: The Id of this ledger.
Review comment:
```suggestion
- **ledgerId**: The ID of this ledger.
```
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -117,137 +112,132 @@ $ pulsar-admin persistent revoke-permission \
}
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
String role = "test-role";
-admin.persistentTopics().revokePermissions(topic, role);
+admin.topics().revokePermissions(topic, role);
```
-### Delete topic
-
-It deletes a topic. The topic cannot be deleted if there's any active subscription or producers connected to it.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
+### Delete topic
-Topic can be deleted using [`delete`](../../reference/CliTools#delete) command.
+You can delete a topic in the following ways. You cannot delete a topic if any active subscription or producers is connected to the topic.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent delete \
+$ pulsar-admin topics delete \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic|operation/deleteTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().delete(topic);
+admin.topics().delete(topic);
```
-### Unload topic
-
-It unloads a topic.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
-
-Topic can be unloaded using [`unload`](../../reference/CliTools#unload) command.
+### Unload topic
+You can unload a topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent unload \
+$ pulsar-admin topics unload \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|PUT|/admin/v2/topics/:tenant/:namespace/:topic/unload|operation/unloadTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().unload(topic);
+admin.topics().unload(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get stats
-It shows current statistics of a given non-partitioned topic.
+You can view the following statistics of a given non-partitioned topic.
- - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second
+ - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second.
- - **msgThroughputIn**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputIn**: The sum of all local and replication publishers' publish rates in bytes per second.
- - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second
+ - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second.
- - **msgThroughputOut**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputOut**: The sum of all local and replication consumers' dispatch rates in bytes per second.
- - **averageMsgSize**: The average size in bytes of messages published within the last interval
+ - **averageMsgSize**: The average size(in bytes) of messages published within the last interval.
Review comment:
```suggestion
- **averageMsgSize**: The average size (in bytes) of messages published within the last interval.
```
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -117,137 +112,132 @@ $ pulsar-admin persistent revoke-permission \
}
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
String role = "test-role";
-admin.persistentTopics().revokePermissions(topic, role);
+admin.topics().revokePermissions(topic, role);
```
-### Delete topic
-
-It deletes a topic. The topic cannot be deleted if there's any active subscription or producers connected to it.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
+### Delete topic
-Topic can be deleted using [`delete`](../../reference/CliTools#delete) command.
+You can delete a topic in the following ways. You cannot delete a topic if any active subscription or producers is connected to the topic.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent delete \
+$ pulsar-admin topics delete \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic|operation/deleteTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().delete(topic);
+admin.topics().delete(topic);
```
-### Unload topic
-
-It unloads a topic.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
-
-Topic can be unloaded using [`unload`](../../reference/CliTools#unload) command.
+### Unload topic
+You can unload a topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent unload \
+$ pulsar-admin topics unload \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|PUT|/admin/v2/topics/:tenant/:namespace/:topic/unload|operation/unloadTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().unload(topic);
+admin.topics().unload(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get stats
-It shows current statistics of a given non-partitioned topic.
+You can view the following statistics of a given non-partitioned topic.
- - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second
+ - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second.
- - **msgThroughputIn**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputIn**: The sum of all local and replication publishers' publish rates in bytes per second.
- - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second
+ - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second.
- - **msgThroughputOut**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputOut**: The sum of all local and replication consumers' dispatch rates in bytes per second.
- - **averageMsgSize**: The average size in bytes of messages published within the last interval
+ - **averageMsgSize**: The average size(in bytes) of messages published within the last interval.
- - **storageSize**: The sum of the ledgers' storage size for this topic. Space used to store the messages for the topic
+ - **storageSize**: The sum of the ledgers' storage size for this topic. The space used to store the messages for the topic.
- - **publishers**: The list of all local publishers into the topic. There can be zero or thousands
+ - **publishers**: The list of all local publishers into the topic. The list ranges from zero to thousands.
- - **msgRateIn**: Total rate of messages published by this publisher in messages per second
+ - **msgRateIn**: The total rate of messages published by this publisher in messages per second.
- - **msgThroughputIn**: Total throughput of the messages published by this publisher in bytes per second
+ - **msgThroughputIn**: The total throughput of the messages published by this publisher in bytes per second.
- - **averageMsgSize**: Average message size in bytes from this publisher within the last interval
+ - **averageMsgSize**: The average message size in bytes from this publisher within the last interval.
- - **producerId**: Internal identifier for this producer on this topic
+ - **producerId**: The internal identifier for this producer on this topic.
- - **producerName**: Internal identifier for this producer, generated by the client library
+ - **producerName**: The internal identifier for this producer, generated by the client library.
- - **address**: IP address and source port for the connection of this producer
+ - **address**: The IP address and source port for the connection of this producer.
- - **connectedSince**: Timestamp this producer was created or last reconnected
+ - **connectedSince**: The timestamp when this producer is created or reconnected last time.
- - **subscriptions**: The list of all local subscriptions to the topic
+ - **subscriptions**: The list of all local subscriptions to the topic.
- - **my-subscription**: The name of this subscription (client defined)
+ - **my-subscription**: The name of this subscription. It is defined by the client.
- - **msgRateOut**: Total rate of messages delivered on this subscription (msg/s)
+ - **msgRateOut**: The total rate of messages delivered on this subscription (msg/s).
Review comment:
use the same expression: use "msg/s" and (bytes/s) or in use "in messages per second" "in bytes per second"
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -307,94 +299,95 @@ It shows current statistics of a given non-partitioned topic.
"replication": {}
}
```
+To get the status of a topic, you can use the following ways.
-#### pulsar-admin
-
-Topic stats can be fetched using [`stats`](../../reference/CliTools#stats) command.
-
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent stats \
+$ pulsar-admin topics stats \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace/:topic/stats|operation/getStats}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/topics/:tenant/:namespace/:topic/stats|operation/getStats}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().getStats(topic);
+admin.topics().getStats(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get internal stats
-It shows detailed statistics of a topic.
+You can get the detailed statistics of a topic.
- - **entriesAddedCounter**: Messages published since this broker loaded this topic
+ - **entriesAddedCounter**: Messages published since this broker loaded this topic.
- - **numberOfEntries**: Total number of messages being tracked
+ - **numberOfEntries**: The total number of messages being tracked.
- - **totalSize**: Total storage size in bytes of all messages
+ - **totalSize**: The total storage size in bytes of all messages.
- - **currentLedgerEntries**: Count of messages written to the ledger currently open for writing
+ - **currentLedgerEntries**: The count of messages written to the ledger that is currently open for writing.
- - **currentLedgerSize**: Size in bytes of messages written to ledger currently open for writing
+ - **currentLedgerSize**: The size in bytes of messages written to the ledger that is currently open for writing.
- - **lastLedgerCreatedTimestamp**: time when last ledger was created
+ - **lastLedgerCreatedTimestamp**: The time when the last ledger is created.
- - **lastLedgerCreationFailureTimestamp:** time when last ledger was failed
+ - **lastLedgerCreationFailureTimestamp:** The time when the last ledger failed.
- - **waitingCursorsCount**: How many cursors are "caught up" and waiting for a new message to be published
+ - **waitingCursorsCount**: How many cursors are "caught up" and waiting for a new message to be published.
Review comment:
The number of cursors that are ....?
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -117,137 +112,132 @@ $ pulsar-admin persistent revoke-permission \
}
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
String role = "test-role";
-admin.persistentTopics().revokePermissions(topic, role);
+admin.topics().revokePermissions(topic, role);
```
-### Delete topic
-
-It deletes a topic. The topic cannot be deleted if there's any active subscription or producers connected to it.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
+### Delete topic
-Topic can be deleted using [`delete`](../../reference/CliTools#delete) command.
+You can delete a topic in the following ways. You cannot delete a topic if any active subscription or producers is connected to the topic.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent delete \
+$ pulsar-admin topics delete \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic|operation/deleteTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().delete(topic);
+admin.topics().delete(topic);
```
-### Unload topic
-
-It unloads a topic.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
-
-Topic can be unloaded using [`unload`](../../reference/CliTools#unload) command.
+### Unload topic
+You can unload a topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent unload \
+$ pulsar-admin topics unload \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|PUT|/admin/v2/topics/:tenant/:namespace/:topic/unload|operation/unloadTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().unload(topic);
+admin.topics().unload(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get stats
-It shows current statistics of a given non-partitioned topic.
+You can view the following statistics of a given non-partitioned topic.
- - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second
+ - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second.
- - **msgThroughputIn**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputIn**: The sum of all local and replication publishers' publish rates in bytes per second.
- - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second
+ - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second.
- - **msgThroughputOut**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputOut**: The sum of all local and replication consumers' dispatch rates in bytes per second.
- - **averageMsgSize**: The average size in bytes of messages published within the last interval
+ - **averageMsgSize**: The average size(in bytes) of messages published within the last interval.
- - **storageSize**: The sum of the ledgers' storage size for this topic. Space used to store the messages for the topic
+ - **storageSize**: The sum of the ledgers' storage size for this topic. The space used to store the messages for the topic.
- - **publishers**: The list of all local publishers into the topic. There can be zero or thousands
+ - **publishers**: The list of all local publishers into the topic. The list ranges from zero to thousands.
- - **msgRateIn**: Total rate of messages published by this publisher in messages per second
+ - **msgRateIn**: The total rate of messages published by this publisher in messages per second.
- - **msgThroughputIn**: Total throughput of the messages published by this publisher in bytes per second
+ - **msgThroughputIn**: The total throughput of the messages published by this publisher in bytes per second.
- - **averageMsgSize**: Average message size in bytes from this publisher within the last interval
+ - **averageMsgSize**: The average message size in bytes from this publisher within the last interval.
- - **producerId**: Internal identifier for this producer on this topic
+ - **producerId**: The internal identifier for this producer on this topic.
- - **producerName**: Internal identifier for this producer, generated by the client library
+ - **producerName**: The internal identifier for this producer, generated by the client library.
- - **address**: IP address and source port for the connection of this producer
+ - **address**: The IP address and source port for the connection of this producer.
- - **connectedSince**: Timestamp this producer was created or last reconnected
+ - **connectedSince**: The timestamp when this producer is created or reconnected last time.
- - **subscriptions**: The list of all local subscriptions to the topic
+ - **subscriptions**: The list of all local subscriptions to the topic.
- - **my-subscription**: The name of this subscription (client defined)
+ - **my-subscription**: The name of this subscription. It is defined by the client.
- - **msgRateOut**: Total rate of messages delivered on this subscription (msg/s)
+ - **msgRateOut**: The total rate of messages delivered on this subscription (msg/s).
- - **msgThroughputOut**: Total throughput delivered on this subscription (bytes/s)
+ - **msgThroughputOut**: The total throughput delivered on this subscription (bytes/s).
- - **msgBacklog**: Number of messages in the subscription backlog
+ - **msgBacklog**: The number of messages in the subscription backlog.
- - **type**: This subscription type
+ - **type**: The subscription type.
- - **msgRateExpired**: The rate at which messages were discarded instead of dispatched from this subscription due to TTL
+ - **msgRateExpired**: The rate at which messages were discarded instead of dispatched from this subscription due to TTL.
- - **lastExpireTimestamp**: The last message expire execution timestamp
+ - **lastExpireTimestamp**: The timestamp of the last message expire execution.
- - **lastConsumedFlowTimestamp**: The last flow command received timestamp
+ - **lastConsumedFlowTimestamp**: The timestamp of the last flow command received.
- - **lastConsumedTimestamp**: The latest timestamp of all the consumed timestamp of the consumers
+ - **lastConsumedTimestamp**: The latest timestamp of all the consumed timestamp of the consumers.
- - **lastAckedTimestamp**: The latest timestamp of all the acked timestamp of the consumers
+ - **lastAckedTimestamp**: The latest timestamp of all the acked timestamp of the consumers.
- - **consumers**: The list of connected consumers for this subscription
+ - **consumers**: The list of connected consumers for this subscription.
- - **msgRateOut**: Total rate of messages delivered to the consumer (msg/s)
+ - **msgRateOut**: The total rate of messages delivered to the consumer (msg/s).
- - **msgThroughputOut**: Total throughput delivered to the consumer (bytes/s)
+ - **msgThroughputOut**: The total throughput delivered to the consumer (bytes/s).
- - **consumerName**: Internal identifier for this consumer, generated by the client library
+ - **consumerName**: The internal identifier for this consumer, generated by the client library.
- - **availablePermits**: The number of messages this consumer has space for in the client library's listen queue. A value of 0 means the client library's queue is full and receive() isn't being called. A nonzero value means this consumer is ready to be dispatched messages.
+ - **availablePermits**: The number of messages this consumer has space for in the client library's listen queue. `0` means the client library's queue is full and `receive()` isn't being called. A nonzero value means this consumer is ready to be dispatched messages.
- - **unackedMessages**: Number of unacknowledged messages for the consumer
+ - **unackedMessages**: The number of unacknowledged messages for the consumer.
- - **blockedConsumerOnUnackedMsgs**: Flag to verify if the consumer is blocked due to reaching threshold of unacked messages
+ - **blockedConsumerOnUnackedMsgs**: The flag to verify if the consumer is blocked due to reaching threshold of the unacked messages.
- - **lastConsumedTimestamp**: The timestamp of the consumer last consume a message
+ - **lastConsumedTimestamp**: The timestamp when the consumer reads a message the last time.
- - **lastAckedTimestamp**: The timestamp of the consumer last ack a message
+ - **lastAckedTimestamp**: The timestamp when the consumer acks a message the last time.
Review comment:
```suggestion
- **lastAckedTimestamp**: The timestamp when the consumer acknowledges a message the last time.
```
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -117,137 +112,132 @@ $ pulsar-admin persistent revoke-permission \
}
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic/permissions/:role|operation/revokePermissionsOnTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
String role = "test-role";
-admin.persistentTopics().revokePermissions(topic, role);
+admin.topics().revokePermissions(topic, role);
```
-### Delete topic
-
-It deletes a topic. The topic cannot be deleted if there's any active subscription or producers connected to it.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
+### Delete topic
-Topic can be deleted using [`delete`](../../reference/CliTools#delete) command.
+You can delete a topic in the following ways. You cannot delete a topic if any active subscription or producers is connected to the topic.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent delete \
+$ pulsar-admin topics delete \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|DELETE|/admin/v2/persistent/:tenant/:namespace/:topic|operation/deleteTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|DELETE|/admin/v2/topics/:tenant/:namespace/:topic|operation/deleteTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().delete(topic);
+admin.topics().delete(topic);
```
-### Unload topic
-
-It unloads a topic.
+<!--END_DOCUSAURUS_CODE_TABS-->
-#### pulsar-admin
-
-Topic can be unloaded using [`unload`](../../reference/CliTools#unload) command.
+### Unload topic
+You can unload a topic in the following ways.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent unload \
+$ pulsar-admin topics unload \
persistent://test-tenant/ns1/tp1 \
```
-#### REST API
-
-{@inject: endpoint|PUT|/admin/v2/persistent/:tenant/:namespace/:topic/unload|operation/unloadTopic}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|PUT|/admin/v2/topics/:tenant/:namespace/:topic/unload|operation/unloadTopic}
+<!--Java-->
```java
String topic = "persistent://my-tenant/my-namespace/my-topic";
-admin.persistentTopics().unload(topic);
+admin.topics().unload(topic);
```
+<!--END_DOCUSAURUS_CODE_TABS-->
+
### Get stats
-It shows current statistics of a given non-partitioned topic.
+You can view the following statistics of a given non-partitioned topic.
- - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second
+ - **msgRateIn**: The sum of all local and replication publishers' publish rates in messages per second.
- - **msgThroughputIn**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputIn**: The sum of all local and replication publishers' publish rates in bytes per second.
- - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second
+ - **msgRateOut**: The sum of all local and replication consumers' dispatch rates in messages per second.
- - **msgThroughputOut**: Same as above, but in bytes per second instead of messages per second
+ - **msgThroughputOut**: The sum of all local and replication consumers' dispatch rates in bytes per second.
- - **averageMsgSize**: The average size in bytes of messages published within the last interval
+ - **averageMsgSize**: The average size(in bytes) of messages published within the last interval.
- - **storageSize**: The sum of the ledgers' storage size for this topic. Space used to store the messages for the topic
+ - **storageSize**: The sum of the ledgers' storage size for this topic. The space used to store the messages for the topic.
- - **publishers**: The list of all local publishers into the topic. There can be zero or thousands
+ - **publishers**: The list of all local publishers into the topic. The list ranges from zero to thousands.
- - **msgRateIn**: Total rate of messages published by this publisher in messages per second
+ - **msgRateIn**: The total rate of messages published by this publisher in messages per second.
- - **msgThroughputIn**: Total throughput of the messages published by this publisher in bytes per second
+ - **msgThroughputIn**: The total throughput of the messages published by this publisher in bytes per second.
- - **averageMsgSize**: Average message size in bytes from this publisher within the last interval
+ - **averageMsgSize**: The average message size in bytes from this publisher within the last interval.
- - **producerId**: Internal identifier for this producer on this topic
+ - **producerId**: The internal identifier for this producer on this topic.
- - **producerName**: Internal identifier for this producer, generated by the client library
+ - **producerName**: The internal identifier for this producer, generated by the client library.
- - **address**: IP address and source port for the connection of this producer
+ - **address**: The IP address and source port for the connection of this producer.
- - **connectedSince**: Timestamp this producer was created or last reconnected
+ - **connectedSince**: The timestamp when this producer is created or reconnected last time.
- - **subscriptions**: The list of all local subscriptions to the topic
+ - **subscriptions**: The list of all local subscriptions to the topic.
- - **my-subscription**: The name of this subscription (client defined)
+ - **my-subscription**: The name of this subscription. It is defined by the client.
- - **msgRateOut**: Total rate of messages delivered on this subscription (msg/s)
+ - **msgRateOut**: The total rate of messages delivered on this subscription (msg/s).
- - **msgThroughputOut**: Total throughput delivered on this subscription (bytes/s)
+ - **msgThroughputOut**: The total throughput delivered on this subscription (bytes/s).
- - **msgBacklog**: Number of messages in the subscription backlog
+ - **msgBacklog**: The number of messages in the subscription backlog.
- - **type**: This subscription type
+ - **type**: The subscription type.
- - **msgRateExpired**: The rate at which messages were discarded instead of dispatched from this subscription due to TTL
+ - **msgRateExpired**: The rate at which messages were discarded instead of dispatched from this subscription due to TTL.
- - **lastExpireTimestamp**: The last message expire execution timestamp
+ - **lastExpireTimestamp**: The timestamp of the last message expire execution.
- - **lastConsumedFlowTimestamp**: The last flow command received timestamp
+ - **lastConsumedFlowTimestamp**: The timestamp of the last flow command received.
- - **lastConsumedTimestamp**: The latest timestamp of all the consumed timestamp of the consumers
+ - **lastConsumedTimestamp**: The latest timestamp of all the consumed timestamp of the consumers.
- - **lastAckedTimestamp**: The latest timestamp of all the acked timestamp of the consumers
+ - **lastAckedTimestamp**: The latest timestamp of all the acked timestamp of the consumers.
- - **consumers**: The list of connected consumers for this subscription
+ - **consumers**: The list of connected consumers for this subscription.
- - **msgRateOut**: Total rate of messages delivered to the consumer (msg/s)
+ - **msgRateOut**: The total rate of messages delivered to the consumer (msg/s).
- - **msgThroughputOut**: Total throughput delivered to the consumer (bytes/s)
+ - **msgThroughputOut**: The total throughput delivered to the consumer (bytes/s).
- - **consumerName**: Internal identifier for this consumer, generated by the client library
+ - **consumerName**: The internal identifier for this consumer, generated by the client library.
- - **availablePermits**: The number of messages this consumer has space for in the client library's listen queue. A value of 0 means the client library's queue is full and receive() isn't being called. A nonzero value means this consumer is ready to be dispatched messages.
+ - **availablePermits**: The number of messages this consumer has space for in the client library's listen queue. `0` means the client library's queue is full and `receive()` isn't being called. A nonzero value means this consumer is ready to be dispatched messages.
- - **unackedMessages**: Number of unacknowledged messages for the consumer
+ - **unackedMessages**: The number of unacknowledged messages for the consumer.
- - **blockedConsumerOnUnackedMsgs**: Flag to verify if the consumer is blocked due to reaching threshold of unacked messages
+ - **blockedConsumerOnUnackedMsgs**: The flag to verify if the consumer is blocked due to reaching threshold of the unacked messages.
Review comment:
```suggestion
- **blockedConsumerOnUnackedMsgs**: The flag used to verify if the consumer is blocked due to reaching threshold of the unacknowledged messages.
```
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on pull request #8375: [WIP][docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#issuecomment-716498565
All the REST API links do not work, open an issue in https://github.com/apache/pulsar/issues/8377
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#issuecomment-717037382
@zymap could you please also help check the update? thank you.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on a change in pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on a change in pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#discussion_r518510647
##########
File path: site2/docs/admin-api-persistent-topics.md
##########
@@ -1,80 +1,78 @@
---
id: admin-api-persistent-topics
-title: Managing persistent topics
-sidebar_label: Persistent topics
+title: Manage topics
+sidebar_label: Topics
---
-Persistent helps to access topic which is a logical endpoint for publishing and consuming messages. Producers publish messages to the topic and consumers subscribe to the topic, to consume messages published to the topic.
-
-In all of the instructions and commands below, the topic name structure is:
-
+Pulsar has persistent and non-persistent topics. Persistent topic is a logical endpoint for publishing and consuming messages. The topic name structure for persistent topics is:
```shell
persistent://tenant/namespace/topic
```
-## Persistent topics resources
+Non-persistent topics are used in applications that only consume real-time published messages and do not need persistent guarantee. In this way, it reduces message-publish latency by removing overhead of persisting messages. The topic name structure for non-persistent topics is:
-### List of topics
+```shell
+non-persistent://tenant/namespace/topic
+```
+## Manage topic resources
+Whether it is persistent or non-persistent topic, you can obtain the topic resources through `pulsar-admin` tool, REST API and Java.
-It provides a list of persistent topics exist under a given namespace.
+### List of topics
-#### pulsar-admin
+You can get the list of topics under a given namespace in the following ways.
-List of topics can be fetched using [`list`](../../reference/CliTools#list) command.
+<!--DOCUSAURUS_CODE_TABS-->
+<!--pulsar-admin-->
```shell
-$ pulsar-admin persistent list \
+$ pulsar-admin topics list \
my-tenant/my-namespace
```
-#### REST API
-
-{@inject: endpoint|GET|/admin/v2/persistent/:tenant/:namespace|operation/getList}
-
-#### Java
+<!--REST API-->
+{@inject: endpoint|GET|/admin/v2/topics/:tenant/:namespace|operation/getList}
Review comment:
{@inject: endpoint|GET|/admin/v2/:schema/:tenant/:namespace|operation/getList}
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
[GitHub] [pulsar] Jennifer88huang commented on pull request #8375: [docs] Re-org topics in Admin API section
Posted by GitBox <gi...@apache.org>.
Jennifer88huang commented on pull request #8375:
URL: https://github.com/apache/pulsar/pull/8375#issuecomment-722873475
@tuteng @zymap Thank you very much for your comments. I've updated the REST API part, could you please double confirm? Thank you.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org