WilliamLam.com

Where are the "Power" Perf Metrics in the vSphere API?

by // Leave a Comment

A recent question was posed on the VMTN developer forum on how to obtain the new power utilization metrics using the vSphere API. This new performance metric was introduced with the release of vSphere 4.x and can be seen using either esxtop or resxtop and specifying the "p" option for power if you are on an ESX or ESXi host.

You can also get these counters by using the vSphere Client and using the Advanced Charts:

This actually seemed like a simple enough question, pointing the user over to the vSphere API reference documentation under the perfManager. Though after taking a second look, it appears that no such metric exists in the documentation from VMware:

After a few minutes of digging around, I found that Power metrics actually do in fact exists but were not properly documented when they were first introduced. I wrote a quick vSphere SDK for Perl script called perfQuery.pl looking for metrics that were related to "power" and I identified the following:

As you can see these match up to those seen using the vSphere Client and I output the metrics using its rollup type, units, internal name and metric description. While writing this script, I also noticed there were two other performance metric types that existed and were not documented by VMware. Here is a mapping of the API performance metric keys to vSphere API perfManager, the last two including power metric types are undocumented by VMware:

vSphere Client Chart Option vSphere API Perf Metric Key Documented
Cluster Services clusterServices yes
CPU cpu yes
Management Agent managementAgent yes
Memory mem yes
Network net yes
Resource Scheduler rescpu yes
Storage Capacity disk yes
Datastore datastore yes
Disk disk yes
Virtual Disk virtualDisk yes
Storage Adapter storageAdapter yes
Storage Path storagePath yes
System sys yes
Virtual Machine Operations vmop yes
Power power no
vCenter Resources vcResources no
vCenter Debug Info vcDebugInfo no

Using the script and the performance metric key, you can actually query either all or a specific metric type that you are interested in. This is helpful, for those metrics that have not been publicly documented by VMware. However, the power metric should have been documented and I believe this to be a documentation bug that was missed by VMware.

Download: perfQuery.pl

If you are interested in learning more about the vSphere statistics and performance monitoring, I highly recommend checking out Luc Dekens three part series (Part1, Part2 and Part3) on vSphere performance monitoring. Even though his posts are specific to PowerCLI, all the concepts discussed apply to all the vSphere SDKs when dealing with performance monitoring using the vSphere APIs.

vGhetto Tech Exchange VMworld 2010 Video

by // Leave a Comment

Back in September, I presented at my very first VMworld: vGhetto - Communities Building Great Solutions (PPC-07) alongside Edward Haletky at Tech Exchange VMworld 2010. For those that missed the session, the famous Pablo Roesch of VMware has graciously uploaded our presentation to Vimeo 🙂

You can view the presentation here.

vGhetto - Communities Building Great Solutions from heyitspablo on Vimeo.

How to Ack & Reset vCenter Alarm implementing hidden API method

by // 11 Comments

There was a recent question in the VMTN developers forum around automating the acknowledgment and resetting of a triggered vCenter alarm using vSphere SDK for Perl. This is actually a trivial task using the vSphere Client, you would first identify the alarm and acknowledge the alarm by right clicking on the alarm and selecting "Acknowledge Alarm". To reset the alarm, you would right click on the alarm and select "Reset Alarm to Green".

To automate this task using the vSphere SDK for Perl which uses the vSphere API, you would perform the same two API operations. Doing a search, you will find a method called AcknowledgeAarm which should does exactly that, but if you try to search for method to reset an alarm, you will notice no such method exists. This was something I was aware of since vSphere 3.5 API, but never understood why it was kept hidden.

UPDATE - The AcknowledgeAlarm API has been made public as of vSphere 7.x and later

Here is a screenshot of the alarmManager in the vSphere MOB and you will notice no methods pertains to resetting an alarm:

You might ask, how is the vSphere Client performing this operation and what API method is it using? Sadly, this operation is one of the many hidden API methods that VMware choose to hide and not public expose for various reasons.

However, there are several ways of identifying some of these hidden vSphere API methods and properties. When you install the vSphere Client on your workstation, there is a catalog directory (e.g. C:\Program Files\VMware\Infrastructure\Virtual Infrastructure Client\4.1\Catalogs\Default)  that is created based on the version of vSphere and within the vim directory, there are these *.vmsg files that contain information regarding the VIM API (Virtual Infrastructure Management API) and searching within these files, you will find some hidden goodies.

Searching the task.vmsg file and within the alarm section, you will see a method name called setAlarmStatus:

alarm.AlarmManager.setAlarmStatus.label = "Set alarm status"
alarm.AlarmManager.setAlarmStatus.summary = "Sets the status of an alarm for an entity"

As you can see, there are other methods with respect to the alarmManager that is documented, but the method above is not documented in the vSphere API reference. We can take this information and further validate by using the vSphere MOB to see what parameters are required for this method.

By generating the proper URL, you can see the method is exposed and the required parameters to this function:

We can perform one additional confirmation to ensure that the method above is actually the method the vSphere Client is performing when resetting an alarm. The tool that we will use here is Onyx, yep, it is not only useful for PowerCLI but for all vSphere developers and administrators. I created a dummy alarm that would trigger if a VM is powered on or powered off and by running Onyx to capture the API calls when acknowledging and resetting an alarm.

Here is the output from Onyx:

As you can see, the two operations uses the AcknowledgeAlarm and the hidden SetAlarmStatus API method. We now can definitively say that the above hidden API method is being used and now we need to figure out how we can incorporate this method into the existing vSphere SDK for Perl.

In this example, I will be working with the vSphere SDK for Perl found on vMA 4.1, but the same set of changes will apply to vCLI 4.x being installed on a Windows or Linux system. There are two client Perl stubs or Perl Modules that contains prototype and definition of a vSphere API method:

/usr/lib/perl5/5.8.8/VMware/VIM25Stub.pm (prototype definition)
/usr/lib/perl5/5.8.8/VMware/VIM25Runtime.pm (method definition)

We will first edit the VIM25Runtime.pm module and if you are on vMA, you will need to use 'sudo' to edit the file. We will add the SetAlarmStatus entry try similar the AcknowledgeAlarm method:

Next we will edit the VIM25Stub.pm and again it will be very similar to an existing method, but now we must populate the parameters based on what we discovered from the vSphere MOB:

Now we are ready to implement this method in a vSphere SDK for Perl Script. I quickly threw together a script that helps manages your vCenter alarms using the CLI by listing all active and triggered alarms in either a red or yellow state.

Download Script: alarmManagement.pl

Here is an example of listing all triggered alarms that are either in a red or yellow state:

Here is an example of acking and resetting the above alarm and utilizing the new hidden API method that was just implemented:

There you have it, a method that was once hidden is no longer =)

If you are interested in locating other hidden API goodies, take a look at this post on How to browse the internal vSphere APIs