darpan 0.2.0

Linux developer service monitoring utility with auto-detection, real-time health checks, and interactive TUI for databases, APIs, Docker containers, and more
Documentation
darpan-0.2.0 has been yanked.

Darpan(दर्पण) - Linux Developer Service Monitor

Darpan (दर्पण) means "mirror" in Sanskrit - a real-time reflection of your entire development environment.

License: MIT Rust

Stop checking services one by one. Darpan shows you everything at a glance.

📋 Table of Contents

🎯 What is Darpan?

Darpan is a developer-friendly service monitoring tool for Linux that automatically detects and monitors all your development services in one place.

The Problem It Solves

As a developer, you probably run multiple services:

# You do this all day:
docker ps                          # Check Docker
systemctl status postgresql        # Check PostgreSQL
redis-cli ping                     # Check Redis
curl localhost:3000               # Check your app
lsof -i :8080                     # Find what's on port 8080

This is tedious and time-consuming!

The Solution

With Darpan:

darpan watch    # See everything at once!

One command shows you:

  • ✅ All running services
  • ✅ Their health status
  • ✅ Response times
  • ✅ Why services are down
  • ✅ Live activity logs

💡 Why Use Darpan?

For Solo Developers

  • 🚀 Start your day faster: Know what's running before you begin coding
  • 🔍 Debug quicker: Instantly see which service is down
  • 🧘 Reduce cognitive load: One tool instead of 10 commands

For Teams

  • 📊 Shared understanding: Everyone sees the same service status
  • 🎯 Faster onboarding: New devs understand the stack immediately
  • 🔧 Better debugging: "Is Redis down for you too?"

Key Features

  • 🔎 Auto-detection: Finds services automatically (ports, processes, Docker)
  • ❤️ Health checks: Port, HTTP, database-specific checks
  • 🖥️ Two interfaces: CLI for quick checks, TUI for monitoring
  • ⚙️ Zero config: Works immediately, configure only when needed
  • 🐳 Docker aware: Detects and monitors containers
  • 📱 Lightweight: <20MB RAM, <5.5MB binary

📦 Installation

Prerequisites

  • Operating System: Linux (Ubuntu, Debian, Arch, etc.)
  • Rust: 1.70 or later (for building from source)
  • Optional: Docker (for Docker container detection)

Method 1: Build from Source (Recommended)

Step 1: Clone the Repository

cd ~
git clone https://github.com/codeBunny2022/darpan.git
cd darpan

Step 2: Build and Install

# Build the release version (optimized)
cargo build --release

# Install globally (requires sudo)
sudo cp target/release/darpan /usr/local/bin/

# Or install for current user only
cargo install --path .

Step 3: Verify Installation

darpan --version
# Output: darpan 0.1.0

✅ Done! Darpan is now available system-wide.

Method 2: Install via Cargo (Future)

# Coming soon!
cargo install darpan

🚀 Quick Start Tutorial

Let's learn Darpan with a hands-on tutorial!

Tutorial 1: Your First Status Check

Step 1: Check What's Running

Open a terminal and run:

darpan status

What you'll see:

Project: your-current-directory

╭───────────┬────────────┬──────────┬────────────────┬──────────╮
│ STATUS    │ NAME       │ TYPE     │ HOST:PORT      │ RESPONSE │
├───────────┼────────────┼──────────┼────────────────┼──────────┤
│ ✓ Healthy │ PostgreSQL │ Database │ localhost:5432 │ 12ms     │
│ ✓ Healthy │ Redis      │ Cache    │ localhost:6379 │ 3ms      │
╰───────────┴────────────┴──────────┴────────────────┴──────────╯

All 2 services are healthy ✓

Understanding the output:

  • ✓ Green checkmark: Service is healthy
  • ⚠ Yellow warning: Service is degraded
  • ✗ Red X: Service is down
  • Response time: How long the health check took

Step 2: Understand What Was Detected

Darpan automatically found:

  • PostgreSQL on port 5432 (standard PostgreSQL port)
  • Redis on port 6379 (standard Redis port)

How? Darpan:

  1. Scanned localhost ports 3000-9999
  2. Found open ports 5432 and 6379
  3. Identified them as PostgreSQL and Redis
  4. Checked their health

