[GitHub] [pulsar] liangyepianzhou commented on a diff in pull request #16434: [feature][doc] Admin API for Transactions

[GitBox <gi...@apache.org>]

liangyepianzhou commented on code in PR #16434:
URL: https://github.com/apache/pulsar/pull/16434#discussion_r922962734


##########
site2/docs/admin-api-transactions.md:
##########
@@ -0,0 +1,712 @@
+---
+id: admin-api-transactions
+title: Manage transactions
+sidebar_label: "Transactions"
+---
+
+````mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+````
+
+
+:::tip
+
+This page only shows **some frequently used operations**.
+
+- For the latest and complete information about `Pulsar admin`, including commands, flags, descriptions, and more, see [Pulsar admin doc](/tools/pulsar-admin/)
+
+- For the latest and complete information about `REST API`, including parameters, responses, samples, and more, see {@inject: rest:REST:/} API doc.
+
+- For the latest and complete information about `Java admin API`, including classes, methods, descriptions, and more, see [Java admin API doc](/api/admin/).
+
+:::
+
+## Transaction resources
+
+### GetSlowTransactions
+
+In the production environment, there may be some long-lasting transactions that have never been completed. You can get these slow transactions that have survived over a certain time under a coordinator or all coordinators in the following ways.
+
+````mdx-code-block
+<Tabs groupId="api-choice"
+ defaultValue="pulsar-admin"
+ values={[{"label":"pulsar-admin","value":"pulsar-admin"},{"label":"REST API","value":"REST API"},{"label":"Java","value":"Java"}]}>
+<TabItem value="pulsar-admin">
+
+```shell
+
+$ pulsar-admin transactions slow-transactions \
+ -c 1 -t 1s
+
+```
+
+</TabItem>
+<TabItem value="REST API">
+
+{@inject: endpoint|GET|/admin/v3/transactions/slowTransactions/:timeout|operation/getSlowTransactions?version=@pulsar:version_number@}
+
+</TabItem>
+<TabItem value="Java">
+
+```java
+
+admin.transaction().getSlowTransactionsByCoordinatorId(coordinatorId, timeout, timeUnit)
+//Or get slow transactions from all coordinators
+admin.transaction().getSlowTransactions(timeout, timeUnit)
+
+```
+
+</TabItem>
+
+</Tabs>
+````
+
+### ScaleTransactionCoordinators
+
+When the performance of transactions reaches a bottleneck due to the insufficient number of transaction coordinators, you can scale the number of the transaction coordinators in the following ways.
+
+````mdx-code-block
+<Tabs groupId="api-choice"
+ defaultValue="pulsar-admin"
+ values={[{"label":"pulsar-admin","value":"pulsar-admin"},{"label":"REST API","value":"REST API"},{"label":"Java","value":"Java"}]}>
+<TabItem value="pulsar-admin">
+
+```shell
+
+$ pulsar-admin transactions scale-transactionCoordinators \
+ -r 17
+
+```
+
+</TabItem>
+<TabItem value="REST API">
+
+{@inject: endpoint|GET|/admin/v3/transactions/transactionCoordinator/:replicas|operation/scaleTransactionCoordinators?version=@pulsar:version_number@}
+
+</TabItem>
+<TabItem value="Java">
+
+```java
+
+admin.transaction().scaleTransactionCoordinators(replicas);
+
+```
+
+</TabItem>
+
+</Tabs>
+````
+
+## Transaction stats
+
+### Get transaction metadata
+
+The transaction metadata that can be retrieved include:
+* **txnId:** The ID of this transaction.
+* **status:** The status of this transaction.
+* **openTimestamp:** The open time of this transaction.
+* **timeoutAt:** The timeout of this transaction.
+* **producedPartitions:** The partitions or topics that messages have been sent to with this transaction.
+* **ackedPartitions:** The partitions or topics where messages have been acknowledged with this transaction.
+
+Use one of the following ways to get your transaction metadata.
+
+````mdx-code-block
+<Tabs groupId="api-choice"
+ defaultValue="pulsar-admin"
+ values={[{"label":"pulsar-admin","value":"pulsar-admin"},{"label":"REST API","value":"REST API"},{"label":"Java","value":"Java"}]}>
+<TabItem value="pulsar-admin">
+
+```shell
+
+$ pulsar-admin transactions transaction-metadata\
+ -m 1 -l 1
+
+```
+
+</TabItem>
+<TabItem value="REST API">
+
+{@inject: endpoint|GET|/admin/v3/transactions/transactionMetadata/:mostSigBits/:leastSigBits|operation/getTransactionMetadata?version=@pulsar:version_number@}
+
+</TabItem>
+<TabItem value="Java">
+
+```java
+
+admin.transactions().getTransactionMetadata(txnID);
+
+```
+
+</TabItem>
+
+</Tabs>
+````
+
+The following is an example of the returned values.
+
+```shell
+
+{
+ "txnId" : "(1,18)",
+ "status" : "ABORTING",
+ "openTimestamp" : 1656592983374,
+ "timeoutAt" : 5000,
+ "producedPartitions" : {
+   "my-topic" : {
+     "startPosition" : null,
+     "aborted" : true
+   }
+ },
+ "ackedPartitions" : {
+   "my-topic" : {
+     "mysubName" : {
+       "cumulativeAckPosition" : null

Review Comment:
   This is the actual production data, but this `"startPosition" : null` is really strange.



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

To unsubscribe, e-mail: commits-unsubscribe@pulsar.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org