WilliamLam.com

  • About
    • About
    • Privacy
  • VMware Cloud Foundation
  • VKS
  • Homelab
    • Resources
    • Nested Virtualization
  • VMware Nostalgia
  • Apple

Retrieving vscsiStats Using the vSphere 5.1 API

01.17.2013 by William Lam // 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.

Categories // Automation Tags // api, ESXi 5.1, service manager, simplecommand, vscsiStats, vSphere 5.1, vsphere sdk for perl

Retrieving ESXTOP Performance Data Using the vSphere 5.1 API

01.15.2013 by William Lam // 5 Comments

In vSphere 5.1, VMware introduced a new managed object called the Service Manager. The Service Manager is a generic object that wraps the execution of a single command and it requires a specific set of inputs to invoke a particular service command. This is particularly interesting as it allows users to access both the ESXTOP and vscsiStatsinterface using the vSphere API. Prior to vSphere 5.1, to use ESXTOP you would need to either login to the ESXi Shell to run the local ESXTOP command or connect remotely using the RESXTOP utility which is only available on a Linux system. For vScsiStats, you would need to login to the ESXi Shell as a remote version of this tool does not exist. The Service Manager used to be a private interface, an interesting tidbit is that some of you may have already interacted with this interface without even realizing it if you have used PowerCLI's Get-Esxtop cmdlet. In this article I will show you how to programmatically access ESXTOP using the vSphere API.

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.

Both the ESXTOP and vscsiStats services are only available when connecting directly to an ESXi 5.1 host, it is not available when connecting to a vCenter Server. If we browse over to the vSphere MOB, we can clearly see the two services:

The first step is to get a reference to the ESXTOP service via the Service Manager and to invoke an operation for ESXTOP, you will need to use the ExecuteSimpleCommand. For ESXTOP, there are three valid operations:

  • CounterInfo
  • FetchStats
  • FreeStats

To demonstrate the ESXTOP interface, I have written a sample vSphere SDK for Perl script called getEsxtop.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.

CounterInfo

This operation only needs to be invoked once and it will provide you with the list of available counters and their associated properties and data types for a given ESXi host. Here is an example of this using the "getcounters" operation implemented in the script:

Each line represents a specific counter type followed by each property name and their data type. For example, the first line is for the Server counter and has the following properties and types:

Property Name Type
MinFetchIntervalInUsec U64
IsVMVisor B
TimeStampInUsec U64
Time S64

Here is a quick diagram to help you visualize the hierarchy of all the ESXTOP counters and their relationships with one another:

Note: This diagram was created using yuml.me and here is the raw text in JSON format if you are interested.

FetchStats

This operation fetches a single snapshot of ALL the ESXTOP statistics which contains two pieces of information:

  • The topology of the counter instances
  • The actual counter instances values

The first section is denoted by ==NUM-OF-OBJECTS== which contains either inventory data that does not change or counter instance structure which describes the relationship between the different counter instances. Here is an example of the first section using the "getstats" operation implemented in the script:

If we take a look at the second line as an example |PCPU|LCPU,24|Core,12|Package,2| we can see that PCPU counter contains 24 LCPU that you would need to then enumerate as well as inventory information describing the CPU's logical cores and physical socket.

To view the enumerated counter instances and their instance values, we need to look in the second portion of the data which is denoted by ==COUNTER-VALUE== within the output. Here is a screenshot of this section and we can see the enumerated LCPU's (24 in total as denoted earlier) and their associated instance values:

Remember you will need to correlate with the counter definitions that was extracted earlier from the "getcounters" and this will help you build up the data. I do have to say it can be a bit confusing when you first look at the raw data, but as you start to play with it a bit more, it will start to make sense. Two useful references that can help with parsing the data is the ESXTOP bible and an article that Luc Dekens wrote awhile back exploring the Get-Esxtop cmdlet which I mentioned earlier leverages this exact interface.

FreeStats

Lastly, once you are done collecting the ESXTOP data, you will need to run the "freestats" operation and this will release any server side resources used during the collection. When this command is invoked, it will free up all resources even for past collections where you might have forgotten to perform this last step. There is no output from this operation as you can see from the example screenshot below:

Even though it is nice to see the ESXTOP interface be accessible via the vSphere API, it is not the easiest interface to use and is definitely geared more towards a developer. For extracting general performance data, I would still recommend using the Performance Manager managed object or one of the above mentioned command-line interfaces. In the next article, I go into more detail about the vscsiStats interface and how to consume it using the vSphere API.

Categories // Automation Tags // api, ESXi 5.1, esxtop, resxtop, service manager, simplecommand, vSphere 5.1, vsphere sdk for perl

Search

Thank Author

Author

William is Distinguished Platform Engineering Architect in the VMware Cloud Foundation (VCF) Division at Broadcom. His primary focus is helping customers and partners build, run and operate a modern Private Cloud using the VMware Cloud Foundation (VCF) platform.

Connect

  • Bluesky
  • Email
  • GitHub
  • LinkedIn
  • Mastodon
  • Reddit
  • RSS
  • Twitter
  • Vimeo

Recent

  • Programmatically accessing the Broadcom Compatibility Guide (BCG) 05/06/2025
  • Quick Tip - Validating Broadcom Download Token  05/01/2025
  • Supported chipsets for the USB Network Native Driver for ESXi Fling 04/23/2025
  • vCenter Identity Federation with Authelia 04/16/2025
  • vCenter Server Identity Federation with Kanidm 04/10/2025

Advertisment

Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Cookie Policy

Copyright WilliamLam.com © 2025