How to Quickly Visualize Shell Commands with Sampler – Install, Configure, and Use

Why Use Sampler?

Sampler is a command‑line utility that executes arbitrary shell commands at a configurable rate, captures their output, and presents the results in a visual UI with optional sound or terminal‑bell alerts. It is useful for quickly observing database changes, monitoring message‑queue latency, or triggering deployment scripts without setting up a full monitoring stack.

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.3-linux-amd64 -O /usr/local/bin/sampler
sudo chmod +x /usr/local/bin/sampler

Note: libasound2‑dev must be installed for sound alerts (e.g., apt install libasound2-dev).

Windows (experimental)

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

Basic Usage

Sampler operates in three steps:

Define shell commands in a YAML configuration file.

Run sampler -c config.yml to start sampling.

Adjust component size and position in the UI.

Component Types

Runchart

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

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 can fire conditional actions such as visual or sound alerts, or run arbitrary scripts.

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

Sampler allows init commands that run once before sampling and transform commands that post‑process output. PTY mode can be enabled when stdin is not a terminal.

textboxes:
  - title: Neo4j polling
    pty: true
    init: cypher-shell -u neo4j -p pwd --format plain
    sample: RETURN rand();
    transform: echo "$sample" | tail -n 1

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
    transform: echo $sample | tr -dc '0-9' | awk '{printf "%.1f min", $1/1000/60}'

Variables

Repeated patterns can be extracted into a variables section and referenced with $varname or overridden via the -v/--variable flag.

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

Real‑World Scenarios

Database Monitoring

Examples show how to keep a persistent connection to MySQL, PostgreSQL, MongoDB, or Neo4j and sample values such as random numbers or status counts.

# 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();

Kafka Lag Monitoring

variables:
  kafka_connection: $KAFKA_HOME/bin/kafka-consumer-groups --bootstrap-server localhost:9092
runcharts:
  - title: Kafka lag per consumer group
    rate-ms: 5000
    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 Container Stats

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

Remote SSH Monitoring

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

JMX Monitoring

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

Sampler therefore provides a fast, script‑driven way to collect metrics, visualize them, and react to conditions without the overhead of a full‑blown monitoring stack.