Cloud Hub Configuration

h6. Content

To configure the Cloud Hub perform the following steps:
# Log in to GroundWork Monitor as an *Administrator*.
# Select *GroundWork Administration* > *GroundWork Cloud Hub*. The *Cloud Hub Configuration Wizard* screen will be displayed where you can add and configure the Cloud Hub for VMware, OpenStack, or Red Hat virtual environments. For each of the current connections you can; view the status, modify the parameters, or choose to remove a connection. You will need your GroundWork Server and Virtual Environment connection parameters handy.
# To create a new connection select the radio button for *VMware* , *OpenStack*, or *Red Hat*, and then click *Add*.
\\
\\
Figure: Cloud Hub Configuration Wizard
!cloudhub_3.jpg!
# Enter the GroundWork Server values:
#* *Display Name*:  This is the configuration server display name, (e.g., ESX-Corporate).
#* *GroundWork Server Name* \- You will need to enter the name of the GroundWork server that will integrate the Cloud Hub messages. If the Cloud Hub is running on the same server as the portal, the name can be {{{*}localhost{*}}} or as preferred, the server name.
#* *Is SSL enabled on GroundWork Server?* \- Check this box if the GroundWork server is configured for secure HTTPS.
#* *GroundWork WebServices Username* and *GroundWork WebServices Password* \- This is the user and password configured to access the Web Service API. The default user is {{{*}wsuser{*}}}. These are the same credentials set in {{/usr/local/groundwork/config/ws_client.properties}}.{Note}
Important for LDAP enabled systems: Make sure that it matches with the entry in the {{ws_client.properties}} file and the user is member of the Authenticated group and the WSUser (or GWUser) group in LDAP.
{Note}Figure: GroundWork Server Values 
\\ !cloudhub_4.jpg|border=1!
# Continue with the specific connection's configuration credentials for *VMware, OpenStack* or *Red Hat* including which views are to be displayed.
# Click *Save* and then *Test Connection* to check if the virtual instance is accessible with the given credentials.
# After a successful validation, click  *Next* to select the *Metrics* be monitored. The metrics screen allows you to define if a metric should be monitored and graphed, and lets you set the values for Warning and Critical thresholds. It is recommended to use the synthetic metrics (computed percentages) since it helps to define the threshold values in a 0-100% range. *Save* any changes. {note}Thresholds cannot be set for the OpenStack Cloud Hub connection in the GroundWork Monitor version 7.0.2.{note}
# After saving the settings, return to the *Home* page to *START* the connection. Monitoring will start immediately synchronizing all Hypervisors and Guests found in the Management server or Hypervisor with the GroundWork server. The monitoring can be adjusted by returning to the Cloud Hub configuration screen and modifying metrics collected (check/un-check) or modifying threshold values.

h4. 2.0 Metrics to be Monitored for VMware

The VMware API (application programming interface) defines a set of metrics (measurements regarding performance, resource utilization, bandwidth) that apply to hypervisors (physical machines), hosts (virtual machines), networks and datastores (disk partitions). The metrics gathered by Cloud Hub are of two kinds: *native* and *synthetic*. The strings that define the native metrics are exactly those supported by the VMware API, with certain restrictions, namely that the list must be from those metrics that result in values, and not lists of objects. The majority of the metrics are numeric in nature - amounts of "MHz" (megahertz, in VMware parlance), amounts of memory (bytes, megabytes), amounts of disk space (bytes, megabytes, gigabytes). Again, they are taken in their native form, neither normalized nor adjusted.

The *native metrics* lack a sense of normalization, as an example a host (VM/virtual machine) may have a metric for CPU utilization of "273". The _?VMware_ documentation indicates that this value is in MHz (megahertz). However, in ferreting out system issues, it is often more useful to know what proportion of the total resource in question is in use. In other words, "273 of what?"

The *synthetic metrics* are pairs of native metrics, cast into _percentage-of-total_ form. The numerator (number "on top") is a performance metric, and the denominator (divisor "on the bottom") is the "sum of, or size of a resource". Synthetic metrics can be extremely helpful in deciphering performance and accessibility issues in real-time. The percentages are bounded in the \[0..100\] range, and they include the "%" character at the end.

