Sampler

https://github.com/sqshq/sampler
Admin
Sampler is a tool for shell commands execution, visualization and alerting, configured with a simple...
Tokens:6,641
Snippets:54
Trust Score:7.8
License:GPL-3.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### Configure multistep initialization

Source: https://github.com/sqshq/sampler/blob/master/README.md

Shows how to execute a sequence of commands before starting the sampling process, useful for complex tools like jmxterm.

```yaml
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
```

--------------------------------

### Install Sampler using Package Managers or Direct Download

Source: https://context7.com/sqshq/sampler/llms.txt

This section provides installation instructions for Sampler across different operating systems and environments. It includes commands for macOS (Homebrew, MacPorts), Linux (direct download), Windows (Chocolatey), and Docker.

```bash
# macOS with Homebrew
brew install sampler

# macOS with MacPorts
sudo port install sampler

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

# Windows with Chocolatey
choco install sampler

# Docker
docker build --tag sampler .
docker run --interactive --tty --volume $(pwd)/config.yml:/root/config.yml sampler --config /root/config.yml
```

--------------------------------

### Configure Interactive Shell Sessions

Source: https://context7.com/sqshq/sampler/llms.txt

Sets up persistent connections to databases or remote servers using init commands and PTY mode. Supports multistep initialization for complex session setups.

```yaml
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: Java application uptime
    multistep-init:
      - java -jar jmxterm-1.0.0-uber.jar
      - open host:port
      - bean java.lang:type=Runtime
    sample: get Uptime
```

--------------------------------

### Configure Sparkline Component for Compact Time-Series Data

Source: https://context7.com/sqshq/sampler/llms.txt

This YAML configuration sets up 'sparkline' components to display single-value time-series data compactly. It includes examples for CPU usage and free memory pages, defining their titles, positions, sampling rates, scales, and the shell commands to fetch the data.

```yaml
sparklines:
  - title: CPU usage
    position: [[0, 20], [22, 8]]
    rate-ms: 200
    scale: 0
    sample: ps -A -o %cpu | awk '{s+=$1} END {print s}'
  - title: Free memory pages
    position: [[22, 20], [23, 8]]
    rate-ms: 200
    scale: 0
    sample: memory_pressure | grep 'Pages free' | awk '{print $3}'
```

--------------------------------

### Configure Gauge Component for Progress Visualization

Source: https://context7.com/sqshq/sampler/llms.txt

This YAML configuration defines 'gauge' components to visualize progress between minimum and maximum values. Examples include minute progress and year progress, specifying titles, positions, sampling rates, scales, and scripts for current, maximum, and minimum values.

```yaml
gauges:
  - title: Minute progress
    position: [[45, 9], [35, 2]]
    rate-ms: 500
    scale: 2
    percent-only: false            # toggle display of current value, default = false
    color: 178
    cur:
      sample: date +%S             # current value script
    max:
      sample: echo 60              # maximum value script
    min:
      sample: echo 0               # minimum value script
  - title: Year progress
    position: [[45, 0], [35, 2]]
    cur:
      sample: date +%j
    max:
      sample: echo 365
    min:
      sample: echo 0
```

--------------------------------

### Set Sampler color theme

Source: https://context7.com/sqshq/sampler/llms.txt

Configures the color theme for the Sampler dashboard. This example sets the theme to 'light', overriding the default 'dark' theme.

```yaml
theme: light                       # options: dark (default), light
```

--------------------------------

### Monitor CPU usage with Sampler

Source: https://context7.com/sqshq/sampler/llms.txt

Monitors the overall CPU usage of the system. It uses the 'ps' command to get CPU percentage for all processes and 'awk' to sum them up.

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

--------------------------------

### Configure Barchart Component for Comparing Metrics

Source: https://context7.com/sqshq/sampler/llms.txt

