{ "componentChunkName": "component---src-templates-issues-tsx", "path": "/issues/499", "result": {"data":{"issuesJson":{"id":"fbee3b2a-2071-5e0f-b563-1a2ee2c736cd","title":"sqshq/sampler: Sampler 是一个用于 shell 命令执行、可视化和警报的工具。使用简单的 YAML 文件进行配置。","number":499,"bodyHTML":"

\n

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Repos	sqshq/sampler
Views	$\"views\"$
Stars	$\"stars\"$
Forks	$\"forks\"$
License	$\"license\"$
UpdatedAt	$\"last-commit\"$
CreatedAt	$\"create-at\"$

\n\n

\n

\n

\n

Sampler. Visualization for any shell command.

\n

$\"Build$ $\"Go$

\n

Sampler is a tool for shell commands execution, visualization and alerting. Configured with a simple YAML file.

\n

\n

Why do I need it?

\n

One can sample any dynamic process right from the terminal — observe changes in the database, monitor MQ in-flight messages, trigger a deployment script and get notification when it's done.

\n

If there is a way to get a metric using a shell command, then it can be visualized with Sampler momentarily.

\n

Installation

\n

macOS

\n

\n

brew install sampler

\n

\n

sudo port install sampler

\n

or

\n

sudo curl -Lo /usr/local/bin/sampler https://github.com/sqshq/sampler/releases/download/v1.1.0/sampler-1.1.0-darwin-amd64\nsudo chmod +x /usr/local/bin/sampler

\n

Linux

\n

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

\n

Note: libasound2-dev system library is required to be installed for Sampler to play a trigger sound tone. Usually the library is in place, but if not - you can install it with your favorite package manager, e.g apt install libasound2-dev

\n

Packaging status

\n

Fedora sudo dnf install golang-github-sqshq-sampler (F31+)
Arch yay -S sampler

\n

Windows (experimental)

\n

Recommended to use with advanced console emulators, e.g. Cmder

\n

\n

choco install sampler

\n

or

\n

\n

Docker

\n

# Create a configuration file\nvim config.yml\n\n# Build the container image\ndocker build --tag sampler .\n\n# Run a container\ndocker run --interactive --tty --volume $(pwd)/config.yml:/root/config.yml sampler --config /root/config.yml\n

\n

Usage

\n

You specify shell commands, Sampler executes them with a required rate. The output is used for visualization.

\n

Using Sampler is basically a 3-step process:

\n

Define your shell commands in a YAML configuration file
Run sampler -c config.yml
Adjust components size and location on UI

\n

But there are so many monitoring systems already

\n

Sampler is by no means an alternative to full-scale monitoring systems, but rather an easy to setup development tool.

\n

If spinning up and configuring Prometheus with Grafana is complete overkill for you task, Sampler might be the right solution. No servers, no databases, no deploy - you specify shell commands, and it just works.

\n

Then it should be installed on every server I monitor?

\n

No, you can run Sampler on local, but still gather telemetry from multiple remote machines. Any visualization might have init command, where you can ssh to a remote server. See the SSH example

\n

Contents

\n

Components\n
- Runchart
- Sparkline
- Barchart
- Gauge
- Textbox
- Asciibox
\n
Bells and whistles\n
\n
Real-world recipes (contributions welcome!)\n
- Databases (MySQL, PostgreSQL, MongoDB, Neo4j)
- Kafka
- Docker
- SSH
- JMX
\n

\n

Components

\n

The following is a list of configuration examples for each component type, with macOS compatible sampling scripts.

\n

Runchart

\n

\n

runcharts:\n  - title: Search engine response time\n    rate-ms: 500        # sampling rate, default = 1000\n    scale: 2            # number of digits after sample decimal point, default = 1\n    legend:\n      enabled: true     # enables item labels, default = true\n      details: false    # enables item statistics: cur/min/max/dlt values, default = true\n    items:\n      - label: GOOGLE\n        sample: curl -o /dev/null -s -w '%{time_total}'  https://www.google.com\n        color: 178      # 8-bit color number, default one is chosen from a pre-defined palette\n      - label: YAHOO\n        sample: curl -o /dev/null -s -w '%{time_total}'  https://search.yahoo.com\n      - label: BING\n        sample: curl -o /dev/null -s -w '%{time_total}'  https://www.bing.com

\n

Sparkline

\n

$\"sparkline\"$

\n

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

\n

Barchart

\n

\n

barcharts:\n  - title: Local network activity\n    rate-ms: 500        # sampling rate, default = 1000\n    scale: 0            # number of digits after sample decimal point, default = 1\n    items:\n      - label: UDP bytes in\n        sample: nettop -J bytes_in -l 1 -m udp | awk '{sum += $4} END {print sum}'\n      - label: UDP bytes out\n        sample: nettop -J bytes_out -l 1 -m udp | awk '{sum += $4} END {print sum}'\n      - label: TCP bytes in\n        sample: nettop -J bytes_in -l 1 -m tcp | awk '{sum += $4} END {print sum}'\n      - label: TCP bytes out\n        sample: nettop -J bytes_out -l 1 -m tcp | awk '{sum += $4} END {print sum}'

\n

Gauge

\n

\n

gauges:\n  - title: Minute progress\n    rate-ms: 500        # sampling rate, default = 1000\n    scale: 2            # number of digits after sample decimal point, default = 1\n    percent-only: false # toggle display of the current value, default = false\n    color: 178          # 8-bit color number, default one is chosen from a pre-defined palette\n    cur:\n      sample: date +%S  # sample script for current value\n    max:\n      sample: echo 60   # sample script for max value\n    min:\n      sample: echo 0    # sample script for min value\n  - title: Year progress\n    cur:\n      sample: date +%j\n    max:\n      sample: echo 365\n    min:\n      sample: echo 0

\n

Textbox

\n

\n

textboxes:\n  - title: Local weather\n    rate-ms: 10000      # sampling rate, default = 1000\n    sample: curl wttr.in?0ATQF\n    border: false       # border around the item, default = true\n    color: 178          # 8-bit color number, default is white\n  - title: Docker containers stats\n    rate-ms: 500\n    sample: docker stats --no-stream --format \"table {{.Name}}\\t{{.CPUPerc}}\\t{{.MemUsage}}\\t{{.PIDs}}\"

\n

Asciibox

\n

\n

asciiboxes:\n  - title: UTC time\n    rate-ms: 500        # sampling rate, default = 1000\n    font: 3d            # font type, default = 2d\n    border: false       # border around the item, default = true    \n    color: 43           # 8-bit color number, default is white\n    sample: env TZ=UTC date +%r

\n

Bells and whistles

\n

Triggers

\n

Triggers allow to perform conditional actions, like visual/sound alerts or an arbitrary shell command.
\nThe following examples illustrate the concept.

\n

Clock gauge, which shows minute progress and announces current time at the beginning of each minute

\n

gauges:\n  - title: MINUTE PROGRESS\n    position: [[0, 18], [80, 0]]  \n    cur:\n      sample: date +%S\n    max:\n      sample: echo 60\n    min:\n      sample: echo 0\n    triggers:\n      - title: CLOCK BELL EVERY MINUTE\n        condition: '[ $label == \"cur\" ] && [ $cur -eq 0 ] && echo 1 || echo 0'  # expects \"1\" as TRUE indicator\n        actions:\n          terminal-bell: true  # standard terminal bell, default = false\n          sound: true    # NASA quindar tone, default = false\n          visual: false  # notification with current value on top of the component area, default = false\n          script: say -v samantha `date +%I:%M%p`  # an arbitrary script, which can use $cur, $prev and $label variables

\n

Search engine latency chart, which alerts user when latency exceeds a threshold

\n

runcharts:\n  - title: SEARCH ENGINE RESPONSE TIME (sec)\n    rate-ms: 200\n    items:\n      - label: GOOGLE\n        sample: curl -o /dev/null -s -w '%{time_total}'  https://www.google.com\n      - label: YAHOO\n        sample: curl -o /dev/null -s -w '%{time_total}'  https://search.yahoo.com     \n    triggers:\n      - title: Latency threshold exceeded\n        condition: echo \"$prev < 0.3 && $cur > 0.3\" |bc -l  # expects \"1\" as TRUE indicator\n        actions:\n          terminal-bell: true  # standard terminal bell, default = false\n          sound: true   # NASA quindar tone, default = false\n          visual: true  # visual notification on top of the component area, default = false\n          script: 'say alert: ${label} latency exceeded ${cur} second' # an arbitrary script, which can use $cur, $prev and $label variables

\n

Interactive shell support

\n

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.

\n

Basic mode

\n

textboxes:\n  - title: MongoDB polling\n    rate-ms: 500\n    init: mongo --quiet --host=localhost test # executes only once to start the interactive session\n    sample: Date.now();                       # executes with a required rate, in scope of the interactive session\n    transform: echo result = $sample          # executes in scope of local session, $sample variable is available for transformation

\n

PTY mode

\n

In some cases interactive shell won't work, because its stdin is not a terminal. We can fool it, using PTY mode:

\n

textboxes:\n  - title: Neo4j polling\n    pty: true  # enables pseudo-terminal mode, default = false\n    init: cypher-shell -u neo4j -p pwd --format plain\n    sample: RETURN rand();\n    transform: echo \"$sample\" | tail -n 1\n  - title: Top on a remote server\n    pty: true  # enables pseudo-terminal mode, default = false\n    init: ssh -i ~/user.pem ec2-user@1.2.3.4\n    sample: top

\n

Multistep init

\n

It is also possible to execute multiple init commands one after another, before you start sampling.

\n

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

\n

Variables

\n

If the configuration file contains repeated patterns, they can be extracted into the variables section.
\nAlso variables can be specified using -v/--variable flag on startup, and any system environment variables will also be available in the scripts.

\n

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

\n

Color theme

\n

$\"light-theme\"$

\n

theme: light # default = dark\nsparklines:\n  - title: CPU usage\n    sample: ps -A -o %cpu | awk '{s+=$1} END {print s}'

\n

Real-world recipes

\n

Databases

\n

The following are different database connection examples. Interactive shell (init script) usage is recommended to establish connection only once and then reuse it during sampling.

\n

MySQL

\n

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

\n

\n

PostgreSQL

\n

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

\n

\n

MongoDB

\n

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

\n

\n

Neo4j

\n

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

\n

\n

Kafka

\n

Kafka lag per consumer group

\n

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

\n

\n

Docker

\n

Docker containers stats (CPU, MEM, O/I)

\n

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

\n

\n

SSH

\n

TOP command on a remote server

\n

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

\n

\n

JMX

\n

Java application uptime example

\n

# prerequisite: download [jmxterm jar file](https://docs.cyclopsgroup.org/jmxterm)\n\ntextboxes:\n  - title: Java application uptime\n    multistep-init:\n      - java -jar jmxterm-1.0.0-uber.jar\n      - open host:port # or local PID\n      - bean java.lang:type=Runtime\n    sample: get Uptime\n    transform: echo $sample | tr -dc '0-9' | awk '{printf \"%.1f min\", $1/1000/60}'

\n

","updatedAt":"2025-05-22T01:47:30Z","upvoteCount":null,"author":{"login":"eryajf","avatarUrl":"https://avatars.githubusercontent.com/u/33259379?u=e4a4090a38ac2473aaed4ef9945233636776c6c3&v=4","url":"https://github.com/eryajf"},"category":null,"labels":{"edges":[{"node":{"name":"更多","color":"25B472"}},{"node":{"name":"命令行工具","color":"e05879"}},{"node":{"name":"sqshq","color":"1b35a9"}}]},"comments":{"edges":[]}}},"pageContext":{"number":499,"previous":{"title":"saltstack/salt: 该软件能自动化管理和配置任何规模的基础设施或应用程序。","number":498},"next":{"title":"samwafgo/SamWaf: 一款开源轻量级的网站应用防火墙","number":500}}}, "staticQueryHashes": ["151096407","2861350382"]}