Tutorial 2: Interactive Monitoring

Step 1: Launch the TUI (Terminal User Interface)

darpan watch

What you'll see:

╔═══════════════════════════════════════════════╗
║  Darpan - your-directory | Live Monitor      ║
╠═══════════════════════════════════════════════╣
║ >> ✓ PostgreSQL    Database    :5432    12ms ║
║    ✓ Redis          Cache       :6379     3ms ║
╠═══════════════════════════════════════════════╣
║ Quick Info:                                   ║
║   Service: PostgreSQL                         ║
║   Status: ✓ HEALTHY                           ║
╠═══════════════════════════════════════════════╣
║ Live Logs:                                    ║
║   [18:13:33] Detected 2 services              ║
║   [18:13:38] Health check: 2/2 healthy        ║
╠═══════════════════════════════════════════════╣
║ q: quit | Enter: details | ↑↓: navigate      ║
╚═══════════════════════════════════════════════╝

Step 2: Navigate and Explore

Try these controls:

  1. Move up/down: Press ↑ and ↓ (or j and k)
    • Watch the >> selector move
    • Quick Info panel updates automatically
  2. View details: Press Enter on any service
    • See full service information
    • View process ID, command line
    • See error messages and suggestions
  3. Go back: Press q or Esc
    • Returns to main dashboard
  4. Refresh: Press r
    • Forces an immediate health check
    • Watch the logs update
  5. Quit: Press q from the main dashboard

Step 3: Watch Live Updates

Leave the TUI running for a minute:

  • Auto-refreshes every 5 seconds
  • Live logs show activity
  • Status updates automatically
  • Time since last update shown at bottom

Try this experiment:

  1. Keep darpan watch running
  2. In another terminal, stop a service: sudo systemctl stop redis
  3. Watch Darpan detect it within 5 seconds!
  4. Restart Redis: sudo systemctl start redis
  5. Watch it turn green again!

Tutorial 3: Troubleshooting a Down Service

Step 1: Simulate a Problem

Stop Redis temporarily:

sudo systemctl stop redis-server

Step 2: Check Status

darpan status

Output:

╭────────────┬────────────┬──────────┬────────────────┬──────────╮
│ STATUS     │ NAME       │ TYPE     │ HOST:PORT      │ RESPONSE │
├────────────┼────────────┼──────────┼────────────────┼──────────┤
│ ✓ Healthy  │ PostgreSQL │ Database │ localhost:5432 │ 12ms     │
│ ✗ Down     │ Redis      │ Cache    │ localhost:6379 │ N/A      │
╰────────────┴────────────┴──────────┴────────────────┴──────────╯

1/2 services healthy. 1 need attention!

Step 3: Investigate the Problem

Use the why command:

darpan why "Redis"

Output:

Service: Redis
────────────────────────────────────────────────────────
Status: DOWN ✗
Reason: Port not reachable: Connection refused
Location: localhost:6379
Process ID: Not running

Suggestion: Check if Redis is running and accepting connections

Last checked: 2026-01-20 18:30:45

This tells you:

  • ❌ Redis is not running
  • 📍 Expected on port 6379
  • 💡 Suggestion: Check if it's running

Step 4: Fix the Problem

sudo systemctl start redis-server

Step 5: Verify the Fix

darpan status

✅ All services are healthy!

📚 Detailed Usage Guide

Command Reference

darpan status

Shows current status of all services.

Basic usage:

darpan status

Options:

# JSON output (for scripts)
darpan status --format json

# Specific project
darpan status --path ~/my-project

# With debug logging
darpan --verbose status

When to use:

  • 🌅 Starting your workday
  • 🐛 Before debugging
  • 🚀 Before deploying
  • 🔄 After restarting services

darpan watch

Interactive TUI with live monitoring.

Basic usage:

darpan watch

Controls:

Key Action
↑ / k Move selection up
↓ / j Move selection down
Enter View service details
L View live logs for selected service
q Quit (or back from details/logs)
Esc Back to dashboard
r Manual refresh

Log Viewer Controls:

