ObanLens

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

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:

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

Quick Setup

1. Create the database table:

mix ecto.gen.migration create_oban_job_history

Add to your migration file:

def change do
  ObanLens.Migration.create_job_history_table()
end

Run the migration:

mix ecto.migrate

2. Start recording jobs:

Add one line to your application.ex:

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:

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

# 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 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
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🗨️ Community: Elixir Forum

License

Copyright © 2024 ObanLens

Licensed under the Apache License, Version 2.0. See LICENSE for details.

Made with ❤️ for the Elixir community