title: ResLens - Monitoring tool

ResLens

ResLens is a CPU and memory profiling toolkit for ResilientDB that aggregates system/process metrics and low‑level storage engine insights into a single, easy‑to‑use dashboard. It combines eBPF/pyroscope, Prometheus exporters (node/process), LevelDB internal stats and custom hooks to help you understand what happens under the hood and optimize performance.

Source: Apache Incubator · ResilientDB ResLens
GitHub (Dashboard): https://github.com/apache/incubator-resilientdb-ResLens 
GitHub (Middleware): https://github.com/apache/incubator-resilientdb-ResLens-Middleware 
Live Demo: https://reslens.resilientdb.com 

Why ResLens

• Understand hot paths with flame graphs and call stacks
• Inspect LevelDB/engine stats (cache hit ratio, SST layout, files per level)
• Track CPU/memory trends at node and process granularity
• One dashboard for learn (offline demo data) and live environments

Prerequisites (Live Mode)

• Linux host (Ubuntu 20.04+ recommended)
• ResilientDB running (service under test)
• Prometheus + exporters:
  • node_exporter · process_exporter
• Pyroscope (eBPF) for profiling (v0.37.0 used by authors)
• ResLens Middleware (backend aggregator)

You can also run ResLens in “Offline Mode” to explore the UI with demo data.

Quick Start

Offline Mode (Explore UI)

1. Clone the ResLens dashboard

git clone https://github.com/apache/incubator-resilientdb-ResLens
cd incubator-resilientdb-ResLens
# follow repo README to run the frontend (Vite/React)

2. Open the dashboard – it will render demo data bundled by the team so you can learn features without a full stack.

Live Mode (End‑to‑End)

1. Clone and set up the dashboard

git clone https://github.com/apache/incubator-resilientdb-ResLens
cd incubator-resilientdb-ResLens

2. Install and run dependencies
   • ResilientDB (service under test)
   • ResilientDB GraphQL (optional for key/value demos)
   • node_exporter and process_exporter
   • Pyroscope (eBPF) agent
   • ResLens Middleware (aggregates metrics + exposes HTTP for UI)
3. Stand up the Middleware (Docker Compose)

git clone https://github.com/apache/incubator-resilientdb-ResLens-Middleware
cd incubator-resilientdb-ResLens-Middleware
docker-compose down && docker-compose build && docker-compose up -d
# Pyroscope UI: http://localhost:4040
# Process Exporter metrics: http://localhost:9256/metrics

4. Configure the dashboard to point to your middleware endpoints
5. Start the dashboard (see repo README for exact commands)

Tip: Start in Offline Mode first to learn navigation, then wire exporters and Pyroscope one by one.

Core Features

1) Terminal‑like Playground (Key/Value)

Interactively Get/Set values in ResilientDB to generate realistic load and immediately visualize effects.

2) Flame Graphs & Call Stacks

Visualize hot paths and find bottlenecks across services. Ideal for spotting expensive functions during Reads/Writes.

3) Engine‑Level Insights (LevelDB)

Custom hooks expose storage metrics like cache hit ratio, SST layout and files per level.

4) System & Process Metrics

Prometheus exporters provide CPU/memory/io per host and per process for full context.

Typical Workflow

1. Open the dashboard (Offline Mode) and review example graphs
2. Switch to Live Mode:
   • Ensure exporters, Pyroscope and middleware are running
   • Point the dashboard to your middleware
3. Reproduce a workload (e.g., KV Get/Set via GraphQL) and watch ResLens update
4. Use the flame graph to locate hot functions and correlate with LevelDB stats
5. Iterate: optimize cache, compaction, or code paths and re‑measure

Example: Key/Value via GraphQL

# Set
curl --location 'https://crow.resilientdb.com/v1/transactions/commit' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "key_test",
    "value": "value_test"
  }'
 
# (Optional) Get – via GraphQL service
# See ResilientDB GraphQL docs for the exact query

Use this simple load to generate events; then inspect flame graphs, process CPU and LevelDB cache hit ratio.

Troubleshooting

• No data in dashboard
  • Check middleware URL, Prometheus targets, and Pyroscope agent status
• Flame graph empty
  • Ensure eBPF/Pyroscope is running with correct process targets
• Storage metrics missing
  • Verify LevelDB hooks are enabled in your ResilientDB build

Middleware Details

The ResLens Middleware is a containerized sidecar that:

• Runs Pyroscope (server + client) to profile target processes
• Runs Process Exporter to expose process metrics for Prometheus
• Exposes HTTP endpoints that the dashboard consumes
• Shares the host process namespace (pid: host) to profile host processes

Key ports (default):

• Pyroscope UI: http://localhost:4040 
• Process Exporter metrics: http://localhost:9256/metrics 

Security note: Requires elevated privileges to access host resources; review before production use.

License

This project is licensed under the Apache License 2.0 - see the LICENSE  file for details.

Contributing

We welcome contributions to this project! Please feel free to submit pull requests, report issues, or suggest new features.