Nutanix REST API v1 /vms/vmId/statsを試した

# /vms/vmId/stats

## 目的

指定したvmの、指定した項目の値を持ってきたい。
/vms/vmId/stats で、指定した値を持ってこれそうだったので、試してみた。

## REST API エクスプローラ

NutanixにWEBからログインし、
アカウント名の部分をクリックすると、
REST API エクスプローラという項目があるので、クリックする。

以降の説明は、その画面上について、得られた結果を記載する。

REST API エクスプローラで、Nutanix API V1を選択。
/vmsの項目をクリックし、
GET /vms/{vmId}/stats/をクリック。

渡すパラメータとして、以下必須
・vmId
・metrics

以下オプション
・startTimeInUsecs
・endTimeInUsecs
・intervalInSecs

パラメータをセットして、Try it out!をクリックすると、APIが実行される。
（ログインしたNutanixに対して、実際にAPIが実行されて、結果が返ってくる）

## パラメータについて

### vmId

vmIdは、/vmsを実行すれば得られる。内容を見ればすぐわかると思う。

例：

vmId = 00055598-561d-b31d-063c-000c291f003d::80b1c712-0177-440e-a81c-a369e260e867

/vmsで返ってきた内容をそのまま指定しているが、::で区切った左側は、hostId、右側がそのvmのid。
なので、

vmId = 80b1c712-0177-440e-a81c-a369e260e867

でも結果は返ってくる。


### metrics

metricsは、/vmsを実行して得られる情報の、statsの項目で渡せる文字列の一覧を知ることができる。
複数の項目を指定することもできる。その場合は、項目名をカンマ区切りで記載すれば良い。

例：hypervisor_avg_read_io_latency_usecs,hypervisor_avg_write_io_latency_usecs

### startTimeInUsecs

startTimeInUsecsは、データを取得する開始時刻を指定する。
単位は、microsec。Nutanix側でどういうデータを保持しているか不明だが、マイクロ秒で指定する。
あまり深く考えず、単にunixtimeを指定したうえで、末尾に0を6個つけるだけでいい気がする。

例：2017/08/01 14:00:00なら、1501563600000000を指定する。

### endTimeInUsecs

endTimeInUsecsは、データを取得する終了時間を指定する。いつからいつまでのデータを持ってきたい、というときに使う。
startTimeInUsecs以上の値を指定する。不正な指定をすると、startTimeInUsecsが0となって、結果を得ることができない。

例：
2017/08/01 14:00:00 - 2017/08/01 14:30:00のデータを取りたいなら、以下のように指定する。
startTimeInUsecs = 1501563600000000
endTimeInUsecs = 1501565400000000

同じ時刻を指定した場合、そのタイミングのデータ、という指定となる。

### intervalInSecs

指定した時刻の範囲を、指定した間隔で平均化したデータを得る模様。

たとえば、2017/08/01 14:00:00 - 2017/08/01 14:30:00の30分間を指定した場合に、
startTimeInUsecsを起点として、60秒ごとのデータが欲しい場合は、

intervalInSecs = 60

という指定をする。

これで、2017/08/01 14:00:00 - 2017/08/01 14:30:00の期間から、
60秒ごとにデータを集計（平均値）したデータが手に入る。
※開始、もしくは終了の指定した時刻にあるデータも1個と数えるので、31個のデータを得る。

intervalInSecsで指定できる値は、30の倍数になるように調整される。
たとえば、29と指定しても、30として扱われ、31と指定しても、60として扱われる。

## 実行結果

### パラメータ

vmId = 00055598-561d-b31d-063c-000c291f003d::80b1c712-0177-440e-a81c-a369e260e867
metrics = hypervisor_avg_read_io_latency_usecs,hypervisor_avg_write_io_latency_usecs,hypervisor_cpu_usage_ppm
startTimeInUsecs = 1501563600000000
endTimeInUsecs = 1501565400000000
intervalInSecs = 60

これでTry it out!をクリックすると、以下のようになる。

### Request URL

```
https://NutanixのIPアドレス:9440/PrismGateway/services/rest/v1/vms/00055598-561d-b31d-063c-000c291f003d%3A%3A80b1c712-0177-440e-a81c-a369e260e867/stats/?metrics=hypervisor_avg_read_io_latency_usecs%2Chypervisor_avg_write_io_latency_usecs%2Chypervisor_cpu_usage_ppm&startTimeInUsecs=1501563600000000&endTimeInUsecs=1501565400000000&intervalInSecs=60
```

