darpan 0.2.3 - Docs.rs

# Darpan 🪞

> **दर्पण** (Darpan) = Mirror in Hindi/Sanskrit  
> *Your development environment, reflected in real-time*

[![Crates.io](https://img.shields.io/crates/v/darpan)](https://crates.io/crates/darpan)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Rust](https://img.shields.io/badge/rust-1.70%2B-orange.svg)](https://www.rust-lang.org/)

**Zero-config service monitoring for Linux developers.** Auto-discovers and monitors databases, APIs, Docker containers, and caches with real-time health checks, live log streaming, and network activity tracking.

```bash
cargo install darpan
darpan watch  # That's it!
```

---

## ✨ What You Get

### Before Darpan 😓
```bash
$ systemctl status postgresql redis nginx
$ docker ps | grep mongo
$ lsof -i :3000,5432,6379
$ curl localhost:8000/health
$ journalctl -u postgresql -f
$ tail -f /var/log/nginx/error.log
```
**6 commands. 6 terminal tabs. Constant context switching.**

### With Darpan ✨
```bash
$ darpan watch
```

```
┌─ Darpan - myproject | Live Monitor ─────────────────┐
│ STATUS    │ NAME        │ TYPE      │ PORT  │ CONN  │
├───────────┼─────────────┼───────────┼───────┼───────┤
│ ✓ Healthy │ PostgreSQL  │ Database  │  5432 │ 3     │
│ ✓ Healthy │ Redis       │ Cache     │  6379 │ 0     │
│ ✓ Healthy │ Frontend    │ HTTP      │  3000 │ 1     │  ← Works without /health!
│ ✗ Down    │ API Server  │ HTTP      │  8000 │ -     │
└──────────────────────────────────────────────────────┘
3/4 healthy | Enter: details | L: logs | r: refresh
```

**One command. One dashboard. Everything.**

---

## 🚀 Key Features

### 🔍 Zero-Config Auto-Discovery
- **Instant detection**: PostgreSQL, Redis, MySQL, MongoDB, Docker, HTTP servers
- **Multi-source scanning**: Ports, processes, Docker API, systemd units
- **Smart recognition**: Service signatures and common patterns
- **Just works**: No setup required

### 💚 Intelligent Health Monitoring
- **Multi-tier checks**: HTTP endpoints → Port connectivity → Process verification
- **Database pings**: PostgreSQL, Redis, MySQL, MongoDB
- **Fallback logic**: Services without `/health` work (React, Vue, Angular dev servers)
- **Real-time updates**: Configurable intervals

### 📡 Live Network Activity Tracking ⚡ NEW
```
═══ Network Activity ═══
Port Status: LISTENING ✓
Active Connections: 5 (traffic detected)
Process Connections: 3 established, 1 listening
```
- **See actual traffic** to your services
- **Detect hung connections** or leaks
- **Verify listening status** even without health endpoints
- **Process-level insights** for deep debugging

### 🔍 Real-Time Log Streaming
```
┌─ SERVICE LOGS: Redis ─────────────────────────┐
│ [12:30:45 INFO ] Starting Redis 7.0.15        │
│ [12:30:46 INFO ] Ready to accept connections  │
│ [12:30:50 WARN ] Memory usage: 2.1MB          │
└───────────────────────────────────────────────┘
Press /: search | 1-4: filter level | E: export
```

**Auto-detects 4 log sources:**
- 🐳 **Docker**: stdout/stderr from all containers
- ⚙️ **Systemd**: `journalctl` integration
- 📁 **Files**: `/var/log/`, `./logs/`, `~/.pm2/logs/`
- ⚡ **Process**: Direct stdout/stderr via `/proc/<pid>/fd/`

**Interactive features:**
- Search with `/` (highlighted matches)
- Filter: `1`=ERROR, `2`=WARN, `3`=INFO, `4`=DEBUG
- Pause/scroll with `Space`, `↑↓`
- Export with `E` to `~/.config/darpan/logs/`

### 🎨 Beautiful TUI
- Keyboard-driven (Vim-style `j/k` support)
- Color-coded status indicators
- Live auto-refresh
- Service details with diagnostics
- Network activity section

---

## 📦 Installation

```bash
# From crates.io (recommended)
cargo install darpan

# From source
git clone https://github.com/codeBunny2022/darpan.git
cd darpan
cargo install --path .

# Verify
darpan --version  # v0.2.2
```

**Requirements:** Rust 1.70+, Linux  
**Optional:** Docker, systemd, ss/netstat

---

## 🎯 Quick Start

### Basic Commands

```bash
darpan watch              # Interactive TUI (recommended)
darpan status             # Quick CLI status
darpan why "Redis"        # Troubleshoot specific service
darpan status --format json  # For scripts/CI
darpan init               # Create .darpan.yml template
```

### TUI Navigation

| Key | Action |
|-----|--------|
| `↑`/`↓`, `j`/`k` | Navigate services |
| `Enter` | View details + network activity |
| **`L`** | **View live service logs** 🔥 |
| `r` | Refresh |
| `q`, `Esc` | Back/Quit |

### Log Viewer (Press `L`)

| Key | Action |
|-----|--------|
| `Space` | Pause/resume |
| `/` | Search |
| `1-4` | Filter by level |
| `0` | Clear filters |
| `E` | Export |
| `↑`/`↓` | Scroll (paused) |

---

## 📚 Configuration (Optional)

Darpan works without config. Add `.darpan.yml` only for custom services:

```yaml
version: 1

services:
  - name: My API
    type: http_server
    port: 8000
    health_check:
      type: http
      path: /api/health
    log_file: /var/log/myapi/app.log  # Custom log path
    
  - name: PostgreSQL
    type:
      database: postgres
    port: 5432
    health_check:
      type: postgres
      database: mydb
    systemd_unit: postgresql.service  # Custom systemd unit
    
  - name: Worker
    type: custom
    port: 9000
    process: "python worker.py"
    tags: [background, critical]

dependencies:
  - service: My API
    depends_on: [PostgreSQL, Redis]
```

**Config locations:**
- `./.darpan.yml` - Project-level (team sharing)
- `~/.config/darpan/config.yml` - User-level (personal defaults)

---

## 🌟 Real-World Examples

### Example 1: Microservices Stack

```bash
$ cd ~/my-microservices
$ darpan watch

# See all services:
# - 3 Docker containers (MongoDB, RabbitMQ, Elasticsearch)
# - 2 Node.js APIs (ports 3000, 4000)
# - 1 React frontend (port 8080)
# - PostgreSQL and Redis

# Press L on any service to see live logs
# Press Enter to see network connections
```

### Example 2: Debugging Slow API

```bash
$ darpan watch

# Select API service → Press Enter
# Check "Network Activity":
#   Active Connections: 127 (!!!)
#   → Connection leak detected!

# Press L → Search for "timeout" with /
# Press E → Export logs for analysis
```

### Example 3: CI/CD Health Check

```bash
#!/bin/bash
# Ensure all services are up before running tests

darpan status --format json | jq '.[] | select(.status != "Healthy")'
if [ $? -eq 0 ]; then
  echo "Some services are down!"
  darpan status
  exit 1
fi

npm test
```

---

## 🔧 Troubleshooting

### Service not detected?

```bash
# Check if port is open
ss -tln | grep 5432

# Check if process is running
ps aux | grep postgres

# Add to .darpan.yml manually
darpan init
```

### Logs not showing?

```bash
# Check permissions
ls -la /var/log/postgresql/

# For systemd logs
journalctl -u redis-server -f

# For Docker
docker logs <container_name>

# Specify custom log path in .darpan.yml
```

### Health check false positive/negative?

```yaml
# Override in .darpan.yml
services:
  - name: My Service
    port: 3000
    health_check:
      type: http
      path: /custom/health  # Custom endpoint
      expected_status: 200
```

---

## 🤝 Contributing

Contributions welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
- Code of conduct
- Development setup
- Pull request process
- Testing guidelines

---

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

Created by [Chirag (chiraglabs)](https://github.com/codeBunny2022)

---

## 🙏 Acknowledgments

Built with:
- [Ratatui](https://github.com/ratatui-org/ratatui) - Terminal UI
- [Tokio](https://tokio.rs/) - Async runtime
- [Bollard](https://github.com/fussybeaver/bollard) - Docker API
- [Serde](https://serde.rs/) - Serialization

Inspired by tools like `htop`, `docker-compose`, and `systemctl status`.

---

## 💬 Support

- **Issues**: [GitHub Issues](https://github.com/codeBunny2022/darpan/issues)
- **Discussions**: [GitHub Discussions](https://github.com/codeBunny2022/darpan/discussions)
- **Crates.io**: [crates.io/crates/darpan](https://crates.io/crates/darpan)

---

<div align="center">

**⭐ Star this repo if Darpan helps you!**

Made with ❤️ by developers, for developers.

</div>