BSV blockchainBSV blockchain

TUI Tools

Index

  1. Overview
  2. Node Status Monitor
  3. Interactive Log Viewer
  4. Related Documentation

1. Overview

Teranode includes two terminal-based monitoring tools in teranode-cli, both built with the Bubble Tea TUI framework and Lip Gloss for styling:

  • Node Status Monitor (teranode-cli monitor) - a live dashboard showing blockchain state, FSM status, peer connections, service health, and Aerospike statistics.
  • Interactive Log Viewer (teranode-cli logs) - a real-time log tail with per-service color coding, filtering, text search, and transaction ID tracking.

Both tools run in an alternate screen buffer and refresh automatically, providing a lightweight alternative to the web dashboard that requires no browser or additional dependencies.

2. Node Status Monitor

The monitor connects to Teranode’s gRPC services and polls them every two seconds to display a consolidated view of node health.

2.1. Dashboard View

The default view shows five panels arranged in a responsive layout (side-by-side on wide terminals, stacked on narrow ones):

Blockchain Panel

FieldDescription
HeightMaximum chain height
BlocksTotal block count
TransactionsTotal transaction count (formatted with commas)
Avg Block SizeAverage block size in human-readable units (KB, MB, etc.)
Avg Tx/BlockAverage transactions per block
Last BlockTime since the most recent block (e.g. “5m ago”)

FSM State Panel

Displays the current Finite State Machine state with color coding:

  • Green for “running”
  • Yellow for “idle”, “catching”, or “sync” states (sync states also show a spinner)
  • White for other states

Below the state, connectivity indicators show whether the Blockchain and P2P services are reachable (green checkmark or red X).

Peers Panel

  • Connected and total known peer counts
  • Top 5 connected peers sorted by height, showing truncated peer ID, height, and reputation score
  • Reputation scores are color-coded: green (>= 80), yellow (>= 50), red (< 50)

Services Health Row

A compact one-line summary using short labels and status icons:

LabelServiceIcons
BCBlockchaincheckmark = healthy, X = down, circle = not configured
VALValidatorcheckmark = healthy, X = down, circle = not configured
BVBlock Validationcheckmark = healthy, X = down, circle = not configured
BABlock Assemblycheckmark = healthy, X = down, circle = not configured
STSubtree Validationcheckmark = healthy, X = down, circle = not configured
P2PP2Pcheckmark = healthy, X = down, circle = not configured

Aerospike Summary Row

A one-line status showing connection state, namespace name, node count, object count, disk usage percentage, and alert indicators for overloads, key contention, low available space, or low memory.

2.2. Settings View

Press s to switch to a scrollable display of the loaded Teranode settings, grouped by section:

  • General - version, commit, network, data folder, log level
  • Blockchain - gRPC address, listen address, HTTP listen, store URL
  • P2P - gRPC address, listen address, HTTP address, port, listen mode, DHT mode, bootstrap/static peer counts
  • Validator - gRPC address, listen address
  • Block Assembly - disabled flag, gRPC address, listen address
  • Kafka - hosts, port, partitions
  • Aerospike - host, port
  • Asset - HTTP address, listen address

The current settings context is shown at the top. Values that are not set appear as “(not set)”.

2.3. Health View

Press h to switch to a detailed service health table:

ColumnDescription
SERVICEService name (Blockchain, Validator, Block Validation, Block Assembly, Subtree Validation, P2P)
STATUSHealth status with icon (checkmark OK, X DOWN, circle N/A)
LATENCYResponse time in milliseconds (or ”-” if not applicable)
MESSAGEStatus message (e.g. “OK”, “Connection failed”, “3 peers connected”)

2.4. Aerospike View

Press a to switch to a scrollable detailed Aerospike statistics view containing:

Cluster Info - node count, open connections, namespace name, node names.

Per-Node Stats - for each node: host address, cluster size, uptime, free memory percentage, client connections, batch/scan queue depths.

Namespace Statistics (aggregated across nodes for multi-node clusters):

  • Disk usage (used/total with percentage)
  • Critical flags: stop_writes, clock_skew_stop_writes, hwm_breached (highlighted in red if non-zero)
  • Storage metrics: available percentage, memory usage, index usage, cache read percentage
  • Object metrics: objects, tombstones, evicted/expired/truncated counts
  • Throughput metrics: read/write successes, errors, and timeouts (errors highlighted in red)
  • Migration metrics (shown only when non-zero)

Latencies - operation latency histograms from the Aerospike server.