Key Action
Space Pause/Resume log streaming
↑ / ↓ Scroll through logs (when paused)
/ Enter search mode
1-4 Filter by log level (1=ERROR, 2=WARN, 3=INFO, 4=DEBUG)
0 Clear all filters
E Export logs to file
q / Esc Return to service details

When to use:

  • 👀 Continuous monitoring
  • 🔍 Troubleshooting complex issues
  • 📊 During development
  • 🎯 When waiting for services to start

darpan why <service-name>

Detailed troubleshooting for a specific service.

Basic usage:

darpan why "PostgreSQL"
darpan why "Redis"
darpan why "Backend API"

Example output:

Service: Backend API
────────────────────────────────────────────────────────
Status: DOWN ✗
Reason: Process not running
Location: localhost:3001
Process ID: Not found
Expected: node dist/server.js

Suggestion: Run 'npm run dev' in project directory

Last checked: 2026-01-20 18:35:22

When to use:

  • ❓ Service shows as down
  • 🐛 Debugging startup issues
  • 📖 Learning about service configuration

darpan init

Creates a .darpan.yml configuration file.

Basic usage:

cd ~/my-project
darpan init

Creates:

version: 1

services:
  - name: Backend API
    type: http_server
    port: 3001
    health_check:
      type: http
      path: /api/health
    tags: [critical, backend]
    
  - name: PostgreSQL
    type:
      database: postgres
    port: 5432
    health_check:
      type: postgres
      database: myapp_dev

When to use:

  • 📝 Custom service names
  • 🎯 Specific health checks
  • 👥 Sharing config with team
  • 🏷️ Organizing with tags

Real-time Log Viewing

Darpan includes a powerful log streaming feature that lets you view real-time logs from any service directly in the TUI.

Accessing Logs

  1. From Dashboard:

    • Use ↑/↓ to select a service
    • Press L to open the log viewer

  2. From Service Details:

    • When viewing service details, press L to view logs

Supported Log Sources

Darpan automatically detects and streams logs from:

🐳 Docker Containers

  • Full stdout/stderr streaming
  • Timestamps and log metadata
  • Works with all running containers

⚙️ Systemd Services

  • Journalctl integration
  • Structured log parsing
  • Log levels and priorities
  • Works with: postgresql, redis-server, mysql, nginx, etc.

