Summary
Key takeaways
- Begin a Django performance audit with one slow customer-facing route and a reproducible tenant cohort.
- Compare matched warm and cold workloads using request p95, error rates, throughput, query counts, and correctness.
- Use end-to-end traces to separate pre-view delays, connection waits, SQL time, application work, and response rendering.
- Count repeated queries across page sizes before using select_related for to-one relations or prefetch_related for many-valued relations.
- Examine PostgreSQL query plans and realistic key distributions before adding an index.
- Validate cache keys, permissions, invalidation, and cold-path latency before relying on Redis.
- Measure Celery queue delay and job completion independently of fast HTTP acknowledgements.
- Check the connection budget before increasing Django or Celery worker concurrency.
- Use the same release worksheet for latency, SQL calls, HTTP errors, dropped iterations, queue wait, and access parity checks.
- Retain an assertNumQueries test and matched load test after deploying the improvement.
When this applies
Use this process when a live Django SaaS route is slow for a repeatable tenant or user cohort, especially when PostgreSQL, ORM access, Redis caching, or Celery work may contribute to latency. It also applies when a candidate change must pass explicit production-like p95 and correctness thresholds before release.
When this does not apply
A single application-wide average or an unmatched load-test run is not enough to justify a release decision. The SQL-focused steps are not a substitute for investigating external dependency delays, response serialization, or background-job completion when the trace identifies those as the main source of user wait.
Checklist
- Choose a slow customer-visible route and affected tenant cohort.
- Record release SHA, environment, fixture shape, page size, cache state, and errors.
- Establish a matched request-rate and measurement window.
- Run warm and cold scenarios separately.
- Track completed requests, HTTP errors, and dropped scheduled iterations.
- Inspect fast and slow traces from the same cohort.
- Separate connection acquisition wait from elapsed SQL time.
- Count SQL calls at two representative result sizes.
- Test select_related or a bounded prefetch only for relations the page renders.
- Review EXPLAIN plans and index tradeoffs for remaining expensive queries.
- Test cache scoping, invalidation, and cold-path performance.
- Measure linked job queue wait, runtime, and final result.
- Compare connection demand with available database capacity before scaling workers.
- Check warm and cold p95, errors, SQL calls, queue wait, and access parity against release criteria.
- Add a fixed-fixture query-count regression test and retain the matched load test.
Common pitfalls
- Using a healthy site-wide average to dismiss a slow enterprise-tenant route.
- Comparing component-level p95 readings as if they came from the same request.
- Accepting improved latency from a load generator that dropped scheduled work.
- Optimizing indexes when connection-pool wait is the actual bottleneck.
- Prefetching relationships that the response never renders.
- Trusting a cached warm result without checking cold misses, permissions, or invalidation.
- Calling a workflow fast because its HTTP response returns before the background result.
- Adding workers without accounting for cumulative database connections.
- Approving a faster route without validating errors and access or response parity.
- Protecting only query count while neglecting latency regressions caused by plans or pool pressure.
Start a Django performance audit with a slow route and a user cohort you can reproduce. Uvik Software follows one request into the application, connection pool, PostgreSQL, and response rendering before choosing a fix. Replay the same traffic after the change and check p95, errors, query counts, and correctness together. Where the user is waiting for an export or another job, measure time to the finished result as well.
A route can be slow for large tenants while the site average looks healthy. Track p95, the latency at or below which 95% of eligible requests finish, by route and a small set of useful workload attributes such as tenant size or page size. Let the affected customer workflow determine the benchmark. Django performance and optimization documentation
Record a representative baseline
Take the first pending approvals page for an enterprise tenant. Record the release SHA, environment, data shape, request volume, cache state, and errors. Reuse them for the candidate. For this route, the size of the tenant and its relationships can change the result as much as the number of requests.
In production, start with existing traces and aggregates. Count how many requests each route contributes and confirm that the time window contains the workload you care about. In a performance environment, replay a representative request mix with production-like cardinality. Run warm and cold scenarios independently. Track completed requests alongside errors and dropped iterations. A load generator that fails to deliver the intended request rate can make a result appear better as the application slows. Grafana k6 constant arrival rate · Grafana k6 dropped iterations
Use one end-to-end measurement for the release gate. Individual span durations explain where time went for a request. Component p95 values usually describe different requests, so use a trace-level critical path to explain the total.
Follow a request from Django to PostgreSQL
Open traces for fast and slow requests from the same cohort. Check whether time is spent before the view runs, in the application, waiting on a database connection, executing queries, calling a dependency, or serializing a response. Preserve the route and fixture shape when reproducing the slow trace. Raw customer payloads and query argument values are usually unnecessary for this work.
| Pattern in the trace | Evidence to collect | First thing to test |
|---|---|---|
| Similar SELECT statements repeat for each item | Query count over several result sizes and the serializer or template field involved | Fetch to-one relations in the base query and prefetch the many-side only when rendered |
| One query dominates slow requests | SQL shape, plan, rows read or filtered, representative key distributions | Better query shape, narrower result or index matched to the actual filter and sort |
| Connection wait dominates | Pool occupancy, worker concurrency, database connections and lock waits | Remove long-held connections or transactions before raising concurrency |
| Cache busy period precedes a spike | Hit rate, key scope, expiry pattern and source-of-truth reads | Validate invalidation and test bounded caching for the affected shape |
| The response is fast and the result appears late | Time from job enqueue to start, run duration, retries and oldest waiting job | Inspect queue routing, capacity and slow jobs for that workflow |
| Application time remains high with little DB time | CPU profile, payload size and external call durations | Trim serialization or remove an unnecessary dependency from the request path |
Count and time SQL calls on one request with Django’s execution wrapper. Inspect aggregate query pressure separately with PostgreSQL’s pg_stat_statements, where enabled. Use a bounded observation period or differences between two snapshots. That keeps old traffic out of the diagnosis. Django database instrumentation · PostgreSQL pg_stat_statements
Measure SQL time and connection wait independently
In an illustrative slow request, the elapsed time is 920 ms. The server waits 80 ms before entering the view, the view waits 260 ms for a database connection, SQL calls account for 420 ms, and the remaining application and outbound work takes 160 ms. These are exclusive portions of one request. If the same SQL shape is fast once it acquires a connection, investigate pool pressure and long-held transactions before changing indexes.
Wrap the rendering path in a test environment when you need query counts or durations. The example records elapsed time and avoids collecting query text and parameters. Substitute your authenticated request and materialize the response within the wrapper.
from time import perf_counter
from django.db import connection
durations_ms = []
def time_sql(execute, sql, params, many, context):
start = perf_counter()
try:
return execute(sql, params, many, context)
finally:
durations_ms.append((perf_counter() - start) * 1000)
with connection.execute_wrapper(time_sql):
render_approval_list(request)
Run the wrapper on a fresh request for each test case. Its elapsed SQL time describes client-observed execution. Use your database and pool telemetry to investigate server waits and connection acquisition separately. Django execution wrapper documentation · PostgreSQL activity statistics
Isolate one ORM change before adding infrastructure
Consider a Django approvals page that lists 50 requests and shows each requester’s name. If Django fetches the requester once per result, the list uses 51 queries for that part of the load. A join to that single-valued relation can retrieve the list and requesters in one query. Measure the query count, transferred bytes, and route latency at the same page size. Keep tenant scope, permissions, and ordering fixed. Django QuerySet reference
approvals = (
Approval.objects
.filter(tenant_id=tenant_id, status=Approval.Status.PENDING)
.select_related("requester")
.order_by("-updated_at", "-id")
)
page = list(approvals[:50])
For a list of many-valued relations, test prefetch_related when the page actually displays them. An eager fetch can add memory or query cost when the UI never uses the relation. Keep result sets bounded and assert the rendered fields. If the query itself remains slow, use QuerySet.explain to inspect the plan. Test a composite index such as tenant, status, updated timestamp, and ID only where the slow workload uses that filter and order. Measure the change in execution and the cost to writes and storage. Django database access optimization
A planned and an executed plan answer different questions. PostgreSQL EXPLAIN shows the estimated plan. EXPLAIN ANALYZE executes the statement and reports measured work, so use it on an approved environment with bounded queries and realistic data. Check row-estimate errors, sorts, scans, and waits before treating an index as the answer. PostgreSQL EXPLAIN
Sentry’s published Django demonstration uses a list of tweets and their owners. It showed nine queries for the lazy related lookup and one after eager-loading the owner with select_related. That is a query-count result for a short example. In a SaaS audit, test the list at two realistic page sizes. If the count stays flat and p95 still climbs, profile the query plan, bytes returned, and connection-pool wait. Sentry’s original database optimization demonstration
Figure 1. Sentry’s Django demonstration reduced the queries needed to read tweets and their owners from nine to one. Sentry database optimization example
Account for caching and work after the response
Add caching where the trace shows repeated work and where staleness has a defined cost. A tenant-specific approvals response may depend on permissions, filters, and sorting as well as tenant ID. Include those factors in the key or cache only shared source data that can be scoped safely. Check invalidation when an approval changes and test the cold path after a deployment. If a cache invalidation or background job depends on a successful database transaction, schedule it after the commit. Django transaction guidance
Keep a separate view of Celery queue wait and execution time when the user expects an export, an index update, or a report. A fast HTTP acknowledgement can coexist with a slow result. Compare when the job was queued with when the worker started, then measure its runtime and final state. Inspect retries and the oldest waiting job before adding workers. Extra concurrency can move pressure from the queue to PostgreSQL. Celery monitoring and events
Check whether concurrency can shift the bottleneck
Estimate the upper exposure on the database before adding web or background workers. A modeled deployment with six web replicas, four processes per replica, and two concurrent database-using threads per process can present up to 48 web-side connections if each active thread holds one. Six Celery worker instances at concurrency three can add 18 more under the same assumption. That is 66 possible application connections before administrative, migration, and other services. Measure actual open and waiting connections as well as pool behavior. Session reuse, a pooler, task implementation, and deployment overlap can change the real count.
Record the reason you chose the concurrency budget. If the database has capacity for 60 application connections after other reservations, the modeled configuration exceeds it by six. You can test changes to worker concurrency or transaction duration before scaling the application. Compare p95 connection wait, p95 request latency, throughput, and queue wait in the same run to see where the pressure went. Django database connection guidance
Approve the release with a p95 worksheet
Copy the worksheet below for one route and one user cohort. The values are illustrative. The warm runs each represent 15,000 attempts at 25 requests per second for 10 minutes in the same performance environment. The cold run uses its own repeatable reset and measurement window. Query count comes from the same representative request before and after. Keep the version, environment, time window, fixture, and test script next to the table.
[CAPTION: Illustrative Django p95 latency comparison for warm and cold workloads]
Figure 2. Uvik Software’s illustrative matched test. Warm and cold p95 readings use distinct workload conditions, and both show the change in the example.
| Measure | Baseline | Candidate | Example release criterion |
|---|---|---|---|
| Warm request p95 | 910 ms | 430 ms | At or below 500 ms |
| Cold request p95 | 1,150 ms | 550 ms | At or below 650 ms |
| SQL calls on the fixed 50 item request | 67 | 7 | At or below 10 |
| HTTP errors in warm run | 45 of 15,000 | 30 of 15,000 | At or below 0.5% |
| Dropped scheduled iterations | 0 | 0 | Zero |
| p95 queue wait for a linked export | 3.4 s | 3.8 s | At or below 5 s |
| Access and response parity tests | 12 of 12 pass | 12 of 12 pass | All required checks pass |
The modeled warm p95 improves by 52.7%, from 910 ms to 430 ms, leaving 70 ms of headroom against the 500 ms limit. Errors fall from 0.30% to 0.20%. With 15,000 eligible observations, the nearest-rank p95 is the 14,250th sorted value. Record how the measurement tool handles errors and timeouts, then use the same convention for the candidate. The sample passes the release thresholds.
Keep the fix in the test suite after the rollout. Use Django’s assertNumQueries on a fixed 50-item fixture to catch an N plus one regression. Use the matched load test for latency, since a constant query count can still hide a bad plan or connection wait. Django testing tools
What Uvik Software changed on a B2B SaaS workflow
Uvik Software’s published Django SaaS case measured approval workflow API latency at about 1.4 seconds p95 before tuning. The team profiled the workflow, optimized database queries, added Redis caching, and moved suitable work to background jobs. The audit started with the approval path that users waited on. Uvik Software’s Django SaaS case study
For a different kind of Django workload, Uvik Software’s Sentry case reports that event ingestion throughput moved from 420,000 to 1.4 million events per second, based on load test reports. The case’s APM figures show a move from 740 ms to 38 ms at p99 for ingestion acceptance. Those measures apply to ingestion, with buffering, deduplication, and quota changes. Choose the endpoint percentile or throughput metric that matches the business action you audit. Uvik Software’s event ingestion case study
If the problem extends to ongoing support, see Uvik Software’s guide to Django maintenance scope and SLAs. For Django consulting and performance audits, bring Uvik Software one affected route, a scrubbed trace, and the current latency budget.