2015-05-04 02:02:53 +08:00
# ExpvarMon
2015-05-02 01:40:32 +08:00
2015-05-04 02:58:03 +08:00
[![Build Status ](https://drone.io/github.com/divan/expvarmon/status.png )](https://drone.io/github.com/divan/expvarmon/latest)
2015-05-04 02:02:53 +08:00
TermUI based Go apps monitor using [expvars ](http://golang.org/pkg/expvar/ ) variables (/debug/vars). Quickest way to monitor your Go app.
2015-05-02 01:40:32 +08:00
## Introduction
2015-05-04 06:22:54 +08:00
Go apps console monitoring tool. Minimal configuration efforts. Quick and easy monitoring solution for one or multiple services.
2015-05-02 01:40:32 +08:00
2015-05-04 02:46:59 +08:00
## Features
* Single- and multi-apps mode
* Local and remote apps support
2015-07-11 00:44:30 +08:00
* HTTP and HTTPS endpoints, including Basic Auth support
2015-05-04 02:46:59 +08:00
* Arbitrary number of apps and vars to monitor (from 1 to 30+, depends on size of your terminal)
* Track restarted/failed apps
* Show maximum value
* Supports: Integer, float, duration, memory, string, bool variables
* Sparkline charts for integer, duration and memory data
* Auto-resize on font-size change or window resize
* Uses amazing [TermUI ](https://github.com/gizak/termui ) library by [gizak ](https://github.com/gizak )
2015-05-02 01:40:32 +08:00
## Demo
2015-05-04 02:02:53 +08:00
### Multiple apps mode
< img src = "./demo/demo_multi.png" alt = "Multi mode" width = "800" >
2015-05-02 01:40:32 +08:00
2015-05-04 02:46:59 +08:00
### Single app mode
2015-05-04 02:02:53 +08:00
< img src = "./demo/demo_single.png" alt = "Single mode" width = "800" >
You can monitor arbitrary number of services and variables:
2015-05-04 02:24:56 +08:00
2015-05-04 02:09:27 +08:00
< a href = "./demo/demo_1var.png" target = "_blank" > < img src = "./demo/demo_1var.png" alt = "1 var" width = "350" > < / a > < a href = "./demo/demo_small.png" target = "_blank" > < img src = "./demo/demo_small.png" alt = "25 apps" width = "350" > < / a >
2015-05-04 02:24:56 +08:00
2015-05-04 02:46:59 +08:00
## Purpose
2015-05-04 06:22:54 +08:00
This app targets debug/develop sessions when you need an instant way to monitor you app(s). It's not intended to monitor apps in production.
2015-05-04 02:46:59 +08:00
Also it doesn't use any storage engines and doesn't send notifications.
2015-05-04 02:24:56 +08:00
## Install
2015-05-04 03:11:36 +08:00
Just run go get:
2015-05-04 02:24:56 +08:00
2015-05-04 02:53:03 +08:00
go get github.com/divan/expvarmon
2015-05-04 02:24:56 +08:00
## Usage
### Prepare your app
First, you have to add [expvars ](http://golang.org/pkg/expvar/ ) support into your Go program. It's as simple as:
import _ "expvar"
2015-05-04 08:34:42 +08:00
and note the port your app is listening on. If it's not, just add two lines:
2015-05-04 02:24:56 +08:00
import "net/http"
...
http.ListenAndServe(":1234", nil)
and expvar will add handler for "localhost:1234/debug/vars" to your app.
2015-05-04 06:22:54 +08:00
By default, expvars adds two variables: *memstats* and *cmdline* . It's enough to monitor memory and garbage collector status in your app.
2015-05-04 02:24:56 +08:00
### Run expvarmon
2015-05-04 06:22:54 +08:00
Just run expvarmon with -ports="1234" flag:
2015-05-04 02:24:56 +08:00
expvarmon -ports="1234"
That's it.
2015-05-04 03:26:32 +08:00
More examples:
./expvarmon -ports="80"
2015-07-11 00:44:30 +08:00
./expvarmon -ports="23000-23010,http://example.com:80-81" -i=1m
2015-05-04 03:26:32 +08:00
./expvarmon -ports="80,remoteapp:80" -vars="mem:memstats.Alloc,duration:Response.Mean,Counter"
./expvarmon -ports="1234-1236" -vars="Goroutines" -self
2015-07-11 00:44:30 +08:00
./expvarmon -ports="https://user:pass@my.remote.app.com:443" -vars="Goroutines" -self
2015-05-04 03:26:32 +08:00
2015-05-04 02:24:56 +08:00
## Advanced usage
If you need to monitor more (or less) vars, you can specify them with -vars command line flag.
2015-05-04 02:46:59 +08:00
$ expvarmon -help
2015-07-11 00:44:30 +08:00
Usage of ./expvarmon:
-dummy=false: Use dummy (console) output
-i=5s: Polling interval
-ports="": Ports/URLs for accessing services expvars (start-end,port2,port3,https://host:port)
-self=false: Monitor itself
-vars="mem:memstats.Alloc,mem:memstats.Sys,mem:memstats.HeapAlloc,mem:memstats.HeapInuse,memstats.EnableGC,memstats.NumGC,duration:memstats.PauseTotalNs": Vars to monitor (comma-separated)
Examples:
./expvarmon -ports="80"
./expvarmon -ports="23000-23010,http://example.com:80-81" -i=1m
./expvarmon -ports="80,remoteapp:80" -vars="mem:memstats.Alloc,duration:Response.Mean,Counter"
./expvarmon -ports="1234-1236" -vars="Goroutines" -self
For more details and docs, see README: http://github.com/divan/expvarmon
So, yes, you can specify multiple ports, using '-' for ranges, and specify fully-qualified URLs for remote apps.
2015-05-04 02:24:56 +08:00
You can also monitor expvarmon itself, using -self flag.
2015-05-04 02:46:59 +08:00
2015-07-11 00:44:30 +08:00
### Basic Auth
If your expvar endpoint is protected by Basic Auth, you have two options:
- Set environmental variables *HTTP_USER* and *HTTP_PASSWORD* accordingly. These values will be applied to each endpoint.
- Embed your credentials to URL via command line flag: `-ports="http://user:pass@myapp:1234"`
2015-05-04 02:46:59 +08:00
### Vars
2015-05-04 06:22:54 +08:00
Expvarmon doesn't restrict you to monitor only memstats. You can publish your own counters and variables using [expvar.Publish() ](http://golang.org/pkg/expvar/#Publish ) method or using expvar wrappers libraries. Just pass your variables names as they appear in JSON to -var command line flag.
2015-05-04 03:26:32 +08:00
Notation is dot-separated, for example: **memstats.Alloc** for .MemStats.Alloc field. Quick link to runtime.MemStats documentation: http://golang.org/pkg/runtime/#MemStats
2015-05-04 06:22:54 +08:00
Expvar allows to export only basic types - structs, ints, floats, bools and strings. Ints are used for sparklines, and displayed as is. But you can specify modifier to make sure it will be rendered properly.
2015-05-04 02:46:59 +08:00
Vars are specified as a comma-separated list of var identifiers with (optional) modifiers.
| Modifier | Description |
| --------- | ----------- |
| mem: | renders int64 as memory string (KB, MB, etc) |
| duration: | renders int64 as time.Duration (1s, 2ms, 12h23h) |
| str: | doesn't display sparklines chart for this value, just display as string |