resq-perf

Version: v0.1.16 · License: Apache-2.0 · Crate: crates.io · API docs: docs.rs

Real-time CPU and memory performance TUI for ResQ platform

Overview

Real-time performance monitoring dashboard for ResQ services. Polls a service’s /status endpoint and displays live memory usage, response latency, and heap object breakdowns in a three-column Ratatui TUI with sparkline history charts.

Architecture

Installation

# From workspace root
cargo build --release -p resq-perf

# Binary location
target/release/resq-perf

CLI Arguments

Argument / Flag	Type	Default	Description
`url` (positional)	`String`	`http://localhost:3000/admin/status`	Service status endpoint URL to monitor
`--refresh-ms <ms>`	`u64`	`500`	Refresh interval in milliseconds (clamped to 100-5000)
`-t`, `--token <jwt>`	`String`	`$RESQ_TOKEN`	Bearer token for authenticated endpoints

Usage Examples

# Monitor default HCE service (localhost:3000)
resq-perf

# Target a specific service status URL
resq-perf http://localhost:5000/admin/status

# Authenticated service with explicit token
resq-perf --token <your-bearer-token>

# Use environment variable for authentication
export RESQ_TOKEN="<your-bearer-token>"
resq-perf http://localhost:3000/admin/status

# Slower refresh rate (1 second) for low-bandwidth environments
resq-perf --refresh-ms 1000

# Fast refresh for detailed monitoring
resq-perf --refresh-ms 100

Metrics Reference

Status Endpoint Schema

The tool expects JSON from the /admin/status endpoint matching this structure (compatible with coordination-hce):

{
  "uptime": "2h 15m 30s",
  "uptimeNanoseconds": 8130000000000,
  "version": "1.2.3",
  "environment": "production",
  "memory": {
    "process": {
      "rss": 104857600,
      "heapUsed": 52428800,
      "heapTotal": 67108864,
      "external": 1048576,
      "arrayBuffers": 524288
    },
    "heap": {
      "heapSize": 67108864,
      "heapCapacity": 83886080,
      "extraMemorySize": 2097152,
      "objectCount": 45000,
      "protectedObjectCount": 1200,
      "globalObjectCount": 350,
      "protectedGlobalObjectCount": 50,
      "objectTypeCounts": {
        "Object": 15000,
        "Array": 8000,
        "Function": 5000,
        "String": 12000
      }
    }
  }
}

Displayed Metrics

Panel	Metric	Source Field	Description
Memory	Heap Gauge	`memory.process.heapUsed / heapTotal`	Percentage bar with color coding (green < 50%, yellow < 80%, red >= 80%)
Memory	RSS	`memory.process.rss`	Resident set size of the process
Memory	External	`memory.process.external`	Memory used by C++ objects bound to JS
Memory	Uptime	`uptimeNanoseconds`	Formatted as `Xh Xm Xs`
Memory	Version	`version`	Service version string
Memory	Sparkline	heap_used history	Rolling 120-sample chart of heap usage
Latency	Current	measured round-trip	Last HTTP request latency in ms
Latency	Average	computed	Mean of all samples in history
Latency	Min / Max	computed	Range across history window
Latency	P95	computed	95th percentile latency
Latency	Success Rate	success / total	Percentage of successful polls
Latency	Sparkline	latency history	Rolling 120-sample chart of response times
Heap Objects	Object Count	`memory.heap.objectCount`	Total objects on the V8 heap
Heap Objects	Protected	`memory.heap.protectedObjectCount`	GC-protected object count
Heap Objects	Global	`memory.heap.globalObjectCount`	Global scope object count
Heap Objects	Heap Size	`memory.heap.heapSize`	Current heap allocation
Heap Objects	Capacity	`memory.heap.heapCapacity`	Total heap capacity
Heap Objects	Type Table	`memory.heap.objectTypeCounts`	Top 12 object types sorted by count

Environment Variables

Variable	Description
`RESQ_TOKEN`	Bearer token for service authentication. Used when `--token` is not provided.

Keybindings

Key	Action
`q` / `Esc`	Quit
`Ctrl+C`	Force quit
`p`	Pause / resume polling
`r`	Reset all history, counters, and error log
`+` / `=`	Increase refresh rate by 100ms (faster polling)
`-` / `_`	Decrease refresh rate by 100ms (slower polling)
`h`	Toggle help overlay panel

TUI Layout

+-- ResQ Performance Monitor -- STATUS -- LATENCY ------------+
|                                                              |
| +-- Memory --------+ +-- Response Time -+ +-- Heap Objects -+|
| | [=======   ] 70% | | Current: 45ms    | | Objects: 45000  ||
| | RSS: 100.0 MiB   | | Average: 52ms    | | Protected: 1200 ||
| | External: 1.0 MiB| | Min: 12ms        | | Global: 350     ||
| | Uptime: 2h 15m   | | Max: 350ms       | | Heap: 64.0 MiB  ||
| | Version: 1.2.3   | | P95: 120ms       | | Capacity: 80 MiB||
| |                   | | Success: 99.2%   | |                 ||
| | History (max: 64M)| |                   | | Type     Count %||
| | ......########    | | Latency (max:350)| | Object   15000  ||
| | ....##########    | | ..####..####..   | | String   12000  ||
| +-------------------+ +------------------+ | Array     8000  ||
|                                             | Function  5000  ||
|                                             +-----------------+|
+--------------------------------------------------------------+
| q quit  p pause  r reset  +/- speed  h help | S:142 E:1 500ms|
+--------------------------------------------------------------+

Configuration

Refresh Rate Bounds

The refresh interval is clamped to the range 100ms - 5000ms. The + and - keys adjust in 100ms increments at runtime. The initial value is set via --refresh-ms (default: 500ms).

History Depth

Both memory and latency sparklines retain the most recent 120 samples (MAX_HISTORY). At the default 500ms refresh rate, this covers approximately 60 seconds of data. The error history retains the last 10 entries.

HTTP Client

The built-in reqwest::blocking::Client has a 5-second timeout per request. Authentication uses the Authorization: Bearer <token> header when a token is provided via --token or RESQ_TOKEN.

Latency Color Coding

Response time in the header is color-coded:

Green: < 50ms
Yellow: 50-200ms
Red: > 200ms

resq-logs — Log aggregator and stream viewer
resq-flame — CPU flame graph profiler
resq-health — Service health checker

For comprehensive profiling workflows see docs/PROFILING_FLAMEGRAPH_GUIDE.md.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

​resq-perf

​Overview

​Architecture

​Installation

​CLI Arguments

​Usage Examples

​Metrics Reference

​Status Endpoint Schema

​Displayed Metrics

​Environment Variables

​Keybindings

​TUI Layout

​Configuration

​Refresh Rate Bounds

​History Depth

​HTTP Client

​Latency Color Coding

​Related Tools

​License