Merge branch 'v0.3.0'

Author: equelin

.gitignore

@@ -1,4 +1,5 @@
 unitymetrics
 unitymetrics.exe
+telegraf.conf
 *.tar.gz
 *.zip

README.md

@@ -1,22 +1,27 @@
 # UNITYMETRICS
 
-Unitymetrics is a tool written in Go for collecting metrics from a Dell EMC Unity array and translating them in InfluxDB's line protocol. 
+Unitymetrics is a tool written in Go for collecting usage and performance metrics from a Dell EMC Unity array and translating them in InfluxDB's line protocol.
 
-It can be use to send metrics in a InfluxDB database with the help of Telegraf.
+![unitymetrics-min](https://user-images.githubusercontent.com/9823778/38147007-b9abfe82-3450-11e8-8590-87d3afb7e480.png)
+
+It can be useful to send metrics in a InfluxDB database with the help of Telegraf and then display metrics in grafana.
+
+![screenshot-2018-3-30 grafana - unity](https://user-images.githubusercontent.com/9823778/38147174-60410d8c-3451-11e8-8320-016c38dbe705.png)
 
 ## How to find the available metrics
 
-In the Unity API, metrics are define by a path. For example, if you want to collect the remaining memory available on the storage processors, you'll have to use the path `sp.*.memory.summary.freeBytes`. 
+In the Unity API, metrics are define by a path. For example, if you want to collect the remaining memory available on the storage processors, you'll have to use the path `sp.*.memory.summary.freeBytes`.
 
 You can find a list of the metrics [here](https://gist.github.com/equelin/37486519972f8161c480f47ae5904390).
 
 If you look at the different path, you will figure that some of them contains `*` or `+` characters.
 
 When there is a `*` in the path, you can use the path as-is in your request, the `*` will be automatically replaced with all the possibilities. For example, if you want to use the path `sp.*.memory.summary.freeBytes`. The API will interpret it as if you were requesting the free memory for the SPA and the SPB. If you need this information only for one of the SPs, you can use the path `sp.spa.memory.summary.freeBytes` 
 
-When there is a `+` in the path, you have to replace it with the relevant item by yourself before requesting the API. For example, if you want to retrieve the CPU utilization of the SPA, you have to modify the path `kpi.sp.+.utilization` like this `kpi.sp.spa.utilization`   
+When there is a `+` in the path, you can replace it with the relevant item by yourself before requesting the API or by a `*` for breaking the results by this item. For example, if you want to specifically retrieve the CPU utilization of the SPA, you have to modify the path `kpi.sp.+.utilization` like this `kpi.sp.spa.utilization`.
 
 ## How to install it
+
 ### From prebuilt release
 
 You can find prebuilt unitymetrics binaries on the [releases page](https://github.com/equelin/unitymetrics/releases).
@@ -53,26 +58,32 @@ You can build unitymetrics using:
 
 See usage with:
 
-```
+```bash
 ./unitymetrics -h
 ```
 
-#### Run a Dell Unity metrics collection with the default metrics and a sampling interval
+### Run a Dell EMC Unity metrics collection for an historical path 
 
-```
-./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword
+```bash
+./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword -histkpipaths kpi.sp.*.utilization
 ```
 
-#### Run a Dell Unity metrics collection with the default metrics and sampling interval of 10 seconds
+### Run a Dell EMC Unity metrics collection with a real time metric and sampling interval of 10 seconds
 
-```
-./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword -interval 10
+```bash
+./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword -rtpaths sp.*.memory.summary.freeBytes -interval 10
 ```
 
-#### Run a Dell Unity metrics collection with specific metrics and sampling interval of 10 seconds
+### Run a Dell EMC Unity metrics collection with multiple metrics and sampling interval of 10 seconds
 
+```bash
+./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword -interval 10 -histkpipaths kpi.sp.*.utilization,kpi.lun.+.sp.+.rw.+.throughput,kpi.lun.*.sp.+.rw.+.throughput,kpi.lun.+.sp.+.responseTime,kpi.lun.*.sp.+.responseTime,kpi.lun.+.sp.+.queueLength,kpi.lun.*.sp.+.queueLength
 ```
-./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword -interval 10 -paths kpi.sp.spa.utilization,sp.*.cpu.summary.busyTicks,sp.*.cpu.uptime,sp.*.storage.pool.*.sizeFree,
+
+### Run a Dell EMC Unity metrics collection for collecting capacity statistics
+
+```bash
+./unitymetrics -unity unity01.example.com -user admin -password AwesomePassword -capacity
 ```
 
 ## Using unitymetrics with Telegraf
@@ -93,14 +104,66 @@ Here is an example of a working telegraf's config file:
 [[inputs.exec]]
   # Shell/commands array
   # Full command line to executable with parameters, or a glob pattern to run all matching files.
-  commands = ["unitymetrics -user admin -password AwesomePassword -unity unity01.okcomputer.lab -interval 10 -paths kpi.sp.spa.utilization,sp.*.cpu.summary.busyTicks,sp.*.cpu.uptime,sp.*.storage.pool.*.sizeFree,sp.*.storage.pool.*.sizeSubscribed,sp.*.storage.pool.*.sizeTotal,sp.*.storage.pool.*sizeUsed,sp.*.memory.summary.totalBytes,sp.*.memory.summary.totalUsedBytes"]
+  commands = ["unitymetrics -user admin -password Mypassword -unity unity01.example.com -histkpipaths kpi.sp.*.utilization,kpi.lun.+.sp.+.rw.+.throughput,kpi.lun.*.sp.+.rw.+.throughput,kpi.lun.+.sp.+.responseTime,kpi.lun.*.sp.+.responseTime,kpi.lun.+.sp.+.queueLength,kpi.lun.*.sp.+.queueLength -capacity"]
+
+  # Timeout for each command to complete.
+  timeout = "60s"
+
+  # Data format to consume.
+  # NOTE json only reads numerical measurements, strings and booleans are ignored.
+  data_format = "influx"
+
+  interval = "60s"
+```
+
+If needed, you can specify more than one input plugin. It might be useful if you want to gather different statistics with different intervals or if you want to query different arrays.
+
+```Toml
+###############################################################################
+#                            INPUT PLUGINS                                    #
+###############################################################################
+
+[[inputs.exec]]
+  # Shell/commands array
+  # Full command line to executable with parameters, or a glob pattern to run all matching files.
+  commands = ["unitymetrics -user admin -password Mypassword -unity unity01.example.com -histkpipaths kpi.sp.*.utilization,kpi.lun.+.sp.+.rw.+.throughput,kpi.lun.*.sp.+.rw.+.throughput,kpi.lun.+.sp.+.responseTime,kpi.lun.*.sp.+.responseTime,kpi.lun.+.sp.+.queueLength,kpi.lun.*.sp.+.queueLength -capacity"]
+
+  # Timeout for each command to complete.
+  timeout = "60s"
+
+  # Data format to consume.
+  # NOTE json only reads numerical measurements, strings and booleans are ignored.
+  data_format = "influx"
+
+  interval = "60s"
+
+[[inputs.exec]]
+  # Shell/commands array
+  # Full command line to executable with parameters, or a glob pattern to run all matching files.
+  commands = ["unitymetrics -user admin -password Mypassword -unity unity01.example.com -interval 50 -rtpaths sp.*.memory.summary.freeBytes,sp.*.memory.summary.totalBytes,sp.*.memory.summary.totalUsedBytes,sp.*.cpu.uptime"]
 
-  # Timeout for each command to complete. 
-  timeout = "20s"
+  # Timeout for each command to complete.
+  timeout = "60s"
 
   # Data format to consume.
   # NOTE json only reads numerical measurements, strings and booleans are ignored.
   data_format = "influx"
+
+  interval = "60s"
+
+[[inputs.exec]]
+  # Shell/commands array
+  # Full command line to executable with parameters, or a glob pattern to run all matching files.
+  commands = ["unitymetrics -user admin -password Mypassword -unity unity02.example.com -histkpipaths kpi.sp.*.utilization,kpi.lun.+.sp.+.rw.+.throughput,kpi.lun.*.sp.+.rw.+.throughput,kpi.lun.+.sp.+.responseTime,kpi.lun.*.sp.+.responseTime,kpi.lun.+.sp.+.queueLength,kpi.lun.*.sp.+.queueLength -capacity"]
+
+  # Timeout for each command to complete.
+  timeout = "60s"
+
+  # Data format to consume.
+  # NOTE json only reads numerical measurements, strings and booleans are ignored.
+  data_format = "influx"
+
+  interval = "60s"
 ```
 
 # Author