📁 File-based Logs

  • Auto-detects common log locations:
    • ./logs/*.log
    • /var/log/<service-name>/*.log
    • ~/.pm2/logs/*.log (PM2-managed apps)
  • Real-time tailing with file watching
  • Handles log rotation gracefully

⚡ Process Output

  • Direct stdout/stderr capture via procfs
  • For processes not managed by systemd
  • Fallback option for custom services

Log Viewer Features

Live Streaming:

┌─ SERVICE LOGS: redis-server ──────────────────────────┐
│ Source: Systemd | Lines: 100 | ● LIVE (Space: pause)  │
├────────────────────────────────────────────────────────┤
│ [12:30:45.123 INFO ] Redis 7.0.15 starting            │
│ [12:30:45.145 INFO ] Running in standalone mode       │
│ [12:30:46.201 WARN ] No persistent storage configured │
│ [12:30:47.089 INFO ] Ready to accept connections:6379 │
│ [12:30:48.134 INFO ] Accepted 127.0.0.1:45678         │

Search Functionality:

  • Press / to enter search mode
  • Type your query
  • Matching text is highlighted in yellow
  • Press Enter to apply, Esc to cancel

Log Level Filtering:

  • Press 1 to show only ERROR logs
  • Press 2 to show only WARN logs
  • Press 3 to show only INFO logs
  • Press 4 to show only DEBUG logs
  • Press 0 to clear filter and show all

Pause and Scroll:

  • Press Space to pause live streaming
  • Use ↑/↓ to scroll through logs (when paused)
  • Resumes auto-scrolling when unpaused

Export Logs:

  • Press E to export current log buffer
  • Saves to: ~/.config/darpan/logs/darpan-<service>-<timestamp>.log
  • Includes metadata header with service info
  • Useful for sharing or archiving

Configuration for Log Files

If Darpan doesn't auto-detect your log files, you can specify them in .darpan.yml:

version: 1

services:
  - name: My Node App
    type: http_server
    port: 3000
    log_file: /var/log/myapp/app.log  # Custom log path
    
  - name: Custom Service
    type: custom
    port: 8080
    systemd_unit: my-custom.service  # Override systemd unit

Tips for Log Viewing

Performance:

  • Log buffer holds last 100 lines per service
  • Older logs are automatically rotated out
  • Minimal memory footprint even with active streaming

Troubleshooting Log Access:

  • Docker logs: Requires Docker daemon access
  • Systemd logs: May require sudo for some services
  • Process logs: Limited to processes owned by current user
  • File logs: Requires read permissions on log files

Best Practices:

  • Use search (/) to find specific errors quickly
  • Filter by ERROR (1) to see only critical issues
  • Export logs before clearing buffers for record-keeping
  • Pause streaming when analyzing specific log sections

Working with Different Projects

Scenario 1: Multiple Projects

You can use Darpan in any project without any setup:

Project A: E-commerce App

cd ~/projects/ecommerce
darpan watch
# Detects: PostgreSQL, Redis, Node.js backend, React frontend

Project B: Analytics Service

cd ~/projects/analytics
darpan watch
# Detects: MySQL, Python API, Celery workers

Project C: Microservices

cd ~/projects/microservices
darpan watch
# Detects: Multiple Docker containers, APIs

Scenario 2: Service-Specific Configs

Each project can have its own .darpan.yml:

Backend API Project:

cd ~/api-service
cat > .darpan.yml << 'EOF'
version: 1
services:
  - name: FastAPI Backend
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /health
  - name: PostgreSQL
    type: { database: postgres }
    port: 5432
EOF

darpan watch

Frontend Project:

cd ~/frontend
cat > .darpan.yml << 'EOF'
version: 1
services:
  - name: React Dev Server
    type: http_server
    port: 3000
  - name: API Backend
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /api/health
EOF

darpan watch

⚙️ Configuration

Configuration Hierarchy

Darpan uses a three-level configuration system:

1. System Defaults (built-in)
   ↓
2. User Config (~/.config/darpan/config.yml)
   ↓
3. Project Config (.darpan.yml)

User Configuration

Create ~/.config/darpan/config.yml for global settings:

mkdir -p ~/.config/darpan
cat > ~/.config/darpan/config.yml << 'EOF'
global:
  theme: dark
  refresh_interval: 5  # seconds

detection:
  enabled_detectors: [config, port, process, docker]
  port_range: [3000, 9999]  # Ports to scan

health_checks:
  timeout: 3  # seconds
  retry_count: 2

projects:
  - path: ~/work/client-a
    auto_load: true
  - path: ~/work/client-b
    auto_load: true
EOF

Project Configuration

Create .darpan.yml in your project root:

cd ~/my-project
cat > .darpan.yml << 'EOF'
version: 1

services:
  # Web Server
  - name: Backend API
    type: http_server
    port: 3001
    health_check:
      type: http
      path: /api/health
      expected_status: 200
    tags: [critical, backend]
    
  # Database
  - name: PostgreSQL
    type:
      database: postgres
    port: 5432
    health_check:
      type: postgres
      database: myapp_dev
    tags: [database, critical]
    
  # Cache
  - name: Redis
    type:
      cache: redis
    port: 6379
    health_check:
      type: redis
    tags: [cache]
    
  # Custom service
  - name: Celery Worker
    type: custom
    process: python celery_worker.py
    health_check:
      type: custom
      script: ./check_celery.sh
    tags: [worker]

# Service dependencies
dependencies:
  - service: Backend API
    depends_on: [PostgreSQL, Redis]
EOF

Supported Service Types

# HTTP Server
type: http_server

# Database
type: { database: postgres }  # postgres, mysql, mongodb, sqlite

# Cache
type: { cache: redis }  # redis, memcached

# Message Queue
type: { message_queue: rabbitmq }  # rabbitmq, kafka, redis

# Search Engine
type: { search: elasticsearch }  # elasticsearch, meilisearch

# Docker Container
type: docker_container

# Custom
type: custom

Health Check Types

# Port connectivity (default)
health_check:
  type: port

# HTTP endpoint
health_check:
  type: http
  path: /health
  expected_status: 200

# PostgreSQL
health_check:
  type: postgres
  database: mydb

# Redis
health_check:
  type: redis

# MySQL
health_check:
  type: mysql
  database: mydb

# Custom script
health_check:
  type: custom
  script: ./health_check.sh
  timeout: 5s

🌟 Real-World Examples

Example 1: Full-Stack MERN App

Setup:

cd ~/mern-app
darpan init

Edit .darpan.yml:

version: 1

services:
  - name: MongoDB
    type: { database: mongodb }
    port: 27017
    tags: [database]
    
  - name: Express Backend
    type: http_server
    port: 5000
    health_check:
      type: http
      path: /api/health
    tags: [backend, critical]
    
  - name: React Frontend
    type: http_server
    port: 3000
    tags: [frontend]
    
  - name: Redis Session Store
    type: { cache: redis }
    port: 6379
    tags: [cache]

dependencies:
  - service: Express Backend
    depends_on: [MongoDB, Redis Session Store]
  - service: React Frontend
    depends_on: [Express Backend]

Usage:

# Start your services
mongod &
redis-server &
cd backend && npm run dev &
cd frontend && npm start &

# Monitor everything
darpan watch

Example 2: Django + PostgreSQL

cd ~/django-project
cat > .darpan.yml << 'EOF'
version: 1

services:
  - name: Django Dev Server
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /admin/
    tags: [web]
    
  - name: PostgreSQL
    type: { database: postgres }
    port: 5432
    health_check:
      type: postgres
      database: django_db
    tags: [database]
    
  - name: Celery Worker
    type: custom
    process: celery -A myapp worker
    tags: [worker]
    
  - name: Celery Beat
    type: custom
    process: celery -A myapp beat
    tags: [scheduler]

dependencies:
  - service: Django Dev Server
    depends_on: [PostgreSQL]
  - service: Celery Worker
    depends_on: [PostgreSQL, Redis]
EOF

Example 3: Microservices with Docker

cd ~/microservices
cat > .darpan.yml << 'EOF'
version: 1

services:
  - name: Auth Service
    type: http_server
    port: 8001
    health_check:
      type: http
      path: /health
    tags: [microservice, critical]
    
  - name: User Service
    type: http_server
    port: 8002
    health_check:
      type: http
      path: /health
    tags: [microservice]
    
  - name: Payment Service
    type: http_server
    port: 8003
    health_check:
      type: http
      path: /health
    tags: [microservice, critical]
    
  - name: Notification Service
    type: http_server
    port: 8004
    health_check:
      type: http
      path: /health
    tags: [microservice]
    
  - name: PostgreSQL
    type: { database: postgres }
    port: 5432
    tags: [database]
    
  - name: Redis
    type: { cache: redis }
    port: 6379
    tags: [cache]
    
  - name: RabbitMQ
    type: { message_queue: rabbitmq }
    port: 5672
    tags: [queue]
EOF

With Docker Compose:

docker-compose up -d
darpan watch
# Automatically detects all containers!

🔧 Troubleshooting

Common Issues and Solutions

Issue 1: No Services Detected

Symptom:

darpan status
# No services detected.

Solutions:

  1. Check if services are actually running:
# Check open ports
ss -tlnp | grep LISTEN

# Check processes
ps aux | grep postgres
ps aux | grep redis
  1. Verify port range: Create ~/.config/darpan/config.yml:
detection:
  port_range: [1000, 65535]  # Scan wider range
  1. Use explicit configuration:
darpan init
# Edit .darpan.yml to define your services

Issue 2: Service Shows as Down but It's Running

Symptom:

✗ Down     │ Redis      │ Cache    │ localhost:6379 │ N/A

Solutions:

  1. Check the actual service:
redis-cli ping
# Should return: PONG
  1. Check if port is accessible:
telnet localhost 6379
# or
nc -zv localhost 6379
  1. Configure custom health check:
services:
  - name: Redis
    type: { cache: redis }
    port: 6379
    health_check:
      type: redis  # Use Redis-specific check
      timeout: 5s
      retry_count: 3

Issue 3: Docker Containers Not Detected

Symptom: Docker containers running but not showing in Darpan.

Solutions:

  1. Check Docker access:
docker ps
# If this fails, Docker daemon might not be running
  1. Add user to docker group:
sudo usermod -aG docker $USER
# Logout and login again
  1. Enable Docker detector:
# ~/.config/darpan/config.yml
detection:
  enabled_detectors: [config, port, process, docker]

Issue 4: Permission Denied Errors

Symptom:

Error: Permission denied (os error 13)

Solutions:

  1. Darpan doesn't need sudo for basic functionality
  2. For Docker: Add user to docker group (see above)
  3. For system services: Run status checks work without sudo

Issue 5: TUI Shows Garbled Text

Symptom: Terminal display is corrupted.

Solutions:

  1. Reset terminal:
reset
  1. Use modern terminal:
  • ✅ GNOME Terminal
  • ✅ Konsole
  • ✅ Alacritty
  • ✅ iTerm2 (if on Mac via WSL)
  1. Check terminal size:
# TUI needs at least 80x24
echo $COLUMNS x $LINES

🚀 Advanced Features

JSON Output for Automation

Export service status as JSON:

# Get all services
darpan status --format json

# Parse with jq
darpan status --format json | jq '.[] | select(.port == 5432)'

# Count healthy services
darpan status --format json | jq '[.[] | select(.health_status.status == "Healthy")] | length'

# Get unhealthy services
darpan status --format json | jq '[.[] | select(.health_status.status != "Healthy")] | .[].name'

Integration with Scripts

Health check script:

#!/bin/bash
# check_services.sh

OUTPUT=$(darpan status --format json)
UNHEALTHY=$(echo $OUTPUT | jq '[.[] | select(.health_status.status != "Healthy")] | length')

if [ $UNHEALTHY -gt 0 ]; then
    echo "❌ $UNHEALTHY service(s) are unhealthy!"
    echo $OUTPUT | jq '[.[] | select(.health_status.status != "Healthy")] | .[].name'
    exit 1
else
    echo "✅ All services are healthy"
    exit 0
fi

Pre-deployment check:

#!/bin/bash
# pre_deploy.sh

echo "Checking services before deployment..."
darpan status

if darpan status --format json | jq -e '[.[] | select(.health_status.status != "Healthy")] | length == 0' > /dev/null; then
    echo "✅ All services healthy. Proceeding with deployment."
    ./deploy.sh
else
    echo "❌ Some services are unhealthy. Aborting deployment."
    darpan status
    exit 1
fi

Custom Health Check Scripts

Example: Custom health check for Celery:

# check_celery.sh
#!/bin/bash
celery -A myapp inspect active >/dev/null 2>&1
if [ $? -eq 0 ]; then
    exit 0  # Healthy
else
    exit 1  # Unhealthy
fi

Configuration:

services:
  - name: Celery Worker
    type: custom
    process: celery worker
    health_check:
      type: custom
      script: ./check_celery.sh
      timeout: 5s

Tags for Organization

Use tags to organize and filter services:

services:
  - name: Auth API
    tags: [critical, microservice, auth]
  - name: Payment Service
    tags: [critical, microservice, payment]
  - name: Analytics Worker
    tags: [worker, non-critical]
  - name: Cache Layer
    tags: [infrastructure, cache]

📖 Best Practices

1. Start Simple

  • Begin without .darpan.yml
  • Let auto-detection work
  • Add config only when needed

2. Use Meaningful Names

# ❌ Bad
- name: Service 1
- name: Server

# ✅ Good
- name: User Authentication API
- name: Payment Processing Service

3. Tag Appropriately

tags: [critical, backend]  # For core services
tags: [optional, worker]   # For non-critical services

4. Document Health Checks

- name: API Gateway
  health_check:
    type: http
    path: /health  # Document why this endpoint

5. Share Configs with Team

# Commit .darpan.yml to git
git add .darpan.yml
git commit -m "Add Darpan service monitoring config"

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick Links

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

  • Built with Rust
  • TUI powered by Ratatui
  • Inspired by tools like htop, docker-compose, and systemctl

📚 Additional Resources

💬 Support

Need help?

Made with ❤️ for developers who are tired of checking services manually

# Try it now!
darpan watch