### Response Body

```json
{
  "statsSpecificResponses": [
    {
      "successful": true,
      "message": null,
      "startTimeInUsecs": 1501563600000000,
      "intervalInSecs": 60,
      "metric": "hypervisor_avg_read_io_latency_usecs",
      "values": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    {
      "successful": true,
      "message": null,
      "startTimeInUsecs": 1501563600000000,
      "intervalInSecs": 60,
      "metric": "hypervisor_avg_write_io_latency_usecs",
      "values": [
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0,
        0
      ]
    },
    {
      "successful": true,
      "message": null,
      "startTimeInUsecs": 1501563600000000,
      "intervalInSecs": 60,
      "metric": "hypervisor_cpu_usage_ppm",
      "values": [
        12282,
        12240,
        13938,
        13851,
        12671,
        14273,
        16015,
        14531,
        13273,
        13030,
        12772,
        12723,
        13171,
        13005,
        13423,
        13796,
        13081,
        13131,
        12711,
        13713,
        12136,
        13508,
        13563,
        15609,
        15856,
        13784,
        14553,
        14163,
        14225,
        14793,
        5065
      ]
    }
  ]
}
```

### Response Code

```
200
```
### Response Headers

```
Date: Tue, 01 Aug 2017 06:16:06 GMT
Content-Encoding: gzip
X-Content-Type-Options: nosniff
X-Permitted-Cross-Domain-Policies: master-only
X-DNS-Prefetch-Control: off
Connection: Keep-Alive
X-XSS-Protection: 1; mode=block
Pragma: no-cache
Server: Nutanix Prism
X-Frame-Options: SAMEORIGIN
Vary: Accept-Encoding,User-Agent
Strict-Transport-Security: max-age=8640000;includeSubdomains
Content-Type: application/json
Cache-Control: no-store, no-cache, must-revalidate
Transfer-Encoding: chunked
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval';  style-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self' wss:; img-src 'self' blob: data:;
Keep-Alive: timeout=5, max=98
X-WebKit-CSP: default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval';  style-src 'self' 'unsafe-inline' 'unsafe-eval'; connect-src 'self' wss:; img-src 'self' blob: data:;
Expires: 0
```

## intervalInSecsによるデータの平均化

Nutanixの内部では、（たぶん）30秒ごとに、データを持っている模様。
intervalInSecsによって、指定した間隔で、データを集計し、平均値にしている模様。

たとえば、hypervisor_cpu_usage_ppmのデータを、60秒間隔と300秒間隔で取得し、
並べてみると、以下のようになる。

```
2017/08/01 14:00 - 14:30のデータを、60秒間隔で。

2017/08/01 14:00:00        12282,
2017/08/01 14:01:00        12240,
2017/08/01 14:02:00        13938,
2017/08/01 14:03:00        13851,
2017/08/01 14:04:00        12671,
2017/08/01 14:05:00        14273,
2017/08/01 14:06:00        16015,
2017/08/01 14:07:00        14531,
2017/08/01 14:08:00        13273,
2017/08/01 14:09:00        13030,
2017/08/01 14:10:00        12772,
2017/08/01 14:11:00        12723,
2017/08/01 14:12:00        13171,
2017/08/01 14:13:00        13005,
2017/08/01 14:14:00        13423,
2017/08/01 14:15:00        13796,
2017/08/01 14:16:00        13081,
2017/08/01 14:17:00        13131,
2017/08/01 14:18:00        12711,
2017/08/01 14:19:00        13713,
2017/08/01 14:20:00        12136,
2017/08/01 14:21:00        13508,
2017/08/01 14:22:00        13563,
2017/08/01 14:23:00        15609,
2017/08/01 14:24:00        15856,
2017/08/01 14:25:00        13784,
2017/08/01 14:26:00        14553,
2017/08/01 14:27:00        14163,
2017/08/01 14:28:00        14225,
2017/08/01 14:29:00        14793,
2017/08/01 14:30:00        5065

2017/08/01 14:00 - 14:30のデータを、300秒間隔で。

2017/08/01 14:00:00        12996, // 14:00 - 14:04のデータの平均
2017/08/01 14:05:00        14224, // 14:05 - 14:09のデータの平均
2017/08/01 14:10:00        13019, // 14:10 - 14:14のデータの平均
2017/08/01 14:15:00        13286, // 14:15 - 14:19のデータの平均
2017/08/01 14:20:00        14134, // 14:20 - 14:24のデータの平均
2017/08/01 14:25:00        14303, // 14:25 - 14:29のデータの平均
2017/08/01 14:30:00        5065   // 14:30のデータ。1個しかないので、そのまま。


```

