public_git
/
unpoller_unpoller
mirror of https://github.com/unpoller/unpoller.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

update readme

This commit is contained in:
davidnewhall2 2019-11-30 01:47:06 -08:00
parent ebe05ec3e5
commit 0d44df85ec
1 changed files with 27 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
README.md
View File

@ -1,4 +1,4 @@
<img width="320px" src="https://raw.githubusercontent.com/wiki/davidnewhall/unifi-poller/images/unifi-poller-logo.png"> <img width="320px" src="https://raw.githubusercontent.com/wiki/davidnewhall/unifi-poller/images/unifi-poller-logo.png"> now with <img width="30px" src="https://prometheus.io/assets/prometheus_logo_grey.svg"> Prometheus support!
[![discord](https://badgen.net/badge/icon/Discord?color=0011ff&label&icon=https://simpleicons.now.sh/discord/eee "Ubiquiti Discord")](https://discord.gg/KnyKYt2) [![discord](https://badgen.net/badge/icon/Discord?color=0011ff&label&icon=https://simpleicons.now.sh/discord/eee "Ubiquiti Discord")](https://discord.gg/KnyKYt2)
@ -13,8 +13,9 @@
[![travis](https://badgen.net/travis/davidnewhall/unifi-poller?icon=travis&label=build "Travis Build")](https://travis-ci.org/davidnewhall/unifi-poller) [![travis](https://badgen.net/travis/davidnewhall/unifi-poller?icon=travis&label=build "Travis Build")](https://travis-ci.org/davidnewhall/unifi-poller)
Collect your UniFi controller data and report it to an InfluxDB instance, Collect your UniFi controller data and report it to an InfluxDB instance,
or export it for Prometheus collection. Prometheus support is new, and much or export it for Prometheus collection. Prometheus support is
of the documentation still needs to be updated. 11/30/2019 [new](https://github.com/davidnewhall/unifi-poller/issues/88), and much
of the documentation still needs to be updated; 11/30/2019.
[Seven Grafana Dashboards](http://grafana.com/dashboards?search=unifi-poller) [Seven Grafana Dashboards](http://grafana.com/dashboards?search=unifi-poller)
included; with screenshots. Five for InfluxDB and two for Prometheus, although included; with screenshots. Five for InfluxDB and two for Prometheus, although
three more Prometheus dashboards are coming! three more Prometheus dashboards are coming!
@ -27,6 +28,7 @@ I'm willing to help if you have troubles.
Open an [Issue](https://github.com/davidnewhall/unifi-poller/issues) and Open an [Issue](https://github.com/davidnewhall/unifi-poller/issues) and
we'll figure out how to get things working for you. You can also get help in we'll figure out how to get things working for you. You can also get help in
the #unifi-poller channel on the [Ubiquiti Discord server](https://discord.gg/KnyKYt2). the #unifi-poller channel on the [Ubiquiti Discord server](https://discord.gg/KnyKYt2).
I've also [provided a forum post](https://community.ui.com/questions/Unifi-Poller-Store-Unifi-Controller-Metrics-in-InfluxDB-without-SNMP/58a0ea34-d2b3-41cd-93bb-d95d3896d1a1) you may use to get additional help.
## Description ## Description
@ -40,35 +42,35 @@ Ubiquiti also provides a dedicated hardware device called a
beta / early access, but UniFi Poller can collect its data! beta / early access, but UniFi Poller can collect its data!
UniFi Poller is a small Golang application that runs on Windows, macOS, Linux or UniFi Poller is a small Golang application that runs on Windows, macOS, Linux or
Docker. It polls a UniFi controller every 30 seconds for measurements and exports Docker. In Influx-mode it polls a UniFi controller every 30 seconds for
the data to an Influx database. A small setup with 2 access points, 1 switch, 1 measurements and exports the data to an Influx database. In Prometheus mode the
gateway and 40 clients produces over 3000 fields (metrics). poller opens a web port and accepts Prometheus polling. It converts the UniFi
Controller API data into Prometheus exports on the fly.
This application requires your controller to be running all the time. If you run This application requires your controller to be running all the time. If you run
a UniFi controller, there's no excuse not to install a UniFi controller, there's no excuse not to install
[Influx](https://github.com/davidnewhall/unifi-poller/wiki/InfluxDB), [Influx](https://github.com/davidnewhall/unifi-poller/wiki/InfluxDB) or
[Prometheus](https://prometheus.io),
[Grafana](https://github.com/davidnewhall/unifi-poller/wiki/Grafana) and this app. [Grafana](https://github.com/davidnewhall/unifi-poller/wiki/Grafana) and this app.
You'll have a plethora of data at your fingertips and the ability to craft custom You'll have a plethora of data at your fingertips and the ability to craft custom
graphs to slice the data any way you choose. Good luck! graphs to slice the data any way you choose. Good luck!
## Backstory ## Backstory
Okay, so here's the deal. I found a simple piece of code on GitHub that I found a simple piece of code on GitHub that sorta did what I needed;
sorta did what I needed; we all know that story. I wanted more data, so we all know that story. I wanted more data, so I added more data collection.
I added more data collection. I believe I've completely rewritten every I believe I've completely rewritten every piece of original code, except the
piece of original code, except the copyright/license file and that's fine copyright/license file and that's fine with me. I probably wouldn't have made
with me. I probably wouldn't have made it this far if it this far if [Garrett](https://github.com/dewski/unifi) hadn't written the
[Garrett](https://github.com/dewski/unifi) hadn't written the original original code I started with. Many props my man.
code I started with. Many props my man.
The original code pulled only the client data. This app now pulls data The original code pulled only the client data. This app now pulls data
for clients, access points, security gateways and switches. I used to for clients, access points, security gateways, dream machines and switches. I
own two UAP-AC-PROs, one USG-3 and one US-24-250W, but have since upgraded used to own two UAP-AC-PROs, one USG-3 and one US-24-250W, but have since upgraded
a few devices. Many other users have also provided feedback to improve this app, a few devices. Many other users have also provided feedback to improve this app,
and we have reports of it working on nearly every switch, AP and gateway; UDM included. and we have reports of it working on nearly every switch, AP and gateway.
## What's this data good for? ## What's this data good for?
I've been trying to get my UAP data into Grafana. Sure, google search that. I've been trying to get my UAP data into Grafana. Sure, google search that.
You'll find [this](https://community.ubnt.com/t5/UniFi-Wireless/Grafana-dashboard-for-UniFi-APs-now-available/td-p/1833532). What if you don't want to deal with SNMP? You'll find [this](https://community.ubnt.com/t5/UniFi-Wireless/Grafana-dashboard-for-UniFi-APs-now-available/td-p/1833532). What if you don't want to deal with SNMP?
Well, here you go. I've replicated 400% of what you see on those SNMP-powered Well, here you go. I've replicated 400% of what you see on those SNMP-powered
@ -76,61 +78,38 @@ dashboards with this Go app running on the same mac as my UniFi controller.
All without enabling SNMP nor trying to understand those OIDs. Mad props All without enabling SNMP nor trying to understand those OIDs. Mad props
to [waterside](https://community.ubnt.com/t5/user/viewprofilepage/user-id/303058) to [waterside](https://community.ubnt.com/t5/user/viewprofilepage/user-id/303058)
for making this dashboard; it gave me a fantastic start to making my own dashboards. for making this dashboard; it gave me a fantastic start to making my own dashboards.
This app is up to five dashboards now!
##### Update 9/2019
Some new "prometheus exporters" are showing up. I admit I don't know much about
Prometheus, but so far the prometheus exporting apps I've seen are missing many
data points. Let me know if Prometheus is something you'd like to see support for.
I've also created [another forum post](https://community.ui.com/questions/Unifi-Poller-Store-Unifi-Controller-Metrics-in-InfluxDB-without-SNMP/58a0ea34-d2b3-41cd-93bb-d95d3896d1a1) you may use to get additional help.
## Development
The "What now..." section below used to be a lot longer. I've received a lot of
support, feedback and assistance from the community. Many thanks! This app is
extremely stable with a tiny memory and cpu footprint. I imagine one day we'll
figure out how to make it run on a CloudKey or UDM directly; once I have one
personally that will be my goal. In addition to stability, this app provides
an intuitive installation and configuration process. Maintenance is a breeze too.
## Operation
You can control this app with puppet, chef, saltstack, homebrew or a simple bash You can control this app with puppet, chef, saltstack, homebrew or a simple bash
script if you needed to. It's available for macOS, Linux and Docker. It comes with script if you needed to. It's available for macOS, Linux and Docker. It comes with
a systemd service unit that allows you automatically start it up on most Linux a systemd service unit that allows you automatically start it up on most Linux
hosts. It works just fine on [Windows](https://github.com/davidnewhall/unifi-poller/wiki/Windows) too. hosts. It works just fine on [Windows](https://github.com/davidnewhall/unifi-poller/wiki/Windows) too.
Most people prefer Docker, and this app is right at home in that environment. Most people prefer Docker, and this app is right at home in that environment.
## Development
The UniFi data extraction is provided as an [external library](https://godoc.org/golift.io/unifi), The UniFi data extraction is provided as an [external library](https://godoc.org/golift.io/unifi),
and you can import that code directly without futzing with this application. That and you can import that code directly without futzing with this application. That
means, if you wanted to do something like make telegraf collect your data instead means, if you wanted to do something like make telegraf collect your data instead
of UniFi Poller you can achieve that with a little bit of Go code. You could write of UniFi Poller you can achieve that with a little bit of Go code. You could write
a small app that acts as a telegraf input plugin using the [unifi](https://github.com/golift/unifi) a small app that acts as a telegraf input plugin using the [unifi](https://github.com/golift/unifi)
library to grab the data from your controller. As a bonus, all of the code in UniFi Poller is library to grab the data from your controller. As a bonus, all of the code in UniFi Poller is
[also a library](https://godoc.org/github.com/davidnewhall/unifi-poller/unifipoller) [in libraries](https://godoc.org/github.com/davidnewhall/unifi-poller/pkg)
and can be used in other projects. and can be used in other projects.
## What now...
We are at a point where the application works as intended, and we are trying to
maintain the status quo. Ubiquiti releases updates, things break, we fix it;
round and round we go. If you have new hardware or a new controller version, and
something is not showing up, please open an
[Issue](https://github.com/davidnewhall/unifi-poller/issues) so we can fix it.
## What's it look like? ## What's it look like?
There are five total dashboards available. Below you'll find screenshots of a few. There are five total dashboards available. Below you'll find screenshots of a few.
##### Client Dashboard ##### Client Dashboard (InfluxDB)
![UniFi Clients Dashboard Image](https://grafana.com/api/dashboards/10418/images/6660/image) ![UniFi Clients Dashboard Image](https://grafana.com/api/dashboards/10418/images/6660/image)
##### USG Dashboard ##### USG Dashboard (InfluxDB)
![USG Dashboard Image](https://grafana.com/api/dashboards/10416/images/6663/image) ![USG Dashboard Image](https://grafana.com/api/dashboards/10416/images/6663/image)
##### UAP Dashboard ##### UAP Dashboard (InfluxDB)
![UAP Dashboard Image](https://grafana.com/api/dashboards/10415/images/6662/image) ![UAP Dashboard Image](https://grafana.com/api/dashboards/10415/images/6662/image)
##### USW / Switch Dashboard ##### USW / Switch Dashboard (InfluxDB)
You can drill down into specific sites, switches, and ports. Compare ports in different You can drill down into specific sites, switches, and ports. Compare ports in different
sites side-by-side. So easy! This screenshot barely does it justice. sites side-by-side. So easy! This screenshot barely does it justice.
![USW Dashboard Image](https://grafana.com/api/dashboards/10417/images/6664/image) ![USW Dashboard Image](https://grafana.com/api/dashboards/10417/images/6664/image)