WilliamLam.com

Using the vSphere API in vCenter Server to collect ESXTOP & vscsiStats metrics

by // 1 Comment

Back in 2013, I wrote two articles here and here on how to use the Service Manager API that was introduced in vSphere 5.1 to remotely collect ESXTOP and vscsiStats metrics. At the time, I was told that this API was only available when connecting directly to an ESXi host using the vSphere API. This was still a huge improvement over the previous method which basically required customers to run the commands locally. For ESXTOP, there was resxtop but it was not available for all platforms and some customers still prefer to use the ESXi Shell's version. When I had learned about this API, I was really hoping I could collect both ESXTOP & vscsiStats metrics using vCenter Server which would remove the need to have direct connectivity to each ESXi host.

Last week, an Engineer came across one of my blog posts related to the Service Manager APIs which helped him with a problem he was trying to solve. In the email conversation, I then came to learn from the Engineer that the the Service Manager API can be used from vCenter Server and going directly to the ESXi host was not necessary. It turns out that the QueryServiceList() method which accepts an array of "location" expects a special keyword prefix appended to the list of ESXi hosts that you wish to use the local Service Manager instances on.

The special keyword prefix is "vmware.host." and this is appended to either the Hostname or IP Address of the ESXi hosts being managed by the vCenter Server. For example, in my environment I have an ESXi host (192.168.1.50) that is managed by my VC and so the location string for that host should be "vmware.host.192.168.1.50". If the method was successfully called, you should get back the two service instances for ESXTOP and vscsiStats for each of the ESXi hosts where you can then perform the metric collection.

I have created two sample pyvmomi scripts which exercises the Service Manager API for ESXTOP and vscsiStats:

Note: For more details on how to use Service Manager API to collect ESXTOP and vscsiStats, please refer to this post here and here.

[Read more...]

Required vSphere Privilege for Read-Only RESXTOP View

by // 1 Comment

Yesterday I received a question about the specific vSphere privilege that is required to view RESXTOP data on an ESXi host. The reason for this request was to create a restricted role for a group of users who only needed to have access to RESXTOP performance data. I did not know the answer off the top of my head, but it was a pretty easy to narrow down the specific privilege with a quick test in my lab.

Through the process of elimination, it turns out you just need the Global.Service managers privilege to view only RESXTOP data. It may not seem intuitive, but the Service Manager is responsible for providing vSphere API access to both RESXTOP as well as vScsiStats interfaces which I have written about here.

In my lab, I created a new role called resxtop and then associated the role with the user(s) within the vSphere inventory. You can centrally manage this using vCenter Server or you can do this directly on an ESXi host, but you will need to ensure the role is create on each and every single ESXi host along with it's user association.

Retrieving vscsiStats Using the vSphere 5.1 API

by // Leave a Comment

In my previous article, I talked about the new Service Manager API that was introduced in vSphere 5.1 and how you can retrieve ESXTOP performance data using this new vSphere API. In this article I will show you how to collect vscsiStats data using this same interface. If you are not familiar or have not used vscsiStats before, I would highly recommend you take a look at the Using vscsiStats for Storage Performance Analysis as it goes over some of the basics of vscsiStats and how it works.

UPDATE 02/15/2017 - Please see this updated article here for how to access this API using vCenter Server.

Disclaimer: You should try to limit the use of these interfaces for statistics collection or debugging/troubleshooting purposes as there is a certain amount of overhead when running these commands. It is also important to note that since the output is based on the implementer of the service, there is no guarantee that output would not change from one release to the other.

The first step is to get a reference to the vscsiStats service via the Service Manager (must connect directly to an ESXi 5. host, this is not supported when connecting to vCenter Server) and to invoke an operation for vscsiStats, you will need to use the ExecuteSimpleCommand. For vscsiStats, there are four valid operations:

  • StartVscsiStats
  • FetchAllHistograms
  • ResetVscsiStats
  • StopVscsiStats

To demonstrate the vscsiStats interface, I have written a sample vSphere SDK for Perl script called getVscsiStats.pl which I will use to explain each operation. Please note the data set that is retrieved is in it's raw data form and requires a bit of data processing.

StartVscsiStats

This operation starts the vscsiStats collection for ALL virtual machines residing on your ESXi hosts. This is exactly the same operation if you were to only specify the -s option to the vscsiStats command-line. Here is a screenshot of the "start" operation implemented in the script:

You should see a response of OK from the output and this would indicate the vscsiStats collection has started.

FetchAllHistograms

This operation fetches ALL the vscsiStats histogram data similar to specifying the -p All option in the vscsiStats command-line. The output contains the following:

The tag denotes the details about each Virtual Machine:

  • VM Display Name
  • VM VMX Configuration Path
  • VM BIOS UUID
  • vCenter Server UUID

This is then followed by the tag which provides the VMDK name in the format of scsi:X:Y and within each virtual disk section it will contain 13 tags which represents each of the statistics type and their associated values:

  1. VSCSIVsi_DistanceHistogram: Histogram: distance (in LBNs) between successive commands
  2. VSCSIVsi_DistanceLast16Histogram: Histogram: distance (in LBNs) between each command from the closest of previous 16
  3. VSCSIVsi_DistanceReadsHistogram: Histogram: distance (in LBNs) between successive Read commands
  4. VSCSIVsi_DistanceWritesHistogram: Histogram: distance (in LBNs) between successive Write commands
  5. VSCSIVsi_IoLatencyHistogram: Histogram: latency of IOs in Microseconds (us)
  6. VSCSIVsi_IoLatencyReadsHistogram: Histogram: latency of Read IOs in Microseconds (us)
  7. VSCSIVsi_IoLatencyWritesHistogram: Histogram: latency of Write IOs in Microseconds (us)
  8. VSCSIVsi_IoLengthHistogram: Histogram: IO lengths of commands
  9. VSCSIVsi_IoLengthReadsHistogram: Histogram: IO lengths of Read commands
  10. VSCSIVsi_IoLengthWritesHistogram: Histogram: IO lengths of Write commands
  11. VSCSIVsi_OutstandingIOsHistogram: Histogram: number of outstanding IOs when a new IO is issued
  12. VSCSIVsi_OutstandingIOsReadsHistogram: Histogram: number of outstanding Read IOs when a new Read IO is issued
  13. VSCSIVsi_OutstandingIOsWritesHistogram: Histogram: number of outstanding Write IOs when a new Write IO is issued

Here is a screenshot of the "getstats" operation implemented in the script:

Note: In comparing the output between the vscsiStats command-line and this interface, I found the following three statistics are not available:

  • Histogram: latency of IO interarrival time in Microseconds (us)
  • Histogram: latency of IO interarrival time for Reads in Microseconds (us)
  • Histogram: latency of IO interarrival time for Writes in Microseconds (us)

 

ResetVscsiStats

This operation will reset the vscsiStats collection similar to the -r option in the vscsiStats command-line. Here is a screenshot of the "reset" operation implemented in the script:

StopVscsiStats 

This operation will stop the vscsiStats collection similar to the -x option in the vscsiStats command-line. Make sure you perform this operation once you are done retrieving your vscsiStats data. Here is a screenshot of the "stop" operation implemented in the script:

In addition to the four operations, you can also save the output to a file by specifying the --output option along with the name of the file. vscsiStats is an extremely useful tool to help vSphere administrators profile their virtual machine's IO workload and now you can easily collect this information using the vSphere API. Some really cool things you can do with this data is to create some nifty graphs such as the ones here and here.