## /vmsの内容（vmIdとstatsを得るために必要）

```json

{
  "vmId": "00055598-561d-b31d-063c-000c291f003d::80b1c712-0177-440e-a81c-a369e260e867",
  "uuid": "80b1c712-0177-440e-a81c-a369e260e867",
  "powerState": "on",
  "vmName": "testVM",
  "guestOperatingSystem": null,
  "ipAddresses": [
    "192.168.0.1"
  ],
  "hypervisorType": "kKvm",
  "hostName": "NTNX",
  "hostId": "00055598-561d-b31d-063c-000c291f003d::2",
  "hostUuid": "0122f8d9-8c2e-460e-9a5d-180ccbbf09c6",
  "containerIds": [
    "00055598-561d-b31d-063c-000c291f003d::4"
  ],
  "containerUuids": [
    "1c91a6a0-16f6-4ae3-aa64-45be06945721"
  ],
  "nutanixVirtualDisks": [
    "/default-container-74497088557416/.acropolis/vmdisk/99c0fdfa-3885-4169-adb8-f5fa486a1022"
  ],
  "nutanixVirtualDiskIds": [
    "00055598-561d-b31d-063c-000c291f003d::99c0fdfa-3885-4169-adb8-f5fa486a1022"
  ],
  "nutanixVirtualDiskUuids": [
    "99c0fdfa-3885-4169-adb8-f5fa486a1022"
  ],
  "virtualNicIds": [
    "00055598-561d-b31d-063c-000c291f003d::80b1c712-0177-440e-a81c-a369e260e867:50:00:00:63:00:cd"
  ],
  "virtualNicUuids": [
    "0a7bf3f9-9b72-48bc-ad05-614bfbf52233"
  ],
  "clusterUuid": "00055598-561d-b31d-063c-000c291f003d",
  "memoryCapacityInBytes": 2147483648,
  "memoryReservedCapacityInBytes": 2147483648,
  "numVCpus": 1,
  "cpuReservedInHz": null,
  "numNetworkAdapters": 1,
  "controlDomain": null,
  "vdiskNames": [
    "00055598-561d-b31d-063c-000c291f003d::NFS:1:0:258"
  ],
  "vdiskFilePaths": [
    "/default-container-74497088557416/.acropolis/vmdisk/99c0fdfa-3885-4169-adb8-f5fa486a1022"
  ],
  "diskCapacityInBytes": 34359738368,
  "protectionDomainName": null,
  "consistencyGroupName": null,
  "fingerPrintOnWrite": "none",
  "onDiskDedup": "NONE",
  "stats": {
    "hypervisor_avg_io_latency_usecs": "0",
    "num_read_iops": "-1",
    "hypervisor_write_io_bandwidth_kBps": "0",
    "timespan_usecs": "-1",
    "controller_num_read_iops": "-1",
    "controller.storage_tier.ssd.usage_bytes": "1336246272",
    "read_io_ppm": "-1",
    "controller_num_iops": "-1",
    "hypervisor_memory_assigned_bytes": "-1",
    "total_read_io_time_usecs": "-1",
    "controller_total_read_io_time_usecs": "0",
    "controller.storage_tier.ssd.configured_pinned_bytes": "0",
    "hypervisor_num_io": "0",
    "controller_total_transformed_usage_bytes": "0",
    "hypervisor_cpu_usage_ppm": "16432",
    "controller_num_write_io": "-1",
    "avg_read_io_latency_usecs": "-1",
    "guest.memory_swapped_in_bytes": "0",
    "controller_total_io_time_usecs": "0",
    "controller_total_read_io_size_kbytes": "0",
    "controller_num_seq_io": "-1",
    "controller_read_io_ppm": "-1",
    "controller_total_io_size_kbytes": "0",
    "hypervisor.cpu_ready_time_ppm": "369",
    "controller_num_io": "0",
    "hypervisor_avg_read_io_latency_usecs": "0",
    "num_write_iops": "-1",
    "controller_num_random_io": "0",
    "num_iops": "-1",
    "guest.memory_usage_ppm": "233580",
    "hypervisor_num_read_io": "0",
    "hypervisor_total_read_io_time_usecs": "0",
    "controller_avg_io_latency_usecs": "-1",
    "num_io": "-1",
    "controller_num_read_io": "0",
    "hypervisor_num_write_io": "0",
    "controller_seq_io_ppm": "-1",
    "guest.memory_usage_bytes": "429756416",
    "controller_read_io_bandwidth_kBps": "-1",
    "controller_io_bandwidth_kBps": "-1",
    "hypervisor_num_received_bytes": "105592",
    "hypervisor_timespan_usecs": "29818505",
    "hypervisor_num_write_iops": "0",
    "total_read_io_size_kbytes": "-1",
    "hypervisor_total_io_size_kbytes": "0",
    "avg_io_latency_usecs": "-1",
    "hypervisor_num_read_iops": "0",
    "hypervisor_swap_in_rate_kBps": "-1",
    "controller_write_io_bandwidth_kBps": "-1",
    "controller_write_io_ppm": "-1",
    "controller_user_bytes": "1326477312",
    "hypervisor_avg_write_io_latency_usecs": "0",
    "hypervisor_num_transmitted_bytes": "0",
    "hypervisor_total_read_io_size_kbytes": "0",
    "read_io_bandwidth_kBps": "-1",
    "guest.memory_swapped_out_bytes": "0",
    "hypervisor_memory_usage_ppm": "1000000",
    "hypervisor_num_iops": "0",
    "hypervisor_io_bandwidth_kBps": "0",
    "controller_num_write_iops": "-1",
    "total_io_time_usecs": "-1",
    "controller_random_io_ppm": "-1",
    "controller.storage_tier.das-sata.usage_bytes": "0",
    "controller_avg_read_io_size_kbytes": "-1",
    "hypervisor_swap_out_rate_kBps": "-1",
    "total_transformed_usage_bytes": "-1",
    "avg_write_io_latency_usecs": "-1",
    "num_read_io": "-1",
    "write_io_bandwidth_kBps": "-1",
    "hypervisor_read_io_bandwidth_kBps": "0",
    "hypervisor_consumed_memory_bytes": "2184302592",
    "random_io_ppm": "-1",
    "total_untransformed_usage_bytes": "-1",
    "hypervisor_total_io_time_usecs": "0",
    "num_random_io": "-1",
    "controller_avg_write_io_size_kbytes": "-1",
    "controller_avg_read_io_latency_usecs": "-1",
    "controller.storage_tier.das-sata.configured_pinned_bytes": "0",
    "num_write_io": "-1",
    "total_io_size_kbytes": "-1",
    "controller.storage_tier.cloud.usage_bytes": "0",
    "io_bandwidth_kBps": "-1",
    "controller_timespan_usecs": "0",
    "num_seq_io": "-1",
    "seq_io_ppm": "-1",
    "write_io_ppm": "-1",
    "controller_avg_write_io_latency_usecs": "-1"
  },
  "usageStats": {},
  "nutanixGuestTools": {
    "vmId": "00055598-561d-b31d-063c-000c291f003d::80b1c712-0177-440e-a81c-a369e260e867",
    "vmUuid": "80b1c712-0177-440e-a81c-a369e260e867",
    "enabled": false,
    "applications": {
      "vss_snapshot": false,
      "file_level_restore": false
    },
    "toolsMounted": false,
    "vmName": "testVM",
    "communicationLinkActive": false,
    "toRemove": false
  },
  "gpusInUse": false,
  "controllerVm": false,
  "displayable": true,
  "acropolisVm": true,
  "runningOnNdfs": true
}

```

## v2とかv3

v1だと、上記のように、いろんなパフォーマンス情報が取得できるが、
どうやら、現時点でv1のみの機能になる模様。

自分と同じように、パフォーマンスチャートについて質問している人がいたが、
Nutanixの従業員が、v1オンリーだと回答している。うーん。

https://next.nutanix.com/t5/API/Performance-metrics/td-p/21841

v2やv3も、REST APIエクスぽローラーを触って、とれる内容を確認してみたが、
v1のstatsに当たる内容が、見当たらない・・・。

v1は今後なくなるとか、v1使っているユーザーはv2以降に切り替えろ、という案内があるようだが、、、
パフォーマンスの情報を、v2、v3でとれるようにして欲しいorz