This is a question I get often and one that I myself ask quite a bit when working with the FlashArray API. When you query the API for specific metric information, as an example “array performance”, you get a listing of metrics and their values back. Now, the API being what it is, these metric names aren’t always indicative of what the metric value actually means, or how it is calculated.
As an example, if I were to query the API using the PowerShell SDK cmdlet Get-Pfa2VolumePerformance (which BTW is doing a simple GET /api/x.x/volumes/performance call), I get a bunch of values returned.
Id : bdb5d4fe-1f29-3824-97b6-e18676687e7f Name : esxi-30-ds3 BytesPerMirroredWrite : 0 BytesPerOp : 7363 BytesPerRead : 5120 BytesPerWrite : 7663 MirroredWriteBytesPerSec : 0 MirroredWritesPerSec : 0 QosRateLimitUsecPerMirroredWriteOp : 0 QosRateLimitUsecPerReadOp : 0 QosRateLimitUsecPerWriteOp : 0 QueueUsecPerMirroredWriteOp : 0 QueueUsecPerReadOp : 8 QueueUsecPerWriteOp : 8 ReadBytesPerSec : 10239 ReadsPerSec : 2 SanUsecPerMirroredWriteOp : 0 SanUsecPerReadOp : 21 SanUsecPerWriteOp : 139 ServiceUsecPerMirroredWriteOp : 0 ServiceUsecPerReadOp : 74 ServiceUsecPerWriteOp : 159 Time : 8/26/2021 12:46:53 PM UsecPerMirroredWriteOp : 0 UsecPerReadOp : 74 UsecPerWriteOp : 159 WriteBytesPerSec : 118777 WritesPerSec : 15
Now, when looking at this output, I may not really know what SanUsecPerWriteOp means, or maybe I want to know what the 139 integer is (seconds, milliseconds, parsects?). So, we need some kind of cross-reference. Swagger does not cover these (which I think it should, but that’s another rant). Thankfully, there is one piece of documentation out there that spells them all out. By all, I mean not just the performance metrics, but all of the returned values from the API. To find my metric definition, I go the Pure Storage Python Client documentation, look under the Models section, find VolumePerformance and there it is:
- service_usec_per_write_op (int) – The average time required for the array to service a write request. Measured in microseconds.
To determine if the 139 microseconds value is acceptable, that takes a bit more investigation into the environment, the workloads on that volume, and any latency or bandwidth considerations. But, for now, I have solved the mystery of knowing where to go to find the meaning of the metrics and returned values that I submit in my API queries.
The raw editable documentation is available in this GitHub repository.