Topics marked with * relate to HQ Enterprise-only features.

Feedback is welcome. Click Add Comment at the bottom of the page.

This page documents Hyperic's vSphere plugin, available in Hyperic 4.4 and later.

vSphere Plugin Overview

Hyperic's vSphere plugin, available starting in Hyperic 4.4, manages vSphere Hosts and the VMs that run on them, using built-in java plugin classes, the HQ API, and the vCenter SDK.  

The vSphere plugin replaces the VMware Infrastructure Manager plugin available in previous versions of Hyperic. The VMware Infrastructure Manager plugin is deprecated in Hyperic 4.4.

Supported Versions and Requirements

The vSphere plugin supports vSphere v4.0 and 4.1, ESX 4.0 and 4.1, and ESXi 4.0 and 4.1 The plugin requires HQ Agent v4.4, and HQ API 3.2, which is bundled with HQ 4.4.

vSphere Resources and the HQ Inventory Model

The vSphere plugin defines three new HQ resource types.

• VMware vCenter — vCenter is the vSphere management service for administering and managing vSphere Hosts and VMs. The vSphere plugin accesses vCenter functions via the vCenter SDK. You install an HQ Agent on the same system as vCenter to enable management of vSphere Hosts and VMs.

• VMware vSphere Host — A vSphere Host is a physical ESX host for VMs. 

• VMware vSphere VM — vSphere VM's run on a vSphere Host. You install an HQ Agent in a vSphere VM to enable management of supported server types (such as Tomcat, JBoss or other supported server types) running in the VM. In HQ Enterprise, if you run an HQ Agent on vCenter and on the VMs that the vCenter instance administers, you can correlate VM and managed server behavior in the HQ Enterprise's HQ vSphere user interface.

The table below shows the vSphere resource type hierarchy; the right column indicates the inventory level for a type in the HQ inventory model.

Note: For more information about how managed resources map to the inventory hierarchy, see HQ Inventory Model.

Configuration Overview

The vSphere plugin makes use of the vCenter SDK to manage the hosts and VMs under vCenter management.

You install an HQ Agent on the platform where the vCenter server runs. The plugin uses SIGAR to discover the vCenter server.

To discover and manage vSphere Hosts and VMs, the plugin must be able to connect to the vCenter SDK port, so after vCenter is discovered, you must enable the plugin to connect to the SDK port by defining the SDK connection settings on the vCenter server's Configuration Properties page.

The plugin tries to connect to the SDK port specified on the vCenter instance's Configuration Properties page. Upon successful connection to vCenter, the HQ Agent reports the vSphere Hosts and VMs under vCenter management to the HQ Server, and starts reporting the availability of the vCenter, the vSphere Hosts it manages, and the VMs in each host.

If an HQ Agent is running in a VM, the agent managing the vCenter service will report all currently enabled metrics for the VM, not just availability.

Resource Types and Management Functions

This section defines the management functions that the vSphere plugin provdies for vCenter, vSphere Hosts, and vSphere VMs.

Management Functions for VMware vCenter

The vSphere plugin uses the vCenter SDK to manage vSphere Hosts and the VMs that run in the hosts. The plugin performs two management functions for vCenter instances:

• Auto-Discovery - The vSphere plugin uses a SIGAR process query to discover a vCenter instance and creates a server of type "VMware vCenter" for it.

• Metric Collection - The plugin reports the vCenter availability, but no other vCenter metrics.

Management Functions for VMware vSphere Hosts

• Auto-Discover New Hosts - After you configure the the VMware vCenter instance's SDK connection information, the vSphere plugin uses the SDK to obtain the location and other properties for each of the physical ESX hosts under vCenter management. The plugin creates a platform of type "VMware vSphere Host" for each.
  • vSphere Host Naming - The name of a vSphere Host in HQ is made up of its name in vCenter, a space, and, enclosed in brackets, its vCenter-assigned UID. For example, the name in HQ for a vSphere Host whose name and UUID in vCenter are "10.16.16.55" and "34313236-3435-5553-4538-30374e39414a", respectively, is:
    10.16.16.55 {34313236-3435-5553-4538-30374e39414a}
  • vSphere Host Properties - The plugin obtains the properties listed below for each vSphere Host. Click the thumbnail below to see the properties as displayed in the HQ user interface when you browse to a VMware vSphere Host.
    • Description
    • VMware Version
    • Build
    • IP Address
    • Primary DNS
    • Secondary DNS
    • Default Gateway
    • Manufacturer
    • Model
    • Processor Type
    • vProcessor Sockets
    • Cores per Socket
    • Data Center
      