This YAML configuration defines a 'barchart' component for comparing metrics across categories using horizontal bars. The example shows local network activity, detailing UDP and TCP bytes in/out, with specified titles, positions, sampling rates, scales, and the shell commands for data retrieval.

```yaml
barcharts:
  - title: Local network activity
    position: [[45, 20], [35, 8]]
    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}'
```

--------------------------------

### Run Sampler with Configuration and Variables

Source: https://context7.com/sqshq/sampler/llms.txt

Demonstrates basic usage of the Sampler tool. It shows how to run Sampler with a YAML configuration file, how to pass custom environment variables, and how to check the tool's version.

```bash
# Run sampler with a configuration file
sampler -c config.yml

# Run with custom variables
sampler -c config.yml -e "host=localhost" -e "port=8080"

# Show version
sampler --version
```

--------------------------------

### Database connection recipes

Source: https://github.com/sqshq/sampler/blob/master/README.md

Standardized configurations for connecting to MySQL, PostgreSQL, and MongoDB using interactive shell sessions.

```yaml
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();
```

--------------------------------

### Configure visual themes and sparklines

Source: https://github.com/sqshq/sampler/blob/master/README.md

Sets the global UI theme and defines a sparkline chart to visualize CPU usage trends.

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

--------------------------------

### Configure interactive shell polling

Source: https://github.com/sqshq/sampler/blob/master/README.md

Demonstrates how to use 'init' and 'sample' commands to maintain an interactive session with databases like MongoDB or Neo4j. PTY mode is utilized for commands that require a terminal environment.

```yaml
textboxes:
  - title: MongoDB polling
    rate-ms: 500
    init: mongo --quiet --host=localhost test
    sample: Date.now();
    transform: echo result = $sample
  - title: Neo4j polling
    pty: true
    init: cypher-shell -u neo4j -p pwd --format plain
    sample: RETURN rand();
    transform: echo "$sample" | tail -n 1
```

--------------------------------

### Manage Variables and Command Line Overrides

Source: https://context7.com/sqshq/sampler/llms.txt

Defines reusable configuration variables and demonstrates how to override them via the command line interface.

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

```bash
sampler -c config.yml -e "mongoconnection=mongo --host=production test"
```

--------------------------------

### Complete Sampler dashboard configuration

Source: https://context7.com/sqshq/sampler/llms.txt

A comprehensive Sampler dashboard configuration demonstrating multiple component types including runcharts for search engine response times, sparklines for CPU usage, gauges for year progress, textboxes for Docker stats, and asciiboxes for UTC time. It also includes a trigger for latency threshold breaches.

```yaml
theme: dark

variables:
  mongoconnection: mongo --quiet --host=localhost test

runcharts:
  - title: Search engine response time
    position: [[0, 0], [45, 19]]
    rate-ms: 500
    scale: 2
    legend:
      enabled: true
      details: false
    triggers:
      - title: Latency threshold exceeded
        condition: echo "$prev < 0.8 && $cur > 0.8" |bc -l
        actions:
          terminal-bell: true
          sound: true
          visual: true
    items:
      - label: GOOGLE
        color: 178
        sample: curl -o /dev/null -s -w '%{time_total}' https://www.google.com
      - label: YAHOO
        sample: curl -o /dev/null -s -w '%{time_total}' https://search.yahoo.com

sparklines:
  - title: CPU usage
    position: [[0, 20], [22, 8]]
    rate-ms: 200
    scale: 0
    sample: ps -A -o %cpu | awk '{s+=$1} END {print s}'

gauges:
  - title: YEAR PROGRESS
    position: [[45, 0], [35, 2]]
    cur:
      sample: date +%j
    max:
      sample: echo 365
    min:
      sample: echo 0

textboxes:
  - title: Docker containers stats
    position: [[0, 29], [45, 10]]
    rate-ms: 500
    sample: docker stats --no-stream --format "table {{.Name}}	{{.CPUPerc}}	{{.MemUsage}}	{{.PIDs}}"

asciiboxes:
  - title: UTC time
    position: [[45, 12], [35, 7]]
    rate-ms: 500
    font: 3d
    border: false
    sample: env TZ=UTC date +%r
```

