Example usage of vPoller¶
This page provides some examples how vPoller can be used to perform various operations like discovery and polling of VMware vSphere objects.
Please also refer to the Supported methods by vPoller documentation for the full list of supported vPoller methods you could use.
The property names which we use in these examples can be found in the official VMware vSphere API documentation.
Each vSphere managed object has specific properties, which are documented in the official documentation.
The examples here serve for demonstration purpose only and do not provide all the properties you could use and get from vSphere objects, so make sure to refer to the official vSphere documentation when looking for a specific property name.
There are also a number of posts about how vPoller is being used for various purposes, which you could also read at the following links:
- VMware vSphere CLI tips & tricks with vPoller
- VMware monitoring with Zabbix, Python & vPoller
- Exporting Data From a VMware vSphere Environment For Fun And Profit
Getting vSphere “about” info¶
Using the about
vPoller method you can retrieve information about
your vSphere host such as API version, vendor, build number, etc.
Here is an example of using the vPoller about
method:
$ vpoller-client --method about --vsphere-host vc01.example.org \
--method about --properties version,fullName,apiVersion,vendor
Datacenter examples¶
Here is how to discover all Datacenter
objects from your vSphere
environment:
$ vpoller-client --method datacenter.discover --vsphere-host vc01.example.org
An example command that would get the summary.overallStatus
property of a specific Datacenter
:
$ vpoller-client --method datacenter.get --vsphere-host vc01.example.org \
--name datacenter01 --properties name,overallStatus
ClusterComputeResource examples¶
A ClusterComputeResource
managed object is what you are used to
refer to simply as cluster
in vSphere. The examples commands below
show how to discover and get properties for your vSphere clusters.
An example command to discover all ClusterComputeResource
managed objects from your vSphere environment:
$ vpoller-client --method cluster.discover --vsphere-host vc01.example.org
And here is how to get the overallStatus
property for a specific
ClusterComputeResource
managed object:
$ vpoller-client --method cluster.get --vsphere-host vc01.example.org \
--name cluster01 --properties name,overallStatus
HostSystem examples¶
HostSystem
managed objects in vSphere are your ESXi hosts.
Here is an example how to discover all your ESXi hosts from your vSphere environment:
$ vpoller-client --method host.discover --vsphere-host vc01.example.org
And here is an example command to get the runtime.powerState
property for a specific HostSystem
object:
$ vpoller-client --method host.get --vsphere-host vc01.example.org \
--name esxi01.example.org --properties runtime.powerState
An example command to get all Virtual Machines registered on a specific ESXi host:
$ vpoller-client --method host.vm.get --vsphere-host vc01.example.org \
--name esxi01.example.org
Here is how you can get all datastores used by a specific ESXi host:
$ vpoller-client --method host.datastore.get --vsphere-host vc01.example.org \
--name esxi01.example.org
VirtualMachine examples¶
An example command to discover all VirtualMachine
managed
objects from your vSphere environment:
$ vpoller-client --method vm.discover --vsphere-host vc01.example.org
Another example showing how to get the runtime.powerState
property of a Virtual Machine:
$ vpoller-client --method vm.get --vsphere-host vc01.example.org \
--name vm01.example.org --properties runtime.powerState
This is how you could discover all disks in a Virtual Machine. Note, that this method requires that you have VMware Tools installed and running on the target Virtual Machine:
$ vpoller-client --method vm.disk.discover --vsphere-host vc01.example.org \
--name vm01.example.org
If you want to get information about a disk in a Virtual Machine you
could use the vm.disk.get
vPoller method. This is how to get the
freeSpace
property for a Virtual Machine disk:
$ vpoller-client --method vm.disk.get --vsphere-host vc01.example.org \
--name vm01.example.org --properties freeSpace --key /var
In order to find out the host on which a specific Virtual Machine is
running on you could use the vm.host.get
vPoller method:
$ vpoller-client --method vm.host.get --vsphere-host vc01.example.org \
--name vm01.example.org
The example below shows how to retrieve information about the network that a Virtual Machine is using along with information about it’s IP address and MAC address:
$ vpoller-client --method vm.guest.net.get --vsphere-host vc01.example.org \
--name vm01.example.org --properties network,ipAddress,macAddress
If you want to see which datastores your Virtual Machine is using you
can use the vm.datastore.get
vPoller method, e.g.:
$ vpoller-client --method vm.datastore.get --vsphere-host vc01.example.org \
--name vm01.example.org
Using the vm.process.get
vPoller method we can get a list of all
processes running in a Virtual Machine. Note, that we need to supply a
username and password when using the vm.process.get
method, which
are used for authentication in the guest system.
$ vpoller-client --method vm.process.get --vsphere-host vc01.example.org \
--name vm01.example.org --properties name,owner,pid,cmdLine \
--guest-username root --guest-password p4ssw0rd
Note
The above example command uses the root
user for authentication
in the guest system. It is recommended that you use a user
with restricted privileges when using the vm.process.get
vPoller method if security is a concern.
Datastore examples¶
Here is an example command which will discover all Datastore
managed objects from your vSphere environment:
$ vpoller-client --method datastore.discover --vsphere-host vc01.example.org
This example command below would return the summary.capacity
property for a specific Datastore
object.
$ vpoller-client --method datastore.get --vsphere-host vc01.example.org \
-name ds:///vmfs/volumes/5190e2a7-d2b7c58e-b1e2-90b11c29079d/ \
--properties summary.capacity
This example command will give you all hosts, which are using a
specific Datastore
.
$ vpoller-client --method datastore.host.get --vsphere-host vc01.example.org \
--name ds:///vmfs/volumes/5190e2a7-d2b7c58e-b1e2-90b11c29079d/
Viewing established Sessions¶
vPoller can also be used for viewing the established sessions to your vSphere hosts.
Note
Viewing vSphere sessions by unauthorized parties may be considered as a security hole, as it may provide an attacker with information such as Session IDs, which could be used for spoofing a user’s session.
If security is a concern make sure that your vSphere Agents
are
configured to use an account with restricted set of privileges,
which cannot view the established vSphere sessions.
Here is an example command that will return the established sessions for your vSphere host:
$ vpoller-client --method session.get --vsphere-host vc01.example.org
Getting vSphere Events¶
With vPoller you can also retrieve vSphere events.
This is how you can retrieve the last registered event from your vSphere host:
$ vpoller-client --method event.latest --vsphere-host vc01.example.org
Getting vSphere Alarms¶
Using the *.alarm.get
vPoller methods we can retrieve the
triggered vSphere alarms on a Datacenter
,
ClusterComputeResource
, HostSystem
, VirtualMachine
and
Datastore
level.
Here is how you could retrieve all triggered alarms for a Datacenter
.
$ vpoller-client --method datacenter.alarm.get --vsphere-host vc01.example.org \
--name MyDatacenter
An here is an example result from the above command, showing the triggered alarms for our Datacenter.
{
"success": 0,
"result": [
{
"overallStatus": "red",
"time": "2015-02-13 09:16:50.916096+00:00",
"key": "alarm-4.host-30",
"entity": "esxi01.example.org",
"acknowledged": false,
"acknowledgedByUser": null,
"info": "Host memory usage"
}
],
"msg": "Successfully retrieved alarms"
}
Performance metrics¶
Note
If you are running a vSphere 6.0 environment and experience issues with real-time performance metrics, make sure to check [KB-2119264](http://kb.vmware.com/kb/2119264) for more details.
Using vPoller you can retrieve various performance metrics from your VMware vSphere environment.
In the following examples we will see how we can use vPoller in order to discover the supported performance metrics in our vSphere environment and also how to retrieve real-time and historical statistics from different performance providers - ESXi hosts, Virtual Machines, Datastores, Clusters, etc.
For more information about the performance metrics in a VMware vSphere environment, please make sure to check the VMware vSphere API documentation and especially the PerformanceManager documentation where you can find information about the supported performance counters, the existing counter groups, description of each counter, etc.
First, let’s see how to obtain all performance counters that are
supported in our vSphere environment. Using the perf.metric.info
vPoller method we can retrieve a list of all supported performance
counters from our vSphere environment.
$ vpoller-client --method perf.metric.info --vsphere-host vc01.example.org
The result of the above command should contain all performance metrics
which are supported on the VMware vSphere host vc01.example.org
.
Below is an example of a single counter as returned from the
perf.metric.info
vPoller method.
{
"perDeviceLevel": 3,
"level": 1,
"key": 143,
"nameInfo": {
"label": "Usage",
"key": "usage",
"summary": "Network utilization (combined transmit-rates and receive-rates) during the interval"
},
"groupInfo": {
"label": "Network",
"key": "net",
"summary": "Network"
},
"unitInfo": {
"label": "KBps",
"key": "kiloBytesPerSecond",
"summary": "Kilobytes per second"
},
"statsType": "rate",
"rollupType": "average"
}
You can find a sample file with all performance metrics as discovered on a VMware vSphere host in the perf-metric-info.json example file.
In order to obtain information about the supported performance metrics
for a specific performance provider (e.g. ESXi host, Virtual Machine,
Datastore, etc.) you can use the respective *.perf.metric.info
vPoller methods, e.g. vm.perf.metric.info
, host.perf.metric.info
,
etc.
The following example shows how to get the available performance metrics for a Virtual Machine:
$ vpoller-client --method vm.perf.metric.info --vsphere-host vc01.example.org \
--name vm01.example.org
You can see an example result of using the vm.perf.metric.info
method in the vm-perf-metric-info.json example file, which shows the
available performance metrics for a specific Virtual Machine.
In the vm-perf-metric-info.json example file you will see
that each discovered performance metric has a counterId
and
instance
attribute, e.g.:
{
"counterId": "net.usage.kiloBytesPerSecond.average",
"instance": "vmnic0"
}
The counterId
part from the above example counter is comprised of
the <groupInfo.key>.<nameInfo.key>.<unitInfo.key>.<rollupType>
attributes from our counter as discovered by the perf.metric.info
vPoller method.
We can also request specific counters only when using the
*.perf.metric.info
methods. For example if we are only interested
in the net.usage.kiloBytesPerSecond.average
counter, then we would
execute this command instead, which would return all counters and
their instances for our performance provider:
$ vpoller-client --method vm.perf.metric.info --vsphere-host vc01.example.org \
--name vm01.example.org --counter net.usage.kiloBytesPerSecond.average
And here’s an example result after executing the above command.
{
"result": [
{
"counterId": "net.usage.kiloBytesPerSecond.average",
"instance": "4000"
},
{
"counterId": "net.usage.kiloBytesPerSecond.average",
"instance": "vmnic0"
},
{
"counterId": "net.usage.kiloBytesPerSecond.average",
"instance": "vmnic1"
},
{
"counterId": "net.usage.kiloBytesPerSecond.average",
"instance": ""
}
],
"msg": "Successfully retrieved performance metrics",
"success": 0
}
We can also get the existing historical performance intervals by
using the perf.interval.info
vPoller method, e.g.:
$ vpoller-client --method perf.interval.info --vsphere-host vc01.example.org
On the screenshot below you can see an example of retrieving the historical performance intervals on a vSphere host.
The historical performance intervals are used when we need to retrieve historical metrics from performance providers.
Now, that we know how to get the available performance metrics for our performance providers, let’s now see how to retrieve the actual performance counters for them.
In the following example we will see how to get the CPU usage in MHz for a specific Virtual Machine.
And here is how we would get three samples of the CPU usage in MHz
performance metric.
$ vpoller-client --method vm.perf.metric.get --vsphere-host vc01.example.org \
--name vm01.example.org --max-sample 3 --counter cpu.usagemhz.megaHertz.average
Here is an example result of the above command.
We can also retrieve the performance metrics for an instance, e.g. get the CPU usage per core.
If we want to retrieve the performance metrics for a specific instance we would execute a similar command instead:
$ vpoller-client --method vm.perf.metric.get --vsphere-host vc01.example.org \
--name vm01.example.org --counter cpu.usagemhz.megaHertz.average --max-sample 3 --instance 0
We could also retrieve some interesting statistics from our Datacenters and Clusters as well.
The vim.Datacenter
and vim.ClusterComputeResource
managed entities support historical statistics only, so in order to
retrieve any performance metrics from them we should specify a valid
historical performance interval.
In the following examples we will see how to retrieve performance
counter vmop.numPoweron.number.latest
, which would give us the
number of the Virtual Machine power on operations for the past day.
$ vpoller-client --method datacenter.perf.metric.get --vsphere-host vc01.example.org \
--name MyDatacenter --counter vmop.numPoweron.number.latest --perf-interval "Past day"
Another example showing how to get performance counter
mem.consumed.kiloBytes.average
, which returns the amount of host
physical memory consumed by a virtual machine, host, or cluster.
$ vpoller-client --method host.perf.metric.get --vsphere-host vc01.example.org \
--name esxi01.example.org --counter mem.consumed.kiloBytes.average
As our last examples we will see how to retrieve various performance
metrics for vim.Datastore
managed entities.
Note
Some of the vim.Datastore
performance metrics are retrieved
by using the datastore.perf.metric.get
vPoller method, while
others are available via the host.perf.metric.get
, where a
datastore metric is retrieved by using the Datastore instance.
A vim.Datastore
performance provider by itself provides only
historical performance statistics.
Most of the real-time statistics (e.g. datastoreIops
) are
accessed via a vim.HostSystem
performance provider.
The example below shows how to retrieve the datastoreIops
for a
specific datastore.
First we will discover all instances of performance counter
datastore.datastoreIops.number.average
for our example
ESXi host esxi01.example.org
.
$ vpoller-client --method host.perf.metric.info --vsphere-host vc01.example.org \
--name esx01.example.org --counter datastore.datastoreIops.number.average
Example result from the above command is shown below, which contains
all instances of counter datastore.datastoreIops.number.average
.
{
"success": 0,
"result": [
{
"counterId": "datastore.datastoreIops.number.average",
"instance": "5481d059-dbd6de3d-2215-d8d385bf2110"
},
{
"counterId": "datastore.datastoreIops.number.average",
"instance": "5485af07-7326ddc0-6afc-d8d385bf2110"
},
{
"counterId": "datastore.datastoreIops.number.average",
"instance": "5485af4f-4dbf72e3-4980-d8d385bf2110"
}
],
"msg": "Successfully retrieved performance metrics"
}
If we are interested in finding out the Datastore name for the
5481d059-dbd6de3d-2215-d8d385bf2110
instance from the above
example result we could use the datastore.get
vPoller method to
do so. For example:
$ vpoller-client --method datastore.get --vsphere-host vc01.example.org \
--name ds:///vmfs/volumes/5481d059-dbd6de3d-2215-d8d385bf2110/ --properties name
And the result from the above command would give us the Datastore name.
{
"success": 0,
"result": [
{
"name": "datastore1",
"info.url": "ds:///vmfs/volumes/5481d059-dbd6de3d-2215-d8d385bf2110/"
}
],
"msg": "Successfully retrieved object properties"
}
Now, let’s get back to the datastoreIops
metric and retrieve it.
$ vpoller-client --method host.perf.metric.get --vsphere-host vc01.example.org \
--name esxi01.example.org --counter datastore.datastoreIops.number.average --instance 5481d059-dbd6de3d-2215-d8d385bf2110
And here is an example result from the above command:
{
"success": 0,
"result": [
{
"instance": "5481d059-dbd6de3d-2215-d8d385bf2110",
"value": 84,
"interval": 20,
"counterId": "datastore.datastoreIops.number.average",
"timestamp": "2015-02-10 15:48:40+00:00"
}
],
"msg": "Successfully retrieved performance metrics"
}