Metrics
A metric is a function in an insights.py file with a decorator that says what kind of answer it returns. Django Insights has six, from a single number to a chart.
Which metric do I need? #
| Your question looks like | Use | Page |
|---|---|---|
| “How many…?” A whole number | @metrics.counter |
Counter |
| “What is the average…?” A percentage, a ratio, a decimal | @metrics.gauge |
Gauge |
| “How many per day, week, month…?” | @metrics.timeseries |
Time series |
| “Does A depend on B?” Two numbers per item | @metrics.scatterplot |
Scatter plot |
| “How many per category?” A few to a dozen categories | @metrics.barchart |
Bar chart |
| “Which are the top 10?” Many or long category names | @metrics.hbarchart |
Horizontal bar chart |
Counters and gauges can also show a trend: a small line with the change against the previous period.
Every metric #
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()
- The function name is the label of the insight, unique per app. Keep it stable: it identifies the insight in the database and in your tests.
questionis shown on the dashboard. Write it as the question you want answered.descis an optional line of explanation under it.- The function runs your own queries on your own databases. It must only read.
- A function that raises is reported and skipped, the others still run. See Collecting.
Options of the charts #
The four chart types share these options, all optional:
| Option | Does |
|---|---|
xlabel, ylabel |
the names of the axes |
title |
a title above the chart |
xformat |
how a timestamp is shown in the data table, "%Y-%m" for example |
yformat |
stored with the chart, the dashboard does not use it yet |
What to return #
The chart types return an iterable of tuples, a QuerySet from values_list(...) works. The position of each value matters:
| Type | Row | Notes |
|---|---|---|
timeseries |
(timestamp, value) |
timestamp is a datetime, oldest first |
scatterplot |
(vertical, horizontal, category) |
the first value is drawn on the vertical axis |
barchart |
(height, unused, label) |
the second value is stored, but not drawn |
hbarchart |
(length, unused, label) |
the length is shown behind the bar, labels over 30 characters are cut |
A missing label (None) is shown as an empty label. Annotate your functions with TimeSeriesResult, ScatterPlotResult and BarChartResult from django_insights.metrics_types.
Tip
Not sure how to start? Recipes has a complete insight for common questions.