• Auto-Discover Changed and Removed Hosts — During each periodic inventory scan, every 15 minutes by default the HQ Agent detects changes to the vSphere Host administered by the vCenter instance it monitors. The following changes are detected and reflected in HQ inventory:
  • Changed properties for vSphere Hosts
  • Removed vSphere Hosts — The plugin detects removal of a host during the inventory scan subsequent to the host's removal from vCenter. As a result, the host and its dependent resources are removed from HQ inventory:
    • The vSphere Host resource is removed from HQ inventory.
    • The vSphere VMs that previously ran in on the host are also removed from HQ inventory.
    • The operating system platforms associated with HQ-managed VMs are removed. (An HQ-managed VM is a VM that has or had an HQ Agent running in it.)

      Warning: Avoid Unexpected Managed Server Deletion In this version of the plugin - 4.4.0 - removing an HQ-managed VM from inventory also causes removal of all managed servers (for example, Tomcat or JBoss) that run in the VM. For more information, see Known Issues in Hyperic Open Source 4.4, in the Hyperic 4.4.0 Release Notes.

• Metric Collection - The org.hyperic.hq.plugin.vsphere.VSphereHostCollector class obtains vCenter Performance Counters for each vSphere host the vCenter Server manages. See VMware vSphere Host Metrics for a list of supported metrics.

• Event Tracking - The org.hyperic.hq.plugin.vsphere.VSphereHostEventPlugin obtains events for vSphere hosts every 5 minutes. See vSphere Events for a list of all vCenter events. For each event, the following data is returned:
  • Log Level
  • Event ID
  • User
  • Message

Management Functions for VMware vSphere VMs

• Auto-Discover VMs - The plugin uses the vCenter SDK to discover VMs that the vCenter Server manages, and creates a platform of type "VMware vSphere VM" for each.
  • vSphere VM Naming - The name of a vSphere VM in HQ is made up of its name in vCenter, a space, and, enclosed in brackets, its vCenter-assigned UID. For example, the name in HQ for a vSphere VM whose name and UUID in vCenter are "vmc-ssrc-centos5.4" and "564d8a4e-3b34-e2ad-e6b5-5807b890bd39", respectively, is:
    vmc-ssrc-centos5.4 {564d8a4e-3b34-e2ad-e6b5-5807b890bd39}
  • vSphere VM Properties The plugin obtains the properties listed below for each VM. Click the thumbnail below to see the properties as displayed in the HQ user interface when you browse to a VMware vSphere VM.
    • Guest OS
    • VM Version
    • IP Address
    • MAC Address
    • Hostname
    • ESX Host
    • Resource Pool
    • Memory Size
    • Virtual CPUs
    • Tools Version
    • Config File
      

• Auto-Discover Changed, Moved, and Removed VMs - - During each periodic inventory scan, every 15 minutes by default, the HQ Agent detects changes to the vSphere VMs administered by the vCenter instance it monitors. The following changes are detected and reflected in HQ inventory:
  • Changed properties for vSphere VMs.
  • Removed vSphere VMs — The plugin detects removal of a VM during the inventory scan subsequent to the host's removal from vCenter. The vSphere Host resource is removed from HQ inventory. Operating system platforms associated with HQ-managed VMs are also removed. (An HQ-managed VM is a VM that has or had an HQ Agent running in it.)

    Warning: Avoid Unexpected Managed Server Deletion In this version of the plugin - 4.4.0 - removing an HQ-managed VM from inventory also causes removal of all managed servers (for example, Tomcat or JBoss) that run in the VM. For more information, see Known Issues in Hyperic Open Source 4.4, in the Hyperic 4.4.0 Release Notes.

  • vMotions - vMotions are detected, and inventory properties updated to reflect the new host without interruption of monitoring.

• Metric Collection - The org.hyperic.hq.plugin.vsphere.VSphereVmCollector class obtains vCenter Performance Counters for each VM with an HQ Agent. See VMware vSphere VM Metrics for a list of supported metrics.

