Turn Shell Commands into Real‑Time Visual Dashboards with Sampler

What is Sampler?

Sampler is a lightweight tool that executes shell commands, visualizes their output and can trigger alerts. Configuration is done with a simple YAML file.

Why use Sampler?

It lets you sample any dynamic process from the terminal—monitor database changes, MQ messages, trigger deployment scripts and receive notifications. If you can obtain a metric with a shell command, Sampler can instantly visualize it.

Installation

macOS: brew cask install sampler or

sudo curl -Lo /usr/local/bin/sampler https://github.com/sqshq/sampler/releases/download/v1.0.3/sampler-1.0.3-darwin-amd64
sudo chmod +x /usr/local/bin/sampler

Linux:

sudo wget https://github.com/sqshq/sampler/releases/download/v1.0.3/sampler-1.0-linux-amd64 -O /usr/local/bin/sampler
sudo chmod +x /usr/local/bin/sampler

Note: libasound2-dev is required for sound alerts.

Windows (experimental): download the .exe and run it in an advanced console such as Cmder.

Basic Usage

Define shell commands in a YAML file, run sampler -c config.yml, then adjust component size and position in the UI.

Three‑step process: Define commands in the YAML configuration. Run sampler -c config.yml . Resize and move components in the UI.

Component Types

Sampler supports several visual components, each configured in YAML.

Runcharts

runcharts:
  - title: Search engine response time
    rate-ms: 500
    scale: 2
    legend:
      enabled: true
      details: false
    items:
      - label: GOOGLE
        sample: curl -o /dev/null -s -w '%{time_total}' https://www.google.com
        color: 178
      - 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

Sparklines

sparklines:
  - title: CPU usage
    rate-ms: 200
    scale: 0
    sample: ps -A -o %cpu | awk '{s+=$1} END {print s}'
  - title: Free memory pages
    rate-ms: 200
    scale: 0
    sample: memory_pressure | grep 'Pages free' | awk '{print $3}'

Barcharts

barcharts:
  - title: Local network activity
    rate-ms: 500
    scale: 0
    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}'

Gauges

gauges:
  - title: Minute progress
    rate-ms: 500
    scale: 2
    percent-only: false
    color: 178
    cur:
      sample: date +%S
    max:
      sample: echo 60
    min:
      sample: echo 0
  - title: Year progress
    cur:
      sample: date +%j
    max:
      sample: echo 365
    min:
      sample: echo 0

Textboxes and Asciiboxes

Examples include local weather, Docker container stats, custom scripts, and ASCII‑art clocks.

Triggers

Components can fire conditional actions such as terminal bells, sound alerts, visual notifications, or arbitrary scripts.

gauges:
  - title: CLOCK PROGRESS
    position: [[0,18],[80,0]]
    cur:
      sample: date +%S
    max:
      sample: echo 60
    min:
      sample: echo 0
    triggers:
      - title: CLOCK BELL EVERY MINUTE
        condition: '[ $label == "cur" ] && [ $cur -eq 0 ] && echo 1 || echo 0'
        actions:
          terminal-bell: true
          sound: true
          visual: false
          script: say -v samantha `date +%I:%M%p`

Interactive Shell Support

Sampler can run an init command once, then repeatedly execute sample commands. PTY mode enables true interactive sessions for databases or remote SSH.

textboxes:
  - title: MongoDB polling
    rate-ms: 500
    init: mongo --quiet --host=localhost test
    sample: Date.now();
    transform: echo result = $sample

Multi‑step Init

textboxes:
  - title: Java application uptime
    multistep-init:
      - java -jar jmxterm-1.0.0-uber.jar
      - open host:port
      - bean java.lang:type=Runtime
    sample: get Uptime

Variables

Repeated patterns can be extracted into a variables section and referenced with $varname. Command‑line -v/--variable overrides are also supported.

variables:
  mongoconnection: mongo --quiet --host=localhost test
barcharts:
  - title: MongoDB documents by status
    items:
      - label: IN_PROGRESS
        init: $mongoconnection
        sample: db.getCollection('events').find({status:'IN_PROGRESS'}).count()
      - label: SUCCESS
        init: $mongoconnection
        sample: db.getCollection('events').find({status:'SUCCESS'}).count()
      - label: FAIL
        init: $mongoconnection
        sample: db.getCollection('events').find({status:'FAIL'}).count()

Database and Service Examples

Sampler can monitor MySQL, PostgreSQL, MongoDB, Neo4j, Kafka, Docker, SSH, and JMX by defining appropriate init and sample commands.

# MySQL example
variables:
  mysql_connection: mysql -u root -s --database mysql --skip-column-names
sparklines:
  - title: MySQL (random number)
    pty: true
    init: $mysql_connection
    sample: select rand();

# PostgreSQL example
variables:
  PGPASSWORD: pwd
  postgres_connection: psql -h localhost -U postgres --no-align --tuples-only
sparklines:
  - title: PostgreSQL (random number)
    init: $postgres_connection
    sample: select random();

# MongoDB example
variables:
  mongo_connection: mongo --quiet --host=localhost test
sparklines:
  - title: MongoDB (random number)
    init: $mongo_connection
    sample: Math.random();

# Neo4j example
variables:
  neo4j_connection: cypher-shell -u neo4j -p pwd --format plain
sparklines:
  - title: Neo4j (random number)
    pty: true
    init: $neo4j_connection
    sample: RETURN rand();
    transform: echo "$sample" | tail -n 1

# Kafka lag example
variables:
  kafka_connection: $KAFKA_HOME/bin/kafka-consumer-groups --bootstrap-server localhost:9092
runcharts:
  - title: Kafka lag per consumer group
    rate-ms: 5000
    scale: 0
    items:
      - label: A->B
        sample: $kafka_connection --group group_a --describe | awk 'NR>1 {sum += $5} END {print sum}'
      - label: B->C
        sample: $kafka_connection --group group_b --describe | awk 'NR>1 {sum += $5} END {print sum}'
      - label: C->D
        sample: $kafka_connection --group group_c --describe | awk 'NR>1 {sum += $5} END {print sum}'

# Docker stats example
textboxes:
  - title: Docker containers stats
    sample: docker stats --no-stream --format "table {{.Name}}	{{.CPUPerc}}	{{.MemPerc}}	{{.MemUsage}}	{{.NetIO}}	{{.BlockIO}}	{{.PIDs}}"

# SSH top example
variables:
  sshconnection: ssh -i ~/my-key-pair.pem [email protected]
textboxes:
  - title: SSH
    pty: true
    init: $sshconnection
    sample: top

# JMX uptime example
# prerequisite: download jmxterm jar
textboxes:
  - title: Java application uptime
    multistep-init:
      - java -jar jmxterm-1.0.0-uber.jar
      - open host:port
      - bean java.lang:type=Runtime
    sample: get Uptime
    transform: echo $sample | tr -dc '0-9' | awk '{printf "%.1f min", $1/1000/60}'