Metadata-Version: 2.4
Name: arq-optimus-dashboard
Version: 0.1.0
Summary: Real-time monitoring dashboard and CLI for ARQ Optimus async task queues
Project-URL: Homepage, https://github.com/arpansahu/arq-optimus
Project-URL: Source, https://github.com/arpansahu/arq-optimus
Project-URL: Changelog, https://github.com/arpansahu/arq-optimus/releases
Project-URL: Issues, https://github.com/arpansahu/arq-optimus/issues
Author-email: Arpan Sahu <arpansahu01@gmail.com>
Maintainer-email: Arpan Sahu <arpansahu01@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.9
Requires-Dist: arq-optimus>=0.27.0
Requires-Dist: click>=8.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: uvicorn[standard]>=0.32.0
Description-Content-Type: text/markdown

# ARQ Optimus Dashboard

[![PyPI version](https://img.shields.io/pypi/v/arq-optimus-dashboard.svg)](https://pypi.org/project/arq-optimus-dashboard/)
[![Python versions](https://img.shields.io/pypi/pyversions/arq-optimus-dashboard.svg)](https://pypi.org/project/arq-optimus-dashboard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Real-time monitoring dashboard and CLI** for [ARQ Optimus](https://pypi.org/project/arq-optimus/) async task queues.

## Features

- **Real-time Dashboard** — Auto-refreshing web UI with queue stats, job listing, status filtering
- **Job Cancellation** — Cancel queued/running jobs via dashboard or CLI using ARQ's native `Job.abort()`
- **Job Management CLI** (`arq-optimus`) — Stats, list, info, cancel, delete from the terminal
- **Key Prefix Support** — Works with ARQ Optimus key-prefix isolation for multi-project Redis
- **FastAPI Backend** — High-performance async API with Redis connection pooling
- **Redis Cloud Support** — Works with SSL/TLS connections

## Installation

```bash
pip install arq-optimus-dashboard
```

This automatically installs [arq-optimus](https://pypi.org/project/arq-optimus/) as a dependency.

## Dashboard

### Start the Dashboard

```bash
# Basic usage
arq-optimus-dashboard --redis-url redis://localhost:6379

# With Redis Cloud (SSL)
arq-optimus-dashboard --redis-url rediss://:password@redis.example.com:6380

# With key prefix (must match your worker's key_prefix)
arq-optimus-dashboard --redis-url redis://localhost:6379 --key-prefix myproject

# Custom host and port
arq-optimus-dashboard --redis-url redis://localhost:6379 --host 127.0.0.1 --port 9000

# With basic auth
arq-optimus-dashboard --redis-url redis://localhost:6379 --username admin --password secret
```

Open your browser to `http://localhost:8910` to see the dashboard.

### Dashboard Features

- **Queue Statistics** — Live counts of queued, running, completed, failed, cancelled jobs
- **Status Filtering** — Filter jobs by status (queued / running / completed / failed / cancelled)
- **Job Details** — Click any job to see arguments, result, timing, errors
- **Cancel Jobs** — Cancel queued or running jobs with one click
- **Delete Jobs** — Clean up completed/failed/cancelled job records
- **Auto-Refresh** — Updates every 5 seconds

## CLI (`arq-optimus`)

Manage jobs from the terminal without a dashboard:

```bash
# Queue statistics
arq-optimus stats --redis-url redis://localhost:6379

# List jobs (optionally filter by status)
arq-optimus list --redis-url redis://localhost:6379
arq-optimus list --redis-url redis://localhost:6379 --status running

# Job details
arq-optimus info <job_id> --redis-url redis://localhost:6379

# Cancel a job
arq-optimus cancel <job_id> --redis-url redis://localhost:6379

# Delete a completed/failed job
arq-optimus delete <job_id> --redis-url redis://localhost:6379
```

### Using Key Prefix

```bash
# Via CLI flag
arq-optimus stats --redis-url redis://localhost:6379 --key-prefix myproject

# Or via environment variable
export ARQ_OPTIMUS_KEY_PREFIX=myproject
arq-optimus stats --redis-url redis://localhost:6379
```

## REST API

The dashboard exposes a REST API:

| Endpoint | Method | Description |
|---|---|---|
| `/api/status` | GET | Queue statistics |
| `/api/jobs` | GET | List jobs (query: `?status=running`) |
| `/api/jobs/count` | GET | Job count by status |
| `/api/jobs/{job_id}` | GET | Job details |
| `/api/jobs/{job_id}/cancel` | POST | Cancel a job |
| `/api/jobs/{job_id}` | DELETE | Delete a job record |

## Job Tracking Setup

For the dashboard to track job status transitions (running → completed/failed), wrap your worker functions with tracking:

```python
# arq_worker.py
from arq.connections import RedisSettings
from arq_optimus_dashboard.tracking import create_tracking_wrapper

async def my_task(ctx, arg):
    return f"processed {arg}"

class WorkerSettings:
    functions = [create_tracking_wrapper(my_task)]
    redis_settings = RedisSettings()
    key_prefix = 'myproject'
```

## Django Integration

```python
# settings.py
ARQ_OPTIMUS_KEY_PREFIX = 'my_project'

# arq_worker.py
from django.conf import settings
from arq.connections import RedisSettings
from arq_optimus_dashboard.tracking import create_tracking_wrapper

async def scrape_task(ctx, url):
    ...

class WorkerSettings:
    functions = [create_tracking_wrapper(scrape_task)]
    redis_settings = RedisSettings(host='redis.example.com', port=6379)
    key_prefix = getattr(settings, 'ARQ_OPTIMUS_KEY_PREFIX', '')
```

## Compatibility

- **Python**: 3.9+
- **Redis**: 5, 6, 7+
- **ARQ Optimus**: 0.27.0+

## Credits

Built on top of [ARQ Optimus](https://github.com/arpansahu/arq-optimus) by [Arpan Sahu](https://github.com/arpansahu).

## License

MIT License
