update readme
This commit is contained in:
davidnewhall2
parent
ebe05ec3e5
commit
0d44df85ec
75
README.md
75
README.md
|
|
@ -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!
|
||||
|
||||
|
||||
[](https://discord.gg/KnyKYt2)
|
||||
|
|
@ -13,8 +13,9 @@
|
|||
[](https://travis-ci.org/davidnewhall/unifi-poller)
|
||||
|
||||
Collect your UniFi controller data and report it to an InfluxDB instance,
|
||||
or export it for Prometheus collection. Prometheus support is new, and much
|
||||
of the documentation still needs to be updated. 11/30/2019
|
||||
or export it for Prometheus collection. Prometheus support is
|
||||
[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)
|
||||
included; with screenshots. Five for InfluxDB and two for Prometheus, although
|
||||
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
|
||||
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).
|
||||
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
|
||||
|
||||
|
|
@ -40,35 +42,35 @@ Ubiquiti also provides a dedicated hardware device called a
|
|||
beta / early access, but UniFi Poller can collect its data!
|
||||
|
||||
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
|
||||
the data to an Influx database. A small setup with 2 access points, 1 switch, 1
|
||||
gateway and 40 clients produces over 3000 fields (metrics).
|
||||
Docker. In Influx-mode it polls a UniFi controller every 30 seconds for
|
||||
measurements and exports the data to an Influx database. In Prometheus mode the
|
||||
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
|
||||
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.
|
||||
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!
|
||||
|
||||
## Backstory
|
||||
|
||||
Okay, so here's the deal. I found a simple piece of code on GitHub that
|
||||
sorta did what I needed; we all know that story. I wanted more data, so
|
||||
I added more data collection. I believe I've completely rewritten every
|
||||
piece of original code, except the copyright/license file and that's fine
|
||||
with me. I probably wouldn't have made it this far if
|
||||
[Garrett](https://github.com/dewski/unifi) hadn't written the original
|
||||
code I started with. Many props my man.
|
||||
I found a simple piece of code on GitHub that sorta did what I needed;
|
||||
we all know that story. I wanted more data, so I added more data collection.
|
||||
I believe I've completely rewritten every piece of original code, except the
|
||||
copyright/license file and that's fine with me. I probably wouldn't have made
|
||||
it this far if [Garrett](https://github.com/dewski/unifi) hadn't written the
|
||||
original code I started with. Many props my man.
|
||||
|
||||
The original code pulled only the client data. This app now pulls data
|
||||
for clients, access points, security gateways and switches. I used to
|
||||
own two UAP-AC-PROs, one USG-3 and one US-24-250W, but have since upgraded
|
||||
for clients, access points, security gateways, dream machines and switches. I
|
||||
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,
|
||||
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?
|
||||
|
||||
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?
|
||||
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
|
||||
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.
|
||||
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
|
||||
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
|
||||
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.
|
||||
|
||||
## Development
|
||||
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
|
||||
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
|
||||
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
|
||||
[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.
|
||||
|
||||
## 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?
|
||||
|
||||
There are five total dashboards available. Below you'll find screenshots of a few.
|
||||
|
||||
##### Client Dashboard
|
||||
##### Client Dashboard (InfluxDB)
|
||||
|
||||
|
||||
##### USG Dashboard
|
||||
##### USG Dashboard (InfluxDB)
|
||||
|
||||
|
||||
##### UAP Dashboard
|
||||
##### UAP Dashboard (InfluxDB)
|
||||
|
||||
|
||||
##### USW / Switch Dashboard
|
||||
##### USW / Switch Dashboard (InfluxDB)
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue