[improve][pip] PIP-347: add role field in consumer's stat

pip/pip-347.md

@@ -0,0 +1,57 @@
+
+# PIP-347: add role field in consumer's stat
+
+# Background knowledge
+
+During the operation and maintenance process, there are many users asking administrator for help to find out the consumers of a topic and notify them about the business change.
+Administrators can call `bin/pulsar-admin topics partitioned-stats` to find out the `ip:port` of the consumers, but no role info. So administrators need to take a lot of time to
+communicate with users to find out the owner based on the `ip:port`. It's a troublesome work and low efficiency.
+
+# Motivation
+
+This pip can help to solve such kind of problem. By adding a field `role` in the consumer's stat, the administrator can find out the owner of the consumer directly. 
+It can save a lot of time and improve the efficiency of the operation and maintenance process.
+
+# Goals
+
+- help administrator to find out the owner of the consumer
+
+# Detailed Design
+
+## Design & Implementation Details
+- Add a field `role` in the consumer's stat to show the owner of this consumer.
+- For some use cases, the role info is sensitive, so we only expose the role info when the cli tool option `--expose-role` is set
+  and the user is a super-user or a tenant admin.
+
+## Public-facing Changes
+
+### Public API
+Add a new option `exposeRole` for following endpoints:
+- `GET /admin/v2/persistent/{tenant}/{namespace}/{topic}/partitioned-stats` 
+- `GET /admin/v2/persistent/{tenant}/{namespace}/{topic}/stats` 
+- `GET /admin/v2/non-persistent/{tenant}/{namespace}/{topic}/partitioned-stats`
+- `GET /admin/v2/non-persistent/{tenant}/{namespace}/{topic}/stats`
+
+`exposeRole` is a boolean value, default is false. If it's true and the user is a super-user or a tenant admin, the role info will be exposed.
+
+### CLI
+Add a new option `--expose-role` for command `bin/pulsar-admin topics partitioned-stats` 
+and `bin/pulsar-admin topics stats` to show the role info of the consumer.
+
+### ADMIN API
+Add a new input parameter `exposeRole` in the `admin.topics().getPartitionedStats` and `admin.topics().getStats` to show the role info of the consumer.
+
+
+# Backward & Forward Compatibility
+
+Fully compatible.
+
+# General Notes
+
+# Links
+
+<!--
+Updated afterwards
+-->
+* Mailing List discussion thread: https://lists.apache.org/thread/p9y9r8pb7ygk8f0jd121c1121phvzd09
+* Mailing List voting thread: