DEV Community

Harshil Jani
Harshil Jani

Posted on

Introducing fastapi-bgtasks-dashboard : One-liner integration on your FastAPI application

#python #fastapi #backend #development

FastAPI is a premier framework for constructing high-performance APIs, favored by tech giants, fintech firms, and e-commerce platforms for its asynchronous capabilities and efficiency.

One of its standout features is the BackgroundTasks class, which facilitates "fire-and-forget" operations such as email dispatching, data processing, or external API integrations. These tasks run post-response, ensuring non-blocking user experiences.

However, tracking it is not possible without having excessive logs. Constant log monitoring becomes impractical at scale, leading to opaque systems where tasks may fail silently, consume excessive resources, or inflate cloud costs.

To address this problem I've developed fastapi-bgtasks-dashboard, an open-source Python package that integrates a real-time dashboard into your FastAPI application with minimal effort. It's just a single line of change on your application which enables the entire real-time dashboard which trackes the background tasks.

Demo of fastapi-bgtasks-dashboard

Integration and Setup

Incorporating the dashboard is straightforward, requiring just one line of code after installation:

pip install fastapi-bgtasks-dashboard
Enter fullscreen mode Exit fullscreen mode

In your main application file:

from fastapi import FastAPI
from fastapi_bgtasks_dashboard import mount_bg_tasks_dashboard

app = FastAPI()

# Integrate the dashboard effortlessly
mount_bg_tasks_dashboard(app=app)
Enter fullscreen mode Exit fullscreen mode

Launch your server (e.g., via uvicorn main:app --reload), and navigate to http://localhost:8000/dashboard. The interface instantly populates with task details as they execute.

Under the hood, the package leverages FastAPI's dependency injection to capture tasks added through BackgroundTasks. It records essential metadata without altering your existing codebase. For example, consider a typical endpoint:

from fastapi import BackgroundTasks, FastAPI

@app.post("/analyze")
async def analyze_data(background_tasks: BackgroundTasks, data: dict):
    background_tasks.add_task(heavy_computation, data)
    return {"status": "Processing initiated"}

def heavy_computation(data: dict):
    # Simulate intensive processing
    import time
    time.sleep(10)  # Replace with actual logic
    print(f"Processed data: {data}")
Enter fullscreen mode Exit fullscreen mode

Triggering this endpoint queues the task, which appears in the dashboard with attributes like start time, duration (formatted in ms/s/m/h), parameters, status, and any exceptions.

Technical Features

It is already designed for enterprise-scale applications, the features that dashboard offers are:

  • Real-Time Monitoring: Utilizes WebSockets for live updates, ensuring instantaneous visibility into task progress without page reloads. This is built on Starlette's async infrastructure, aligning perfectly with FastAPI's ecosystem.

  • Interactive Controls: Sort and filter tasks by function name, status, or duration. Re-execute failed tasks with a single click, preserving original parameters.

  • Efficient Storage: Defaults to an in-memory, thread-safe dictionary, optimized for handling millions of tasks on modest hardware (1-2 GB RAM suffices, with metadata footprint in mere MBs). A "clear tasks" feature allows manual flushing to prevent memory bloat, ideal for long-running services.

Without such a tool, applications risk undetected inefficiencies—tasks could deadlock, leak memory, or violate SLAs in distributed environments like Kubernetes clusters.

Future Development Roadmap

Version 0.1.5 represents a stable release, with all known issues resolved. It focuses on core functionality without external dependencies.

Upcoming iterations will introduce persistent storage options, targeting Redis for caching in distributed systems and PostgreSQL for robust querying and historical retention.

Why Adopt This Tool?

For teams managing critical FastAPI systems such as real-time analytics or payment gateways—this dashboard mitigates blind spots, reduces debugging overhead, and optimizes resource utilization. It prevents production meltdowns and curtails unnecessary cloud expenditures, fostering reliable, scalable architectures.

Explore the full documentation on PyPI or the GitHub repository. I encourage starring the repo to support visibility and contributing via pull requests—whether enhancing integrations, adding metrics (e.g., Prometheus), or refining the UI.

My vision is to integrate this into the official FastAPI ecosystem, and improve the background task handling industry-wide. Let's collaborate to make FastAPI applications more resilient and observable. Feedback and experiences with background task challenges are welcome in the comments!

Top comments (0)