h5. 2.1 Synthetic Performance and Resource Utilization Statistics

The following table lists the _synthetic metrics_ that are supported at present in the VEMA _Cloud Hub_ performance monitoring API. As a reminder - these are all +percentages+ in the range of \[0..100\]. The metrics marked as _critical_ are necessary for the general operation of the API, and should not be removed.
|| Statistic Accessor String || Notes and Comments || Host || VM || Critical ||
| syn.host.cpu.unused | % of CPU that is +un{+}used | Y | | |
| syn.host.cpu.used | % of CPU that is in use | Y | | |
| syn.host.mem.unused | % of memory that is +un{+}used | Y | | |
| syn.host.mem.used | % of memory that is in use | Y | | |
| syn.vm.cpu.cpuToMax.unused | Similar to above, but for VMs | | Y | Y |
| syn.vm.cpu.cpuToMax.used | Similar to above, but for VMs | | Y | |
| syn.vm.mem.balloonToConfigMemSize.unused | These compare the \[balloonMemory\] statistics against the \[totalMemory\] of the virtual machine. \\
Again, represented as a PERCENTAGE between 0-100. | | Y | Y |
| syn.vm.mem.balloonToConfigMemSize.used | Used quantity compared to total | | Y | |
| syn.vm.mem.compressedToConfigMemSize.unused | \[compressedMemory\] compared to \[totalMemory\] -- amount unused | | Y | Y |
| syn.vm.mem.compressedToConfigMemSize.used | \[compressedMemory\] compared to \[totalMemory\] -- amount in use | | Y | |
| syn.vm.mem.guestToConfigMemSize.unused | \[guestMemory\] ... to \[totalMemory\] | | Y | Y |
| syn.vm.mem.guestToConfigMemSize.used | \[guestMemory\] ... to \[totalMemory\] | | Y | |
| syn.vm.mem.sharedToConfigMemSize.unused | \[sharedMemory\] ... to \[totalMemory\] | | Y | Y |
| syn.vm.mem.sharedToConfigMemSize.used | \[sharedMemory\] ... to \[totalMemory\] | | Y | |
| syn.vm.mem.swappedToConfigMemSize.unused | \[swappedMemory\] ... to \[totalMemory\] | | Y | Y |
| syn.vm.mem.swappedToConfigMemSize.used | \[swappedMemory\] ... to \[totalMemory\] | | Y | |

h5. 2.2 Native Metrics