2.5. Keyboard Shortcuts

KeyAction
q, Ctrl+CQuit
EscReturn to dashboard (or quit if already on dashboard)
rForce refresh
sToggle settings view
hToggle health view
aToggle Aerospike view
j / DownScroll down (in settings/Aerospike views)
k / UpScroll up (in settings/Aerospike views)
g / HomeScroll to top (in settings/Aerospike views)
G / EndScroll to bottom (in settings/Aerospike views)

2.6. Running the Monitor

Build:

make build-teranode-cli

Launch:

./teranode-cli monitor

The monitor reads Teranode’s settings.conf (and settings_local.conf if present) to discover service addresses. At minimum, the Blockchain and P2P gRPC addresses must be configured for the dashboard to display data. Other services (Validator, Block Validation, Block Assembly, Subtree Validation, Aerospike) are optional and will show as “Not configured” if their addresses are not set.

3. Interactive Log Viewer

The log viewer tails a Teranode log file in real time, parsing each line into structured fields and rendering them with color coding and alignment.

3.1. Log Display

Each parsed log line is displayed with the following columns:

HH:MM:SS  LEVEL  SERVICE   Message text...
  • Timestamp - displayed in gray (HH:MM:SS format)
  • Level - color-coded: gray (DEBUG), blue (INFO), yellow (WARN), red (ERROR), magenta (FATAL)
  • Service - padded to 8 characters, each service gets a distinct color:
ServiceColor
p2pGreen
bchnPurple
validator / validBlue
propOrange
baPink
rpcCyan
assetGold
alertRed
prunerLight purple
legacyGray

Lines that do not match the expected log format are displayed as raw text in gray.

The header shows:

  • Title (“TERANODE LOGS”)
  • Rate sparkline - a Unicode block-character graph showing log frequency over the last 30 seconds, with a current rate counter (e.g. “42/s”). Toggle with r.
  • Status indicator - “LIVE” (green) or “PAUSED” (yellow)
  • Line counts - filtered line count and total count (if different)

3.2. Filtering

The log viewer supports four types of filters that can be combined:

Service Filter (s)

Enter a comma-separated list of service names to show only those services. Press Tab to autocomplete from discovered service names. Services are discovered automatically as log entries are parsed.

Log Level Filter (+ / -)

Increase or decrease the minimum log level to display. The hierarchy is: DEBUG < INFO < WARN < ERROR < FATAL. The default shows all levels.

Text Search (/)

Enter a search string to filter log entries. Matches are case-insensitive and search across the message, service name, and caller fields. Matching text is highlighted with a yellow background.

Transaction ID Search (t)

Enter a 64-character hex transaction ID to filter logs to only entries containing that ID. The ID is highlighted in matching lines.

All filters can be cleared at once with c. The current filter state is shown in the status bar at the bottom (e.g. “Filter: WARN+ | p2p,validator | “search text” | tx:abcd1234…”).

3.3. Error Summary

Press e to toggle the error summary panel. This shows a 5-minute sliding window of error and warning counts per service, sorted by total count (descending). The panel displays up to 4 services plus a total, in the format:

ERRORS (5m): service1: 3E 2W | service2: 1E 0W | Total: 4E 2W

Error counts are shown in red and warning counts in yellow.

3.4. Keyboard Shortcuts

KeyAction
Navigation
j / k, Up / DownScroll up/down one line
g / G, Home / EndGo to top/bottom
PgUp / PgDnPage up/down
Ctrl+U / Ctrl+DHalf page up/down
Filtering
/Open text search
sOpen service filter
tOpen transaction ID search
+ / -Increase/decrease minimum log level
cClear all filters
TabAutocomplete service name (in filter mode)
Controls
p, SpacePause/resume auto-scroll
mToggle mouse mode (off enables text selection for copy)
eToggle error summary panel
rToggle rate sparkline graph
?Toggle full help screen
q, Ctrl+CQuit
EscCancel current input / close help
EnterConfirm current input

3.5. Running the Log Viewer

Build:

make build-teranode-cli

Launch:

./teranode-cli logs [--file <path>] [--buffer <size>]
FlagDefaultDescription
--file./logs/teranode.logPath to the log file to tail
--buffer10000Number of log entries to keep in memory

The log viewer requires Teranode to be running with log output directed to a file. The recommended way is to use the log rotation script:

./scripts/run-teranode-with-logrotate.sh

The viewer reads the last 1,000 lines on startup and then tails new entries in real time.