Admin API

The Admin API provides a simple way to view cluster information, including metasrv health detection, metasrv leader query, database metadata query, and datanode heartbeat detection.

The Admin API is an HTTP service that provides a set of RESTful APIs that can be called through HTTP requests. The Admin API is simple, user-friendly and safe. Available APIs:

  • /health
  • /leader
  • /heartbeat
  • /maintenance

All these APIs are under the parent resource /admin.

In the following sections, we assume that your metasrv instance is running on localhost port 3002.

/health HTTP endpoint

The /health endpoint accepts GET HTTP requests and you can use this endpoint to check the health of your metasrv instance.

Definition

  1. curl -X GET http://localhost:3002/admin/health

Examples

Request

  1. curl -X GET http://localhost:3002/admin/health

Response

  1. OK

/leader HTTP endpoint

The /leader endpoint accepts GET HTTP requests and you can use this endpoint to query the leader’s addr of your metasrv instance.

Definition

  1. curl -X GET http://localhost:3002/admin/leader

Examples

Request

  1. curl -X GET http://localhost:3002/admin/leader

Response

  1. 127.0.0.1:3002

/heartbeat HTTP endpoint

The /heartbeat endpoint accepts GET HTTP requests and you can use this endpoint to query the heartbeat of all datanodes.

You can also query the heartbeat data of the datanode for a specified addr, however, specifying addr in the path is optional.

Definition

  1. curl -X GET http://localhost:3002/admin/heartbeat
Query String ParameterTypeOptional/RequiredDefinition
addrStringOptionalThe addr of the datanode.

Examples

Request

  1. curl -X GET 'http://localhost:3002/admin/heartbeat?addr=127.0.0.1:4100'

