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:
David Newhall II 2019-08-25 21:00:52 -07:00
parent eaa583bfff
commit 75c616aebe
2 changed files with 40 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.metadata.sh
View File

@ -9,8 +9,8 @@ GHUSER="davidnewhall"
# Github repo containing homebrew formula repo.
HBREPO="golift/homebrew-mugs"
MAINT="David Newhall II <david at sleepers dot pro>"
VENDOR="Go Lift"
DESC="Polls a UniFi controller and stores metrics in InfluxDB"
VENDOR="Go Lift <code at golift dot io>"
DESC="Polls a UniFi controller and exports metrics to InfluxDB"
GOLANGCI_LINT_ARGS="--enable-all -D gochecknoglobals -e dupl -e G101"
# Example must exist at examples/$CONFIG_FILE.example
CONFIG_FILE="up.conf"

78
README.md
View File

@ -12,9 +12,19 @@
[![stars](https://badgen.net/github/stars/davidnewhall/unifi-poller?icon=https://simpleicons.now.sh/macys/fab&label=&color=0099ee "GitHub Stars")](https://github.com/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 send it to an InfluxDB instance.
[Grafana Dashboards](http://grafana.com/dashboards?search=unifi-poller) included.
Updated 2019.
Collect your UniFi controller data and export it to an InfluxDB instance.
[Five Grafana Dashboards](http://grafana.com/dashboards?search=unifi-poller)
included; with screenshots. Updated 2019.
## Installation
[See the Wiki!](https://github.com/davidnewhall/unifi-poller/wiki/Installation)
We have a special place for [Docker Users](https://github.com/davidnewhall/unifi-poller/wiki/Docker).
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 check out
my [Discord server](https://discord.gg/DyVsMyt).
## Description
@ -27,8 +37,8 @@ Ubiquiti also provides a dedicated hardware device called a
[CloudKey](https://www.ui.com/unifi/unifi-cloud-key/) that runs the controller software.
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 stores
the data in an Influx database. A small setup with 2 access points, 1 switch, 1
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).
This application requires your controller to be running all the time. If you run
@ -38,11 +48,6 @@ a UniFi controller, there's no excuse not to install
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!
## Installation
[See the Wiki!](https://github.com/davidnewhall/unifi-poller/wiki/Installation)
We have a special place for [Docker Users](https://github.com/davidnewhall/unifi-poller/wiki/Docker).
# Backstory
Okay, so here's the deal. I found a simple piece of code on GitHub that
@ -54,44 +59,46 @@ with me. I probably wouldn't have made it this far if
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 currently
own two UAP-AC-PROs, one USG-3 and one US-24-250W. If your devices differ
this app may miss some data. I'm willing to help and make it better.
Open an [Issue](https://github.com/davidnewhall/unifi-poller/issues) and
we'll figure out how to get things working for you.
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
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.
# 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).
And that's all you'll find. What if you don't want to deal with SNMP?
Well, here you go. I've replicated 90% of what you see on those SNMP-powered
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
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.
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 larger. I've received a lot of
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 device directly; once I have one
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.
I'm not a software engineer, I'm a a firm believer in operational excellence above
all else. To that end, this app shall remain easy, intuitive and highly adaptable.
I'm totally open to add more configuration options if someone raises a need or concern.
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.
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
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
@ -102,20 +109,11 @@ and can be used in other projects.
# What now...
### Are there other devices that need to be included?
I have: switch, router, access point. Three total, and the type structs are
likely missing data for variants of these devices. e.g. Some UAPs have more
radios, I probably didn't properly account for that. Some gateways have more
ports, some switches have 10Gb, etc. These are things I do not have data on
to write code for. If you have these devices, and want them graphed, open an
Issue and lets discuss.
### Radios, Frequencies, Interfaces, vAPs
My access points only seem to have two radios, one interface and vAP per radio.
I'm not sure if the graphs, as-is, provide enough insight into APs with other
configurations. Help me figure that out?
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?