Turn Shell Commands into Real‑Time Visual Dashboards with Sampler

Sampler is a tool for executing shell commands, visualizing their output, and triggering alerts, configured via a simple YAML file.

Why you need it

You can sample any dynamic process directly from the terminal—watch database changes, monitor in‑flight MQ messages, trigger deployment scripts and receive notifications upon completion.

If you can obtain metrics with a shell command, Sampler can immediately visualize them.

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</code>
<code>sudo chmod +x /usr/local/bin/sampler

Linux

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

Note : Install the system library libasound2-dev for sound alerts (e.g., apt install libasound2-dev ).

Windows (experimental)

Run the .exe in an advanced console emulator such as Cmder.

Usage

Specify a shell command; Sampler runs it at the defined rate and uses the output for visualization. The basic three‑step workflow: Define shell commands in a YAML config file Run sampler -c config.yml Adjust component size and position in the UI

Components

Below are example configurations for each component type (images illustrate the UI).

Runchart

runcharts:
  - title: Search engine response time
    rate-ms: 500        # sampling rate, default = 1000
    scale: 2            # digits after decimal, default = 1
    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

Sparkline

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}'

Barchart

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}'

Gauge

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

Textbox

textboxes:
  - title: Local weather
    rate-ms: 10000
    sample: curl wttr.in?0ATQF
    border: false
    color: 178
  - title: Docker containers stats
    rate-ms: 500
    sample: docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.PIDs}}"

Asciibox

asciiboxes:
  - title: UTC time
    rate-ms: 500
    font: 3d
    border: false
    color: 43
    sample: env TZ=UTC date +%r

Extra Features

Triggers

Triggers allow conditional actions such as visual or sound alerts, or arbitrary shell commands.

gauges:
  - title: MINUTE 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

Besides sample, you can define init (run once before sampling) and transform (post‑process output) commands, enabling interactive sessions such as a persistent DB connection.

Basic mode

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

PTY mode

textboxes:
  - title: Neo4j polling
    pty: true
    init: cypher-shell -u neo4j -p pwd --format plain
    sample: RETURN rand();
    transform: echo "$sample" | tail -n 1
  - title: Top on a remote server
    pty: true
    init: ssh -i ~/user.pem [email protected]
    sample: top

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

Reusable 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()

Color Themes

theme: light
sparklines:
  - title: CPU usage
    sample: ps -A -o %cpu | awk '{s+=$1} END {print s}'

Real‑World Scenarios

Databases

Use an interactive init to open a persistent connection and reuse it for sampling.

MySQL

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

PostgreSQL

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

MongoDB

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

Neo4j

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

Kafka

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

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

SSH

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

JMX

# prerequisite: download jmxterm jar file
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}'