Response

  1. [
  2. [{
  3. "timestamp_millis": 1677049348651,
  4. "cluster_id": 0,
  5. "id": 1,
  6. "addr": "127.0.0.1:4100",
  7. "is_leader": false,
  8. "rcus": 0,
  9. "wcus": 0,
  10. "table_num": 0,
  11. "region_num": 2,
  12. "cpu_usage": 0.0,
  13. "load": 0.0,
  14. "read_io_rate": 0.0,
  15. "write_io_rate": 0.0,
  16. "region_stats": []
  17. }, {
  18. "timestamp_millis": 1677049344048,
  19. "cluster_id": 0,
  20. "id": 1,
  21. "addr": "0.0.0.0:4100",
  22. "is_leader": false,
  23. "rcus": 0,
  24. "wcus": 0,
  25. "table_num": 0,
  26. "region_num": 2,
  27. "cpu_usage": 0.0,
  28. "load": 0.0,
  29. "read_io_rate": 0.0,
  30. "write_io_rate": 0.0,
  31. "region_stats": []
  32. }, {
  33. "timestamp_millis": 1677049343624,
  34. "cluster_id": 0,
  35. "id": 1,
  36. "addr": "127.0.0.1:4100",
  37. "is_leader": false,
  38. "rcus": 0,
  39. "wcus": 0,
  40. "table_num": 0,
  41. "region_num": 2,
  42. "cpu_usage": 0.0,
  43. "load": 0.0,
  44. "read_io_rate": 0.0,
  45. "write_io_rate": 0.0,
  46. "region_stats": []
  47. }, {
  48. "timestamp_millis": 1677049339036,
  49. "cluster_id": 0,
  50. "id": 1,
  51. "addr": "0.0.0.0:4100",
  52. "is_leader": false,
  53. "rcus": 0,
  54. "wcus": 0,
  55. "table_num": 0,
  56. "region_num": 2,
  57. "cpu_usage": 0.0,
  58. "load": 0.0,
  59. "read_io_rate": 0.0,
  60. "write_io_rate": 0.0,
  61. "region_stats": []
  62. }, {
  63. "timestamp_millis": 1677049338609,
  64. "cluster_id": 0,
  65. "id": 1,
  66. "addr": "127.0.0.1:4100",
  67. "is_leader": false,
  68. "rcus": 0,
  69. "wcus": 0,
  70. "table_num": 0,
  71. "region_num": 2,
  72. "cpu_usage": 0.0,
  73. "load": 0.0,
  74. "read_io_rate": 0.0,
  75. "write_io_rate": 0.0,
  76. "region_stats": []
  77. }, {
  78. "timestamp_millis": 1677049334019,
  79. "cluster_id": 0,
  80. "id": 1,
  81. "addr": "0.0.0.0:4100",
  82. "is_leader": false,
  83. "rcus": 0,
  84. "wcus": 0,
  85. "table_num": 0,
  86. "region_num": 2,
  87. "cpu_usage": 0.0,
  88. "load": 0.0,
  89. "read_io_rate": 0.0,
  90. "write_io_rate": 0.0,
  91. "region_stats": []
  92. }, {
  93. "timestamp_millis": 1677049333592,
  94. "cluster_id": 0,
  95. "id": 1,
  96. "addr": "127.0.0.1:4100",
  97. "is_leader": false,
  98. "rcus": 0,
  99. "wcus": 0,
  100. "table_num": 0,
  101. "region_num": 2,
  102. "cpu_usage": 0.0,
  103. "load": 0.0,
  104. "read_io_rate": 0.0,
  105. "write_io_rate": 0.0,
  106. "region_stats": []
  107. }, {
  108. "timestamp_millis": 1677049329002,
  109. "cluster_id": 0,
  110. "id": 1,
  111. "addr": "0.0.0.0:4100",
  112. "is_leader": false,
  113. "rcus": 0,
  114. "wcus": 0,
  115. "table_num": 0,
  116. "region_num": 2,
  117. "cpu_usage": 0.0,
  118. "load": 0.0,
  119. "read_io_rate": 0.0,
  120. "write_io_rate": 0.0,
  121. "region_stats": []
  122. }, {
  123. "timestamp_millis": 1677049328573,
  124. "cluster_id": 0,
  125. "id": 1,
  126. "addr": "127.0.0.1:4100",
  127. "is_leader": false,
  128. "rcus": 0,
  129. "wcus": 0,
  130. "table_num": 0,
  131. "region_num": 2,
  132. "cpu_usage": 0.0,
  133. "load": 0.0,
  134. "read_io_rate": 0.0,
  135. "write_io_rate": 0.0,
  136. "region_stats": []
  137. }, {
  138. "timestamp_millis": 1677049323986,
  139. "cluster_id": 0,
  140. "id": 1,
  141. "addr": "0.0.0.0:4100",
  142. "is_leader": false,
  143. "rcus": 0,
  144. "wcus": 0,
  145. "table_num": 0,
  146. "region_num": 2,
  147. "cpu_usage": 0.0,
  148. "load": 0.0,
  149. "read_io_rate": 0.0,
  150. "write_io_rate": 0.0,
  151. "region_stats": []
  152. }]
  153. ]

/maintenance HTTP endpoint

The metasrv will ignore detected region failures when under maintenance. This is useful when the datanodes are planned to be unavailable for a short period of time; for example, rolling upgrade for datanodes.

GET

The /maintenance endpoint accepts GET HTTP requests and you can use this endpoint to query the maintenance status of your metasrv instance.

  1. curl -X GET http://localhost:3002/admin/maintenance

Request

  1. curl -X GET http://localhost:3002/admin/maintenance

Response

  1. Maintenance mode is disabled

PUT

The /maintenance endpoint accepts PUT HTTP requests and you can toggle the maintenance status of your metasrv instance.

  1. curl -X PUT http://localhost:3002/admin/maintenance
Query String ParameterTypeOptional/RequiredDefinition
enableStringRequired‘true’ or ‘false’

Request

  1. curl -X PUT http://localhost:3002/admin/maintenance?enable=true

Response

  1. Maintenance mode enabled