• Control - The org.hyperic.hq.plugin.vsphere.VSphereVmControlPlugin class enables these control actions for VMs with an HQ Agent:
  • CreateSnapshot - Saves a snapshot of the current state of the VM so that you can return to the same state repeatedly.
  • RemoveAllSnapshots - Commits all the immediate snapshots before the "You are here" current active state to the base disk and removes all existing snapshots for the VM.
  • RevertToCurrentSnapshot - equivalent to "go to the parent snapshot of the VM (the parent snapshot of the "You Are Here" position. Revert immediately activates the parent snapshot of the current state of the VM. The current disk and memory states are discarded, and the VM reverts to the disk and memory states of the parent snapshot.
  • Stop - Stop VM.
  • Start - Start VM.
  • Reset - Resets the VM abruptly, with no consideration for work in progress. If you reset a VM while the virtual disk is being written to, data may be lost or corrupted.
  • Suspend - stops the VM and saves the current state of the VM state and applications running in it; the next resume command returns the VMs and applications to the state they were in when suspend.
  • RebootGuest - Issues a command to the guest operating system asking it to perform a reboot.
  • GuestHeartbeatStatus - The guest heartbeat status, one of:
    • gray - VMware Tools are not installed or not running.
    • red - No heartbeat. Guest operating system may have stopped responding.
    • yellow - Intermittent heartbeat. May be due to guest load.
    • green - Guest operating system is responding normally.

• Event Tracking - The org.hyperic.hq.plugin.vsphere.VSphereVmEventPlugin class obtains events (for VMs that have an HQ Agent) using the vCenter SDK, in accordance with the log tracking options configured for vSphere VMs. If log tracking is enabled, an event will be logged for any control action performed. In addition, vCenter events that meet the log tracking filter criteria will be tracked. (See vSphere Events for a list of all vCenter events.) For each event, the following data is logged:
  • Log Level
  • Event ID
  • User
  • Message

Licensing Considerations

vSphere Hosts and vSphere VMs are platform types, so each vSphere Host and vSphere VM running an HQ Agent counts as a managed platform, and consumes an HQ license. A vSphere VM without an HQ Agent installed in it does not consume a license.

vSphere Components in the Hyperic User Interface

This section introduces the user interface for viewing vSphere resources in Hyperic. In Hyperic Open Source, you use the Resource Hub to view vSphere resources.

Hyperic Enterprise has a separate management view — the HQ vSphere page — for monitoring and managing vSphere components.

vSphere Components in the Resource Hub

Follow the instructions in this section to view vSphere components in the Resource Hub.

View a VMware vCenter Instance in the Resource Hub

Use Resources > Browse > Servers > VMware vCenter to navigate to VMware vCenter instance. The Current Health page for the vCenter instance appears. See the thumbnail below for a screenshot.

View a VMware vSphere Host in the Resource Hub

Use Resources > Browse > Platforms > vSphere Host to navigate to a vSphere Host. The Current Health page for the host. See the thumbnail below for a screenshot.

View a VMware vSphere VM in the Resource Hub

Use Resources > Browse > Platforms > vSphere VM to navigate to a vSphere VM. The Current Health page for the VM. See the thumbnail below for a screenshot.

When you browse platforms on the Resources > Browse page, if the filter is set to "All Platform Types", vSphere VMs will not appear in the list of platforms. You must select "vSphere VM" in the platform types filter to display a list of vSphere VMs in the Resource Hub.

vSphere Components in Hyperic Enterprise

Use Resources > Browse > HQ vSphere to display the HQ vSphere management interface. For more information, see ui-vSphere.

Configuration Instructions

This section has instructions for enabling the vSphere plugin to manage vSphere Hosts and VMs.

Remove VMware Infrastructure Manager Plugin and Resources If you currently have pre-4.4 HQ Agents monitoring vSphere components with the VMware Infrastructure Manager plugin deprecated in Hyperic 4.4, remove the plugin and VI3 resources from inventory. The resource types are: VMware VI3 VM server VMware VI3 Host platform VMware VI3 Resource Pool server VMware VI3 VM CPU service VMware VI3 VM NIC service

Step 1: Install HQ Agent on vCenter Platform

Install an HQ Agent on the platform where vCenter Server runs. For instructions, see Installing an Agent-Only Package

Interactive Agent Configuration is Not Supported You must configure the HQ Agent in its properties file. Do not start the HQ Agent until you have configured its startup setting in its agent.properties file, as described in the following section.

Step 2: Configure Agent Setup Properties File

The vSphere plugin reads the agent.properties file for the HQ Agent on the platform where vCenter server is installed to get the connection properties the HQ Agent and HQ Server use to communicate with one another. You must edit the agent.properties file to supply the connection property values.

Edit the following lines in agent.properties to supply the correct values for your environment, and then restart the HQ Agent. For more information, see about agent startup settings, see Configure Agent - Server Communication in Properties File.

After restart, the HQ Agent should discover the vCenter server and present it in the Auto-Discovery Portlet on the HQ Dashboard. Import the discovered vCenter server to inventory.

Step 3: Configure vCenter Server Access Credentials

