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