From 6e57383991b1e0172bcc2738850feff5716dcd92 Mon Sep 17 00:00:00 2001 From: sqshq Date: Wed, 24 Apr 2019 20:03:47 -0400 Subject: [PATCH] README and CI config updates --- .travis.yml | 17 +++++++ README.md | 141 ++++++++++++++++++++++++++++++++++++++++++---------- 2 files changed, 132 insertions(+), 26 deletions(-) create mode 100644 .travis.yml diff --git a/.travis.yml b/.travis.yml new file mode 100644 index 0000000..f15d606 --- /dev/null +++ b/.travis.yml @@ -0,0 +1,17 @@ +language: go +go: + - 1.11.x + - master +os: + - linux + - osx +addons: + apt: + packages: + - libasound2-dev +dist: trusty +sudo: false +install: true +script: + - env GO111MODULE=on go build + - env GO111MODULE=on go test -v ./... diff --git a/README.md b/README.md index e00754f..97bd1d9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# Sampler. Visualization for any shell command. +# Sampler. Visualization for any shell command. +[![Build Status](https://travis-ci.com/sqshq/sampler.svg?token=LdyRhxxjDFnAz1bJg8fq&branch=master)](https://travis-ci.com/sqshq/sampler) [![Go Report Card](https://goreportcard.com/badge/github.com/sqshq/sampler)](https://goreportcard.com/report/github.com/sqshq/sampler) Sampler is a tool for shell commands execution, visualization and alerting. Configured with a simple YAML file. @@ -13,36 +14,124 @@ Sampler is a tool for shell commands execution, visualization and alerting. Conf ### Windows ... ## Usage -Using Sampler is basically a three-step process: +You specify shell commands, Sampler executes them with a required rate. The output is used for visualization. + +One can sample any dynamic process right from the terminal - observe changes in the database, monitor MQ in-flight messages, trigger deployment process and get notification when it's done. + +Using Sampler is basically a 3-step process: - Define your configuration in a YAML file - Run `sampler -c config.yml` -- Adjust components size and location, if needed +- Adjust components size and location on UI ## Configuration -Links to the sections below +- [Components](#components) + - [Runchart](#runchart) + - [Sparkline](#sparkline) + - [Barchart](#barchart) + - [Gauge](#gauge) + - [Textbox](#textbox) + - [Asciibox](#asciibox) +- [Bells and whistles](#bells-and-whistles) + - [Triggers (conditional actions)](#triggers) + - [Interactive shell (for database interaction, remote server access, etc)](#interactive-shell-support) + - [Variables](#variables) + - [Color theme](#color-theme) +- [Real-world examples (contributions welcome)](#real-world-examples) -### Runchart +### Components +#### Runchart +```yml +runcharts: + - title: Search engine response time + rate-ms: 500 # sampling rate, default = 1000 + scale: 2 # number of digits after sample decimal point, default = 1 + legend: + enabled: true # enables item labels, default = true + details: false # enables item statistics: cur/min/max/dlt values, default = true + items: + - label: GOOGLE + sample: curl -o /dev/null -s -w '%{time_total}' https://www.google.com + color: 178 # 8-bit color number, default one is chosen from a pre-defined palette + - label: YAHOO + sample: curl -o /dev/null -s -w '%{time_total}' https://search.yahoo.com + - label: BING + sample: curl -o /dev/null -s -w '%{time_total}' https://www.bing.com +``` +#### Sparkline +```yml +sparklines: +- title: CPU usage + rate-ms: 200 # sampling rate, default = 1000 + scale: 0 # number of digits after sample decimal point, default = 1 + sample: ps -A -o %cpu | awk '{s+=$1} END {print s}' +``` +#### Barchart +```yml +barcharts: + - title: Local network activity + rate-ms: 500 # sampling rate, default = 1000 + scale: 0 # number of digits after sample decimal point, default = 1 + items: + - label: UDP bytes in + sample: nettop -J bytes_in -l 1 -m udp | awk '{sum += $4} END {print sum}' + - label: UDP bytes out + sample: nettop -J bytes_out -l 1 -m udp | awk '{sum += $4} END {print sum}' + - label: TCP bytes in + sample: nettop -J bytes_in -l 1 -m tcp | awk '{sum += $4} END {print sum}' + - label: TCP bytes out + sample: nettop -J bytes_out -l 1 -m tcp | awk '{sum += $4} END {print sum}' +``` +#### Gauge +```yml +gauges: + - title: Minute progress + rate-ms: 500 # sampling rate, default = 1000 + scale: 2 # number of digits after sample decimal point, default = 1 + color: 39 # 8-bit color number, default one is chosen from a pre-defined palette + cur: + sample: date +%S # sample script for current value + max: + sample: echo 60 # sample script for max value + min: + sample: echo 0 # sample script for min value +``` +#### Textbox +```yml +textboxes: + - title: Local weather + rate-ms: 10000 # sampling rate, default = 1000 + sample: curl wttr.in?0ATQF + border: false # border around the item, default = true + color: 178 # 8-bit color number, default is white + - title: Docker containers stats + rate-ms: 500 + sample: docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.PIDs}}" +``` +#### Asciibox +```yml +asciiboxes: + - title: UTC time + rate-ms: 500 # sampling rate, default = 1000 + font: 3d # font type, default = 2d + color: 178 # 8-bit color number, default is white + sample: env TZ=UTC date +%r +``` + +### Bells and whistles + +#### Triggers +Triggers allow to perform conditional actions, like visual/sound alerts or an arbitrary shell command. + +#### Interactive shell support +In addition to the `sample` command, one can specify `init` command (executed only once before sampling) and `transform` command (to post-process `sample` command output). That covers interactive shell use case, e.g. to establish connection to a database only once, and then perform polling within interactive shell session. MongoDB example: ... + +#### Variables +If the configuration file contains repeated patterns, they can be extracted into the `variables` section. +Also variables can be specified using `-v`/`--variable` flag on startup, and any system environment variables will also be available in the scripts. + +#### Color theme ... -### Sparkline + +### Real-world examples ... -### Barchart -... -### Gauge -... -### Textbox -... -### Asciibox -... -### Triggers -Perform conditional actions, like visual/sound alerts or a shell command - -### Interactive shell -Allows efficient database polling, remote server access, etc - -### Variables -Extract variables or repeated patterns into YAML variables or command line flags - - - -