At a high level the following _VMware_ metrics are supported. Some are _required for use within the module_ to compute either synthetic statistics, or, for populating key operational access fields (such as IP address, MAC address) and cannot be excluded. The following table documents known metric accessor strings that are known as accessible in the _Cloud Hub_ system. Those marked "critical" cannot be excluded from collection, as they figure critically into other components of the auto-configuration and data gathering supported by the VEMA API.
|| Statistic Accessor String || Notes and Comments || Host || VM || Critical ||
| summary.config.memorySizeMB | e.g. 4092 | | Y | |
| summary.config.name | e.g. VM-1234 | | Y | |
| summary.config.numCpu | e.g. 2 | | Y | |
| summary.config.numEthernetCards | e.g. 2 | | Y | |
| summary.config.numVirtualDisks | e.g. 3 | | Y | |
| summary.guest.hostName | e.g. www-dev-platform-3 | | Y | Y |
| summary.guest.ipAddress | e.g. 123.45.74.103 | | Y | Y |
| summary.hardware.cpuMhz | e.g. 3102 | Y | | Y |
| summary.hardware.memorySize | e.g. 16400 (could be long bytes tho') | Y | | Y |
| summary.hardware.model | e.g. “Dell PowerEdge 192B” | Y | | Y |
| summary.hardware.numCpuCores | e.g. 2 | Y | | |
| summary.hardware.numCpuPkgs | e.g. 2 | Y | | |
| summary.hardware.numCpuThreads | e.g. 8 | Y | | |
| summary.hardware.vendor | e.g. “Dell” | Y | | |
| summary.quickStats.balloonedMemory | See VMWARE documentation. Important | | Y | |
| summary.quickStats.compressedMemory | See VMWARE documentation. Important | | Y | |
| summary.quickStats.consumedOverheadMemory | See VMWARE documentation. Important | | Y | |
| summary.quickStats.guestMemoryUsage | See VMWARE documentation. Important | | Y | |
| summary.quickStats.hostMemoryUsage | See VMWARE documentation. Important | | Y | |
| summary.quickStats.overallCpuDemand | See VMWARE documentation. Important | | Y | |
| summary.quickStats.overallCpuUsage | See VMWARE documentation. Important | Y | Y | Y |
| summary.quickStats.overallMemoryUsage | See VMWARE documentation. Important | Y | | Y |
| summary.quickStats.privateMemory | See VMWARE documentation. Important | | Y | |
| summary.quickStats.sharedMemory | See VMWARE documentation. Important | | Y | |
| summary.quickStats.ssdSwappedMemory | See VMWARE documentation. Important | | Y | Y |
| summary.quickStats.swappedMemory | See VMWARE documentation. Important | | Y | |
| summary.quickStats.uptime | Uptime in seconds | Y | | Y |
| summary.quickStats.uptimeSeconds | Uptime in seconds | | Y | |
| summary.runtime.bootTime | ... since boot time | Y | Y | Y |
| summary.runtime.connectionState | See VMWARE documentation. Important | Y | Y | |
| summary.runtime.host | VMware name of host e.g. HOST-1234 | | Y | |
| summary.runtime.maxCpuUsage | e.g. 175 | | Y | |
| summary.runtime.maxMemoryUsage | e.g. 2021 | | Y | |
| summary.runtime.memoryOverhead | See VMWARE documentation. Important | | Y | |
| summary.runtime.powerState | e.g. POWERED_ON / POWERED_OFF | Y | Y | Y |
| summary.storage.committed | e.g. 17300000000 | | Y | |
| summary.storage.uncommitted | e.g. 12000000000 | | Y | |
\\
The Cloud Hub data acquisition subsystem actually supports all numeric metrics that are accessible through the VMware API. As an example, we have tested the following metric strings and found them to work. They are _not_ included in the configuration page XML file though, so they don't show up for configuration.
\\

|| Statistic Accessor String || Notes and Comments || Host || VM || Critical ||
| guest.guestState | Up, down | | Y | |
| guest.hostName | Coded as \[host-1234\] | | Y | Y |
| guest.ipAddress | First IP address, if multiple | | Y | |
| guest.net | Complex object, not directly useful | | Y | |
| hardware.cpuInfo.hz | e.g. 3143234432 | Y | | |
| hardware.cpuInfo.numCpuThreads | e.g. 8 | Y | | |
| hardware.memorySize | e.g. 16342123000 | Y | | |
| hardware.systemInfo.model | e.g. “Dell PowerEdge 192B” | Y | | |
| hardware.systemInfo.vendor | e.g. “Dell” | Y | | |
| name | Name of the entity, in VMware format. | Y | Y | |
| runtime.powerState | e.g. POWERED_ON / POWERED_OFF | Y | | |
| vm | | Y | | Y |

h4. 3.0 Monitoring Profiles for Virtual Environments

The master monitoring profiles for virtual environments are stored on the GroundWork server. Each time the user goes into the configuration screens for Cloud Hub the monitoring profile from the GroundWork server would be loaded into the Cloud Hub. This allows to you to manage and maintain the monitoring profiles for Cloud Hub in a central location.

The location for Cloud Hub monitoring profiles is:
{code}/usr/local/groundwork/core/vema/profiles/{code}
* The name of the VMware monitoring profile is:
{code}vmware_monitoring_profile.xml{code}
* The name of the Red Hat monitoring profile is:
{code}rhev_monitoring_profile.xml{code}

If you wish, you may carefully edit the profiles to include additional numeric metrics.{note}PLEASE test immediately - any metric test that is slightly misspelled or otherwise rejected by the API short-circuits ALL the metrics from reporting, silently and without raising flags. In general, we can't recommend adding additional numeric metrics as at the time of this writing all the useful ones have been included as part of the release XML file contents.{note}