--------------------------------

### Connect to Neo4j using cypher-shell

Source: https://context7.com/sqshq/sampler/llms.txt

Establishes a connection to Neo4j using the cypher-shell command. It defines a variable for the connection string and then uses it to execute a sample query returning a random number.

```yaml
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
```

--------------------------------

### Define UI Components in YAML

Source: https://context7.com/sqshq/sampler/llms.txt

Configures visual components like textboxes and asciiboxes to display command outputs. These components support custom positioning, refresh rates, and styling options.

```yaml
textboxes:
  - title: Docker containers stats
    position: [[0, 29], [45, 10]]
    rate-ms: 500
    sample: docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.PIDs}}"
  - title: Local weather
    position: [[69, 31], [13, 7]]
    rate-ms: 10000
    sample: curl wttr.in?0ATQF
    border: false
    color: 178

asciiboxes:
  - title: UTC time
    position: [[45, 12], [35, 7]]
    rate-ms: 500
    font: 3d
    border: false
    color: 43
    sample: env TZ=UTC date +%r
```

--------------------------------

### Implement Triggers and Alerts

Source: https://context7.com/sqshq/sampler/llms.txt

Defines conditional logic for charts and gauges to trigger visual, audio, or script-based alerts. Uses shell expressions to evaluate state changes.

```yaml
runcharts:
  - title: SEARCH ENGINE RESPONSE TIME (sec)
    triggers:
      - title: Latency threshold exceeded
        condition: echo "$prev < 0.3 && $cur > 0.3" |bc -l
        actions:
          terminal-bell: true
          sound: true
          visual: true
          script: 'say alert: ${label} latency exceeded ${cur} second'
```

--------------------------------

### Configure Barchart Widget

Source: https://github.com/sqshq/sampler/blob/master/README.md

Sets up a barchart to compare multiple data points, such as network activity. It uses shell commands to aggregate data and displays them in a bar format.

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

--------------------------------

### Execute remote TOP command via SSH

Source: https://github.com/sqshq/sampler/blob/master/README.md

Connects to a remote server using an SSH key and runs the top command. Requires a valid SSH key path and remote server credentials.

```yaml
variables:
  sshconnection: ssh -i ~/my-key-pair.pem ec2-user@1.2.3.4
textboxes:
  - title: SSH
    pty: true
    init: $sshconnection
    sample: top
```

--------------------------------

### Configure Textbox Widget

Source: https://github.com/sqshq/sampler/blob/master/README.md

Displays raw text output from shell commands in a box. Useful for status summaries or formatted tables like Docker container stats.

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

--------------------------------

### Configure Gauge Widget

Source: https://github.com/sqshq/sampler/blob/master/README.md

Creates a gauge to represent progress or percentage-based metrics. It requires current, minimum, and maximum value samples to calculate the display state.

```yaml
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
```

--------------------------------

### Define and use configuration variables

Source: https://github.com/sqshq/sampler/blob/master/README.md

Extracts repeated connection strings into a variables section to simplify configuration maintenance and improve readability.

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

--------------------------------

### Configure Asciibox Widget

Source: https://github.com/sqshq/sampler/blob/master/README.md

Renders text using ASCII art fonts. Ideal for displaying large, readable status information like time or system status.

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

--------------------------------

### Monitor remote server using SSH

Source: https://context7.com/sqshq/sampler/llms.txt

Monitors a remote server's processes using the 'top' command via SSH. It defines an SSH connection variable including the key pair and IP address, then uses it to run the 'top' command in a textbox.

```yaml
variables:
  sshconnection: ssh -i ~/my-key-pair.pem ec2-user@1.2.3.4

textboxes:
  - title: Remote server top
    pty: true
    init: $sshconnection
    sample: top
```

