Skip to content

Commit

Permalink
update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@sofixa
sofixa committed Nov 10, 2017
1 parent 3614590 commit b47e66d
Showing 1 changed file with 61 additions and 33 deletions.
94 changes: 61 additions & 33 deletions README.md
View file
@@ -1,59 +1,68 @@
[![Go Report Card](https://goreportcard.com/badge/Oxalide/vsphere-influxdb-go)](https://goreportcard.com/report/github.com/Oxalide/vsphere-influxdb-go)
[![Releases](https://img.shields.io/github/release/Oxalide/vsphere-influxdb-go.svg?style=flat-square)](https://github.com/Oxalide/vsphere-influxdb-go/releases/latest) [![Build Status](https://travis-ci.org/Oxalide/vsphere-influxdb-go.svg?branch=master)](https://travis-ci.org/Oxalide/vsphere-influxdb-go) [![Go Report Card](https://goreportcard.com/badge/Oxalide/vsphere-influxdb-go)](https://goreportcard.com/report/github.com/Oxalide/vsphere-influxdb-go)

# Collect VMware vSphere, vCenter and ESXi performance metrics and send them to InfluxDB
# Collect VMware vCenter and ESXi performance metrics and send them to InfluxDB

# External dependencies
# Screenshots of Grafana dashboards
![screenshot](https://grafana.com/api/dashboards/3556/images/2224/image)
![screenshot](https://grafana.com/api/dashboards/3556/images/2227/image)
![screenshot](https://grafana.com/api/dashboards/3556/images/2230/image)
![screenshot](https://grafana.com/api/dashboards/3571/images/2245/image)
![screenshot](https://grafana.com/api/dashboards/3571/images/2251/image)
![screenshot](https://grafana.com/api/dashboards/3571/images/2254/image)

* [govmomi](https://github.com/vmware/govmomi)
* [influxDB go client](https://github.com/influxdata/influxdb/tree/master/client/v2)

Both are installed via go dep when go getting the project:

# Run
# Description and Features
This is a tool written in Go that helps you do your own custom tailored monitoring, capacity planning and performance debugging of VMware based infrastructures. It collects all possible metrics from vCenters and ESXi hypervisors about hosts, clusters, resource pools, datastores and virtual machines and sends them to an [InfluxDB database](https://github.com/influxdata/influxdb) (a popular open source time series database project written in Go), which you can then visualise in Grafana (links to sample dashboards [below](#example-dashboards)) or Chronograf, and use Grafana, Kapacitor or custom scripts to do alerting based on your needs, KPIs, capacity plannings/expectations.

# Install
Grab the [latest release](https://github.com/Oxalide/vsphere-influxdb-go/releases/latest) for your OS (deb, rpm packages, exes, archives for Linux, Darwin, Windows, FreeBSD on amd64, arm6, arm7, arm64 are available) and install it.

For Debian/Ubuntu on adm64:
```
go get github.com/oxalide/vsphere-influxdb-go
```
This will install the project in your $GOBIN($GOPATH/bin). If you have appended $GOBIN to your $PATH, you will be able to call it directly. Otherwise, you'll have to call it with its full path.
Example:
```
vsphere-influxdb-go
curl -L -O $(curl -s https://api.github.com/repos/Oxalide/vsphere-influxdb-go/releases | grep browser_download_url | grep '64[.]deb' | head -n 1 | cut -d '"' -f 4)
dpkg -i vsphere-influxdb-go*.deb
```
or :

CentOS/Red Hat on amd64:
```
$GOBIN/vsphere-influxdb-go
curl -L -O $(curl -s https://api.github.com/repos/Oxalide/vsphere-influxdb-go/releases | grep browser_download_url | grep '64[.]rpm' | head -n 1 | cut -d '"' -f 4)
rpm -i vsphere-influxdb-go*.rpm
```

This will install vsphere-influxdb-go in /usr/local/bin/vsphere-influxdb-go and an example configuration file in /etc/vsphere-influxdb-go.json that needs to be edited.


# Configure

You'll need a JSON file with all your vCenters/ESXi to connect to, the InfluxDB connection details(url, username/password, database to use), and the metrics to collect.
Additionally you can provide a vCenter/ESXi server and InfluxDB connection details via environment variables, wich is extremly helpful when running inside a container.
The JSON configuration file in /etc/vsphere-influxdb-go.json contains all your vCenters/ESXi to connect to, the InfluxDB connection details(url, username/password, database to use), and the metrics to collect(full list [here](http://www.virten.net/2015/05/vsphere-6-0-performance-counter-description/) ).

For InfluxDB set INFLUX\_HOSTNAME, INFLUX\_USERNAME, INFLUX\_PASSWORD and INFLUX\_DATABASE.
For vSphere set VSPHERE\_HOSTNAME, VSPHERE\_USERNAME and VSPHERE\_PASSWORD and keep in mind, that currently only one vCenter/ESXi can be added via environment variable.
**Note: Not all metrics are available directly, you might need to change your metric collection level.**
A table with the level needed for each metric is availble [here](http://www.virten.net/2015/05/which-performance-counters-are-available-in-each-statistic-level/), and you can find a python script to change the collect level in the [tools folder of the project](./tools/).

If you set a domain, it will be automaticaly removed from the names of the found objects.
Additionally you can provide a vCenter/ESXi server and InfluxDB connection details via environment variables, wich is extremly helpful when running inside a container:

Metrics collected are defined by associating ObjectType groups with Metric groups.
To see all available metrics, check out [this](http://www.virten.net/2015/05/vsphere-6-0-performance-counter-description/) page.
For InfluxDB:
* INFLUX\_HOSTNAME
* INFLUX\_USERNAME
* INFLUX\_PASSWORD
* INFLUX\_DATABASE

**Note: Not all metrics are available directly, you might need to change your metric collection level.**
A table with the level needed for each metric is availble [here](http://www.virten.net/2015/05/which-performance-counters-are-available-in-each-statistic-level/), and you can find a pyVmomi script that cahanges to collect level in the [tools folder of the project](./tools/).
For vSphere:
* VSPHERE\_HOSTNAME
* VSPHERE\_USERNAME
* SPHERE\_PASSWORD

Keep in mind, that currently only one vCenter/ESXi can be added via environment variable.

An example of configuration file is [here](./vsphere-influxdb.json.sample).
If you set a domain, it will be automaticaly removed from the names of the found objects.

You need to place it at /etc/*binaryname*.json (/etc/vsphere-influxdb.json by default) or you can specify a different location using the config flag.
Metrics collected are defined by associating ObjectType groups with Metric groups.


# Run as a service

Create a crontab to run it every X minutes(one minute is fine - in our case, ~30 vCenters, ~100 ESXi and ~1400 VMs take approximately 25s to collect all metrics - rather impressive, i might add).
```
* * * * * $HOME/work/go/bin/vsphere-influxdb-go
* * * * * /usr/local/bin/vsphere-influxdb-go
```

# Example dashboards
Expand All @@ -63,9 +72,28 @@ Create a crontab to run it every X minutes(one minute is fine - in our case, ~30

Contributions welcome!

# TODO

# Compile from source

```
go get github.com/oxalide/vsphere-influxdb-go
```
This will install the project in your $GOBIN($GOPATH/bin). If you have appended $GOBIN to your $PATH, you will be able to call it directly. Otherwise, you'll have to call it with its full path.
Example:
```
vsphere-influxdb-go
```
or :
```
$GOBIN/vsphere-influxdb-go
```

# TODO before v1.0
* Add service discovery(or probably something like [Viper](https://github.com/spf13/viper) for easier and more flexible configuration with multiple backends)
* Add extra tags(cluster for the hosts, etc.)
* Daemonize
* Provide a ready to use Dockerfile

# Contributing
You are welcome to contribute!
Expand Down

0 comments on commit b47e66d

Please sign in to comment.