From 0d44df85ec57238741381ccf830512ff9a561457 Mon Sep 17 00:00:00 2001 From: davidnewhall2 Date: Sat, 30 Nov 2019 01:47:06 -0800 Subject: [PATCH 1/3] update readme --- README.md | 75 ++++++++++++++++++++----------------------------------- 1 file changed, 27 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 721c0e6e..4340dd0b 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + now with 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) @@ -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) 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) ![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) -##### UAP Dashboard +##### UAP Dashboard (InfluxDB) ![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 sites side-by-side. So easy! This screenshot barely does it justice. ![USW Dashboard Image](https://grafana.com/api/dashboards/10417/images/6664/image) From 7767fbd67724c3ae60f21aaaf07c5d15bb2769ac Mon Sep 17 00:00:00 2001 From: davidnewhall2 Date: Sat, 30 Nov 2019 01:57:50 -0800 Subject: [PATCH 2/3] fix build --- Makefile | 14 +++++++------- README.md | 3 +-- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/Makefile b/Makefile index 21b3524e..672f8ff1 100644 --- a/Makefile +++ b/Makefile @@ -87,39 +87,39 @@ README.html: md2roff # Binaries build: $(BINARY) -$(BINARY): *.go */*.go +$(BINARY): main.go pkg/*/*.go go build -o $(BINARY) -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" linux: $(BINARY).amd64.linux -$(BINARY).amd64.linux: *.go */*.go +$(BINARY).amd64.linux: main.go pkg/*/*.go # Building linux 64-bit x86 binary. GOOS=linux GOARCH=amd64 go build -o $@ -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" linux386: $(BINARY).i386.linux -$(BINARY).i386.linux: *.go */*.go +$(BINARY).i386.linux: main.go pkg/*/*.go # Building linux 32-bit x86 binary. GOOS=linux GOARCH=386 go build -o $@ -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" arm: arm64 armhf arm64: $(BINARY).arm64.linux -$(BINARY).arm64.linux: *.go */*.go +$(BINARY).arm64.linux: main.go pkg/*/*.go # Building linux 64-bit ARM binary. GOOS=linux GOARCH=arm64 go build -o $@ -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" armhf: $(BINARY).armhf.linux -$(BINARY).armhf.linux: *.go */*.go +$(BINARY).armhf.linux: main.go pkg/*/*.go # Building linux 32-bit ARM binary. GOOS=linux GOARCH=arm GOARM=6 go build -o $@ -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" macos: $(BINARY).amd64.macos -$(BINARY).amd64.macos: *.go */*.go +$(BINARY).amd64.macos: main.go pkg/*/*.go # Building darwin 64-bit x86 binary. GOOS=darwin GOARCH=amd64 go build -o $@ -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" exe: $(BINARY).amd64.exe windows: $(BINARY).amd64.exe -$(BINARY).amd64.exe: *.go */*.go +$(BINARY).amd64.exe: main.go pkg/*/*.go # Building windows 64-bit x86 binary. GOOS=windows GOARCH=amd64 go build -o $@ -ldflags "-w -s -X $(VERSION_PATH)=$(VERSION)-$(ITERATION)" diff --git a/README.md b/README.md index 4340dd0b..28a53777 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,4 @@ - now with 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) [![twitter](https://badgen.net/twitter/follow/TwitchCaptain?icon=https://simpleicons.now.sh/twitter/0099ff&label=TwitchCaptain&color=0116ff "TwitchCaptain @ Twitter")](https://twitter.com/TwitchCaptain) From 5866cafcc350ffa453c4013530281b0d6fe76a3f Mon Sep 17 00:00:00 2001 From: davidnewhall2 Date: Sat, 30 Nov 2019 01:58:38 -0800 Subject: [PATCH 3/3] add back comment --- README.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 28a53777..b81ca7c9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + now with 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) [![twitter](https://badgen.net/twitter/follow/TwitchCaptain?icon=https://simpleicons.now.sh/twitter/0099ff&label=TwitchCaptain&color=0116ff "TwitchCaptain @ Twitter")](https://twitter.com/TwitchCaptain) @@ -20,7 +20,6 @@ included; with screenshots. Five for InfluxDB and two for Prometheus, although three more Prometheus dashboards are coming! ## 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. @@ -30,7 +29,6 @@ the #unifi-poller channel on the [Ubiquiti Discord server](https://discord.gg/Kn 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 - [Ubiquiti](https://www.ui.com) makes networking devices like switches, gateways (routers) and wireless access points. They have a line of equipment named [UniFi](https://www.ui.com/products/#unifi) that uses a @@ -55,7 +53,6 @@ You'll have a plethora of data at your fingertips and the ability to craft custo graphs to slice the data any way you choose. Good luck! ## Backstory - 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 @@ -80,9 +77,9 @@ for making this dashboard; it gave me a fantastic start to making my own dashboa ## 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. +script if you needed to. Packages are 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