--------------------------------

### Configure Runchart Component for Time-Series Data Visualization

Source: https://context7.com/sqshq/sampler/llms.txt

This YAML configuration defines a 'runchart' component for visualizing time-series data. It specifies the chart's title, position, sampling rate, scale, legend options, and individual data items with their respective sampling commands.

```yaml
runcharts:
  - title: Search engine response time
    position: [[0, 0], [45, 19]]  # [[x, y], [width, height]]
    rate-ms: 500                   # sampling rate in milliseconds, default = 1000
    scale: 2                       # decimal digits after point, default = 1
    legend:
      enabled: true                # show item labels, default = true
      details: false               # show cur/min/max/dlt statistics, default = true
    items:
      - label: GOOGLE
        color: 178                 # 8-bit color number
        sample: curl -o /dev/null -s -w '%{time_total}' https://www.google.com
      - 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
```

--------------------------------

### Monitor Docker container statistics

Source: https://context7.com/sqshq/sampler/llms.txt

Displays real-time statistics for Docker containers. It uses the 'docker stats' command with specific formatting to show CPU usage, memory, network I/O, block I/O, and PIDs for each container.

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

--------------------------------

### Display Docker container statistics

Source: https://github.com/sqshq/sampler/blob/master/README.md

Retrieves real-time CPU, memory, and I/O usage for Docker containers using the docker stats command. Outputs data in a formatted table.

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

--------------------------------

### Monitor Kafka consumer group lag

Source: https://context7.com/sqshq/sampler/llms.txt

Monitors the lag for Kafka consumer groups. It sets up a Kafka connection variable and then uses it to describe consumer groups, extracting the lag for specific groups using awk.

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

--------------------------------

### Configure Runchart Widget

Source: https://github.com/sqshq/sampler/blob/master/README.md

Defines a runchart to track time-series data. It samples multiple endpoints using curl and displays them as a line chart with configurable legends and sampling rates.

```yaml
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
```

--------------------------------

### Configure search engine latency monitoring

Source: https://github.com/sqshq/sampler/blob/master/README.md

Defines a runchart to monitor response times for external services. It includes trigger conditions to alert users via sound or visual notifications when latency thresholds are exceeded.

```yaml
runcharts:
  - title: SEARCH ENGINE RESPONSE TIME (sec)
    rate-ms: 200
    items:
      - label: GOOGLE
        sample: curl -o /dev/null -s -w '%{time_total}'  https://www.google.com
      - label: YAHOO
        sample: curl -o /dev/null -s -w '%{time_total}'  https://search.yahoo.com     
    triggers:
      - title: Latency threshold exceeded
        condition: echo "$prev < 0.3 && $cur > 0.3" |bc -l
        actions:
          terminal-bell: true
          sound: true
          visual: true
          script: 'say alert: ${label} latency exceeded ${cur} second'
```

--------------------------------

### Configure Widget Triggers

Source: https://github.com/sqshq/sampler/blob/master/README.md

Adds conditional logic to widgets to perform actions like playing sounds or executing shell scripts when specific conditions are met.

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

--------------------------------

### Configure Sparkline Widget

Source: https://github.com/sqshq/sampler/blob/master/README.md

Configures sparkline widgets to visualize continuous data streams like CPU usage or memory metrics. These are lightweight components that execute shell scripts at specified intervals.

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

--------------------------------

### Monitor Kafka consumer group lag

Source: https://github.com/sqshq/sampler/blob/master/README.md

Tracks Kafka consumer group lag by executing the kafka-consumer-groups command and parsing the output with awk. Requires KAFKA_HOME to be set.

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

--------------------------------

### Monitor Java application uptime via JMX

Source: https://github.com/sqshq/sampler/blob/master/README.md

Retrieves Java application uptime using the jmxterm utility. Requires the jmxterm jar file and a connection to a local or remote JMX port.

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