oban_lens

# ObanLens

Advanced job monitoring and filtering for Oban with persistent job history, time-based search, detailed forensics, and AI-powered insights.

![ObanLens Dashboard](https://via.placeholder.com/800x400/1f2937/ffffff?text=ObanLens+Dashboard+Preview)

## Features

✨ **Persistent Job History** - Automatically records all job executions to a history table for forensic analysis  
🔍 **Advanced Filtering** - Filter jobs by worker, queue, state, time range, duration, and search within job args  
⏰ **Time-Based Search** - Find jobs from specific time periods (e.g., "last Tuesday 2-4 PM")  
🔬 **Job Details & Forensics** - Click any job to see complete details including args, errors, attempts, and execution timeline  
📊 **CSV Export** - Export filtered job data for compliance audits and reporting  
🚀 **Real-time Dashboard** - LiveView dashboard with instant filtering and pagination  
⚙️ **Zero Configuration** - Works out of the box with Oban and Oban Pro  

## Installation

Add `oban_lens` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:oban_lens, "~> 0.1.0"}
  ]
end
```

## Quick Setup

**1. Create the database table:**
```bash
mix ecto.gen.migration create_oban_job_history
```

Add to your migration file:
```elixir
def change do
  ObanLens.Migration.create_job_history_table()
end
```

Run the migration:
```bash
mix ecto.migrate
```

**2. Start recording jobs:**

Add one line to your `application.ex`:
```elixir
def start(_type, _args) do
  ObanLens.Telemetry.attach()  # Add this line
  
  children = [
    # ... your existing children
  ]
  
  Supervisor.start_link(children, opts)
end
```

**3. Mount the dashboard:**

In your `router.ex`:
```elixir
defmodule MyAppWeb.Router do
  use MyAppWeb, :router
  import ObanLens.Router
  
  scope "/" do
    pipe_through :browser
    oban_lens_dashboard "/admin/oban"
  end
end
```

**4. Visit your dashboard at `/admin/oban`** 🎉

## Advanced Configuration

```elixir
# config/config.exs
config :oban_lens,
  # Specify repo (auto-detected from Oban if not set)
  repo: MyApp.ObanRepo,
  
  # How long to keep job history (default: 30 days)
  history_retention_days: 90,
  
  # What job states to record (defaults: all true)
  record_completed: true,
  record_failed: true,
  record_discarded: true
```

## Use Cases

### 🔍 **Forensic Analysis**
- Debug failed jobs with complete execution history
- Track job performance over time
- Identify patterns in job failures

### 📊 **Compliance & Auditing**  
- Export job data for compliance reports
- Maintain audit trails for critical processes
- Track SLA compliance for background jobs

### 🚀 **Performance Monitoring**
- Monitor job execution times and trends
- Identify slow or resource-heavy jobs
- Optimize queue configurations

### 🛠️ **Operations**
- Real-time monitoring of job processing
- Quick filtering to find specific jobs
- Historical analysis for capacity planning

## Dashboard Features

- **Real-time Filtering** - Filter by worker, queue, state, time range
- **Text Search** - Search within job arguments and metadata  
- **Job Details** - Click any job to see full execution details
- **CSV Export** - Export filtered results for analysis
- **Pagination** - Handle large job histories efficiently
- **Responsive Design** - Works on desktop and mobile

## Works With

- **Elixir** 1.14+
- **Oban** 2.15+ (Free and Pro versions)
- **Phoenix** 1.7+
- **PostgreSQL** (via Ecto)

## Roadmap

### v0.2.0 - AI & Alerts
- 🤖 Pattern detection in job failures
- 📢 Anomaly alerts (queue growth, failure spikes)
- 💡 Smart retry suggestions
- 🗣️ Natural language search

### v1.0.0 - Production Features
- 💾 Saved filter presets
- ⚙️ Custom alert configurations  
- 🚀 Performance recommendations
- 🔗 Webhook integrations
- 👥 Multi-tenant support

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Run tests (`mix test`)
4. Commit your changes (`git commit -m 'Add amazing feature'`)
5. Push to the branch (`git push origin feature/amazing-feature`)
6. Open a Pull Request

## Support

- 📖 **Documentation**: [hexdocs.pm/oban_lens](https://hexdocs.pm/oban_lens)
- 🐛 **Issues**: [GitHub Issues](https://github.com/your-username/oban_lens/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/your-username/oban_lens/discussions)
- 🗨️ **Community**: [Elixir Forum](https://elixirforum.com)

## License

Copyright © 2024 ObanLens

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.

---

**Made with ❤️ for the Elixir community**