Using the HA Application Monitoring APIs

You can use the HA Application Monitoring SDK to create a stand-alone application monitoring program, or to enhance an existing application or script. The purpose of your application monitoring program determines the API call sequence and the application behavior that you write to handle the response data.

For example, if your application monitoring program is tracking critical applications that are running in a guest OS, your application can intentionally stop sending heartbeat signals if any application-related process fails. The HA monitoring agent interprets the absence of heartbeats as a failure, and resets the virtual machine.

Alternatively, instead of not sending heartbeat signals, your application monitoring program can set the needReset flag using the VMGuestAppMonitor_PostAppState call. When the HA monitoring agent notices this flag, it will reset the virtual machine.

Most of the calls you make using the HA Application Monitoring APIs send information to the virtual infrastructure of the ESXi host, and the host relays the information to the HA monitoring agent. However, the VMGuestAppMonitor_GetAppStatus call is a two-way transaction that lets you request the virtual machine status from the HA monitoring agent.

Most HA Application Monitoring functions lack input parameters, because the calls are local. The vSphere infrastructure passes the heartbeat and status data to and from other levels of the cluster.

Call each function from your application monitoring program. The vSphere infrastructure (in the virtual machine where the application monitoring program is running) passes the function data up to the ESXi host. The local virtual machine sends all status responses to your application monitoring program, even though they are passed down from the HA monitoring agent.

HA Application Monitoring API Functions

The following calls are available to a vSphere HA application monitoring program:

HA Application Monitoring API Calls  

Call Name	Data Type Returned	Description
VMGuestAppMonitor_Enable	char	Requests the virtual machine infrastructure to monitor the calling application. The virtual machine infrastructure returns a value of VMGUESTAPPMONITORLIB_ERROR_SUCCESS, if monitoring was enabled. After your application monitoring program makes this call, your program must call VMGuestAppMonitor_MarkActive() at least once every 30 seconds or the virtual machine infrastructure will change the virtual machine’s status to Red or Gray.
VMGuestAppMonitor_Disable	int	Requests the virtual machine infrastructure to stop monitoring the calling program. The virtual machine infrastructure returns a value of TRUE if monitoring was disabled.
VMGuestAppMonitor_IsEnabled	int	Returns the current recorded state of application monitoring. The virtual machine infrastructure returns a value of TRUE if monitoring is enabled.
VMGuestAppMonitor_MarkActive	char	Sends a request to mark the program as active. This function is also called the heartbeat because your program must call it at least once every 30 seconds while your application monitoring is enabled, or the virtual machine infrastructure will determine that the monitoring has failed.
VMGuestAppMonitor_PostAppState	int	Publish the application state that the guest OS wants delivered to vSphere HA. The application should monitor its environment and update its state accordingly. Heartbeat counting does not need to be enabled as a pre-condition, so the enable() call is not necessary. Returns 0 (zero) on success. The single state parameter passed to this call can be either: ■ OK – The guest's application agent declared state to be normal and no action is required. ■ needReset – The guest's application agent has requested an immediate reset. The guest can request this at any time.
VMGuestAppMonitor_GetAppStatus	char	Returns the current status recorded by the virtual machine infrastructure as ‘Green’, ‘Red’, or ‘Gray’. ■ Green. Virtual machine infrastructure acknowledges that the application is being monitored. ■ Red. Virtual machine infrastructure does not think the application is being monitored. The HA monitoring agent will initialize an asynchronous reset on the virtual machine if the status is Red. ■ Gray. Application should send VMGuestAppMonitor_Enable again, followed by VMGuestAppMonitor_MarkActive, because either application monitoring failed, or the virtual machine was vMotioned to a different location. Use the VMGuestAppMonitor_Free function to free the result. If this call returns a nonerror result that was not anticipated, it can mean that another program in the same virtual machine has called VMGuestAppMonitor_Disable or VMGuestAppMonitor_Enable. If your application is still running, call VMGuestAppMonitor_Enable again, followed by calls to VMGuestAppMonitor_MarkActive.
VMGuestAppMonitor_Free	char	Returns a pointer to the memory to be freed.

Code Sample for appmon.cpp

The HA Application Monitoring SDK includes a code sample called appmon.cpp. The sample is located in the docs/samples directory and defines the entry point for the console application. The appmon.cpp program includes interface code that your application monitoring program can send after receiving results from calls to VMGuestAppMonitor_Enable, VMGuestAppMonitor_MarkActive, and VMGuestAppMonitor_Disable.

Calling the APIs from Your Application

The following steps provide a possible API sequence of calls:

1	Include vmGuestAppMonitorLib.h in the declarations for your C program.

2	To start the monitoring, notify the virtual machine that you are going to start sending a heartbeat signal by calling VMGuestAppMonitor_Enable.

3	After you have called VMGuestAppMonitor_Enable, call VMGuestAppMonitor_MarkActive every 30 seconds or your virtual machine will be reset.

4	Send VMGuestAppMonitor_IsEnabled to make sure the virtual machine infrastructure received your requests correctly and has begun monitoring.

5	Periodically, call VMGuestAppMonitor_GetAppStatus to make sure the vSphere infrastructure is still receiving the heartbeat calls.

The status will be returned as Green, Red, or Gray. See HA Application Monitoring API Calls, for a description of each status value. Heartbeat and Status Signals shows a possible coding flow for the GetAppStatus call.

Coding Flow for VMGuestAppMonitor_GetAppStatus

6	After you call VMGuestAppMonitor_GetAppStatus, call the VMGuestAppMonitor_Free function to free the memory that was used to store the status.

If your application does not free the memory, it can use a large amount of storage very quickly because a new status is created every 30 seconds, when VMGuestAppMonitor_MarkActive is called.

7	Call VMGuestAppMonitor_Disable when you want the agent to stop monitoring.