1. Navigate to the  Configuration Properties page for the VMware vCenter instance.
   
2. Enter the vCenter SDK URL, supplying an URL with a fully-qualified domain name or an IP address.

   vCenter URLs must be unique Due to a known problem (https://jira.hyperic.com/browse/HQ-2418), each vCenter Server resource managed by Hyperic must be configured with a unique URL. If multiple vCenter Server resources are defined with the same URL, for instance the default http://localhost/sdk all discovered Hosts and VMs will appear under one of the vCenter Server instances.

3. Enter the username and password for connecting to vCenter.
   • vSphere Hosts and VMs are automatically imported into inventory. They do not appear in the Auto-Discovery Portlet on the HQ Dashboard.
   • Only VMs that are powered on and have a MAC address will be discovered
4. Soon, metrics should appear on the Monitor tab for a vSphere resource.

Solving Problems If the agent does not start to report metrics for vSphere Hosts and VMs: Verify that you have correctly specified the vCenter SDK URL, using a fully-qualified domain name or an IP address. Because HQ can monitor multiple vCenter servers, the vCenter SDK URL for each must be unambiguous; if you use localhost when configuring the SDK URLs (rather than an FQDN or IP address), the various vCenter SDK URLs will be non-unique, resulting in erroneous vCenter > Host > VM hierarchies. Verify that the Username and Password you configured are valid credentials for access the SDK. Verify that the HQ Agent has network connectivity and can reach the API port on the platform where vCenter runs — check to see if it is blocked by a firewall.

Step 4: Set Event Tracking Options

You can enable log tracking for vSphere Hosts and VMs. If you do, the agent will log an event for vCenter events that match the criteria you specify. Note that if you enable log tracking for vSphere VMs, HQ will log an event for each control action command performed on the VM from HQ. If log tracking is not enabled for a VM, control actions will not be tracked as events.

Note: This version of the vSphere plugin returns all events as level INFO. You cannot define filter criteria based on severity level in this version of the vSphere plugin. You can only filter based on message content - you can track events based on whether it matches or does not match a regular repression. See vSphere Events for a list of all vCenter events.

To enable log tracking, click the Enable Log Tracking box in the Monitoring section of the Configuration Properties page.

For information about HQ log tracking functionality and configuration options, and how to view log events, see Log Tracking.

Step 5: Configure vCenter Statistics Level

The metrics the plugin can collect is limited by the the value of vCenter's Statistics Level setting, which by default is level 1. Level 1 provides only basic performance information. To enable additional metrics, you may wish to increase the Statistics Level setting.

vCenter Statistics Levels When changing the level of vCenter statistic to collect, consider the overhead that detailed statistics impose on vCenter and vSphere Hosts. Level 1 has very low overhead on VirtualCenter server and ESXhosts. Levels 2 – 4 have only slightly greater overhead on ESX, but can adversely impact VirtualCenter performance if there are more than 10 ESX Server hosts. Level 4 can quickly fill the VirtualCenter database, so it should only be turned on for limited periods of time. For more information, see Collection Levels in vSphere Basic System Administration.

Step 6: Tailor Plugin Monitoring Defaults

You can enable and disable metrics, select indicator metrics, and change the collection interval for a resource type on its Monitoring Defaults page. To navigate to a resource type's Monitoring Defaults page:

1. Click the Administration tab.
2. Click Monitoring Defaults.
3. Scroll down to the resource type and click Edit Metric Template.
   • Click the thumbnails below to view the Monitoring Defaults pages for vSphere Hosts and VMs.
     
     

Step 7: Install HQ Agents in VMs

Installing an HQ Agent in each VM enables you to manage HQ-supported server types running in it.  In HQ Enterprise, this enables you to correlate the behavior of resources throughout the managed resource hierarchy - from vCenter to managed servers in the VM.  

For installation instructions, see Installing an Agent-Only Package.

Note: If you run an HQ Agent in a VM, HQ creates an operating system type platform type for it in inventory. For instance, if you run and agent in a VM running Linux, HQ creates a platform of type "Linux" for the system, in addition to the platform of type "vSphere VM" create for the VM itself.

Step 8: Configure Alert Definitions

Create alert definitions as desired for your managed vSphere components.

About Alert Processing for vSphere Resources If a VM has an agent running in it, If a VM is suspended or powered off, “down” alerts on the “associated platform” (the platform that is represented in HQ when you install an agent on the VM) will not fire.

Metric Documentation

The following sections define the metrics available

VMware vSphere Host Metrics

VMware vSphere VM Metrics