Django Insights

Django Insights

Django Insights, questions about your app as numbers and charts

How many people signed up this month? Which weekday do customers order? Is the refund rate going up? Django Insights answers questions like these straight from your own database, with a function per question, right next to the code it is about.

# shop/insights.py
from django_insights.metrics import metrics
from shop.models import Order


@metrics.counter(question="How many orders have been placed?")
def count_orders() -> int:
    return Order.objects.count()

Run python manage.py collect_insights and the answer shows up in a dashboard, and in a SQLite file you can query or share.

What can you do with it? #

Track the numbers that matter

Signups, active users, revenue, refund rate. A counter or a gauge, with a trend line.

See how things change

Time series, bar charts and scatter plots from the queries you already know.

Share without exporting data

Hand out one SQLite file with answers instead of CSV files with customer data.

Test your queries

Every insight is a plain function, so the pytest plugin tests it against your test database.

How it works #

  1. Write an insights.py in any of your apps. Each function is one question, and returns a number or the rows of a chart.
  2. Collect with python manage.py collect_insights, by hand or from cron. Django Insights runs every function against your database, and stores the answers in a separate SQLite database.
  3. Look at the built-in dashboard in your browser, or query the SQLite file from a script, a notebook or sqlite3.

Your own database is only ever read, by the queries you write. The answers are a cache: delete the insights database at any time and collect_insights rebuilds it, trends included.

Is it for you? #

It is a good fit when you want insights about the current state of your app that you can gather again at any moment: counts per day, averages, shares, top 10 lists. It is not a realtime source: no requests per second, no live counters. More in About.

Start in five minutes #

pip install django-insights

Then follow Getting started: you have your first insight in the dashboard in a few steps.

Upgrading from 0.2?

Version 0.3 needs Django 5.2+ and Python 3.11+, renamed some settings and has a database migration. Follow the upgrade checklist.

Supported: Django 5.2 (LTS), 6.0 and 6.1 (Django 6 needs Python 3.12+), on Python 3.11 to 3.14.