Skip to content

Add comprehensive documentation of metrics exported by this library #497

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
romanek-adam-b2c2 wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Add comprehensive documentation of metrics exported by this library #497

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
5d8fa27
Add comprehensive documentation of metrics exported by this library
romanek-adam-b2c2 Feb 3, 2026
363ba02
Fixed description of one metric
romanek-adam-b2c2 Feb 4, 2026
a0e6837
Add documentation for cache metrics
romanek-adam-b2c2 Feb 4, 2026
e003ec8
Tweak some descriptions to match others
romanek-adam-b2c2 Feb 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,10 @@ This library provides Prometheus metrics for Django related operations:
* Database access done via [Django ORM](https://docs.djangoproject.com/en/3.2/topics/db/)
* Cache access done via [Django Cache framework](https://docs.djangoproject.com/en/3.2/topics/cache/)

## Metrics Reference

For a detailed list and explanation of all metrics exported by this library, see [documentation/metrics.md](documentation/metrics.md).

## Usage

### Requirements
Expand Down
2 changes: 1 addition & 1 deletion django_prometheus/middleware.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ def register(self):
self.requests_latency_by_view_method = self.register_metric(
Histogram,
"django_http_requests_latency_seconds_by_view_method",
"Histogram of request processing time labelled by view.",
"Histogram of request processing time labelled by view name and HTTP method. ",
["view", "method"],
buckets=PROMETHEUS_LATENCY_BUCKETS,
namespace=NAMESPACE,
Expand Down
77 changes: 77 additions & 0 deletions documentation/metrics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# HTTP Request/Response Metrics

The following table lists and explains the HTTP request and response metrics produced by the `django_prometheus` project
middleware, which are relevant for monitoring the API endpoints in your Django application.

| Metric Name | Type | Labels | Description |
|--------------------------------------------------------------------|-----------|-------------------------------|--------------------------------------------------------------------------------------------------------------------------|
| `django_http_requests_before_middlewares_total` | Counter | *(none)* | Total number of HTTP requests received before middlewares run. |
| `django_http_responses_before_middlewares_total` | Counter | *(none)* | Total number of HTTP responses before middlewares run. |
| `django_http_requests_latency_including_middlewares_seconds` | Histogram | *(none)* | Histogram of request processing time (including middleware processing time). |
| `django_http_requests_unknown_latency_including_middlewares_total` | Counter | *(none)* | Number of requests for which the latency was unknown (for `django_http_requests_latency_including_middlewares_seconds`). |
| `django_http_requests_latency_seconds_by_view_method` | Histogram | `view`, `method` | Histogram of request processing time labeled by view name and HTTP method. |
| `django_http_requests_unknown_latency_total` | Counter | *(none)* | Number of requests for which the latency was unknown. |
| `django_http_ajax_requests_total` | Counter | *(none)* | Number of AJAX requests (`X-Requested-With: XMLHttpRequest`). |
Copy link

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description says "Number of AJAX requests" but the actual metric documentation in the code (django_prometheus/middleware.py:70) says "Count of AJAX requests." Consider using "Count" instead of "Number" to match the implementation and maintain consistency with other metric descriptions.

This issue also appears in the following locations of the same file:

  • line 15
  • line 16
  • line 23
  • line 8
  • line 11
  • ...and 8 more

Copilot uses AI. Check for mistakes.
Copy link
Author

@romanek-adam-b2c2 romanek-adam-b2c2 Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd suggest the descriptions of individual metrics within the code to be aligned to consistently use Count/Counter/Number and then update the documentation if needed, but that's something for a separate PR.

| `django_http_requests_total_by_method` | Counter | `method` | Number of requests split by HTTP method (e.g., GET, POST). |
| `django_http_requests_total_by_transport` | Counter | `transport` | Number of requests split by transport protocol (`http` or `https`). |
| `django_http_requests_total_by_view_transport_method` | Counter | `view`, `transport`, `method` | Number of requests by view name, transport protocol, and HTTP method. |
| `django_http_requests_body_total_bytes` | Histogram | *(none)* | Histogram distribution of incoming HTTP request body sizes (in bytes). |
| `django_http_responses_total_by_templatename` | Counter | `templatename` | Number of responses broken out by template name used for rendering. |
| `django_http_responses_total_by_status` | Counter | `status` | Number of responses by HTTP status code (e.g., 200, 404). |
| `django_http_responses_total_by_status_view_method` | Counter | `status`, `view`, `method` | Number of responses split by HTTP status, view name, and HTTP method. |
| `django_http_responses_body_total_bytes` | Histogram | *(none)* | Histogram distribution of outgoing HTTP response body sizes (in bytes). |
| `django_http_responses_total_by_charset` | Counter | `charset` | Number of responses split by charset (e.g., utf-8). |
| `django_http_responses_streaming_total` | Counter | *(none)* | Number of streaming responses served. |
| `django_http_exceptions_total_by_type` | Counter | `type` | Number of exceptions occurring, labeled by the exception object (class) type. |
| `django_http_exceptions_total_by_view` | Counter | `view` | Number of exceptions broken down by view name. |

## Labels

- `view`: Name of the Django view (or `<unnamed view>` if not resolved).
- `method`: HTTP method (`GET`, `POST`, etc.).
- `transport`: `http` or `https`, per request scheme.
- `status`: HTTP status code as string.
- `templatename`: Name of the template used, if applicable.
- `charset`: Character set of the response.
- `type`: Exception class name.

## Notes

- Metrics with no labels provide cumulative totals or global histograms.
- **Latency metrics** (`requests_latency_*`) record how long requests take. Separate metrics exist for end-to-end (
before middlewares, by view/method, etc.).
- **Body size metrics** record the distributions of incoming/outgoing body sizes in powers-of-two buckets.

# Database Metrics

| Metric Name | Type | Labels | Description |
|-----------------------------------------|-----------|---------------------------|-------------------------------------------------------------------------------------|
| `django_db_new_connections_total` | Counter | `alias`, `vendor` | Number of created connections by database and by vendor. |
| `django_db_new_connection_errors_total` | Counter | `alias`, `vendor` | Number of connection failures by database and by vendor. |
| `django_db_execute_total` | Counter | `alias`, `vendor` | Number of executed statements by database and by vendor, including bulk executions. |
| `django_db_execute_many_total` | Counter | `alias`, `vendor` | Number of executed statements in bulk operations by database and by vendor. |
| `django_db_errors_total` | Counter | `alias`, `vendor`, `type` | Number of execution errors by database, vendor and exception type. |
Comment on lines +49 to +53
Copy link

Copilot AI Feb 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The description says "Number of executed statements in bulk operations by database and by vendor" but the actual metric documentation in the code (django_prometheus/db/metrics.py:29) says "Counter of executed statements in bulk operations by database and by vendor." Consider using "Counter" instead of "Number" to match the implementation's wording and maintain consistency with the metric type terminology.

This issue also appears in the following locations of the same file:

  • line 53
  • line 49
  • line 50
  • line 51
Suggested change
| `django_db_new_connections_total` | Counter | `alias`, `vendor` | Number of created connections by database and by vendor. |
| `django_db_new_connection_errors_total` | Counter | `alias`, `vendor` | Number of connection failures by database and by vendor. |
| `django_db_execute_total` | Counter | `alias`, `vendor` | Number of executed statements by database and by vendor, including bulk executions. |
| `django_db_execute_many_total` | Counter | `alias`, `vendor` | Number of executed statements in bulk operations by database and by vendor. |
| `django_db_errors_total` | Counter | `alias`, `vendor`, `type` | Number of execution errors by database, vendor and exception type. |
| `django_db_new_connections_total` | Counter | `alias`, `vendor` | Counter of created connections by database and by vendor. |
| `django_db_new_connection_errors_total` | Counter | `alias`, `vendor` | Counter of connection failures by database and by vendor. |
| `django_db_execute_total` | Counter | `alias`, `vendor` | Counter of executed statements by database and by vendor, including bulk executions.|
| `django_db_execute_many_total` | Counter | `alias`, `vendor` | Counter of executed statements in bulk operations by database and by vendor. |
| `django_db_errors_total` | Counter | `alias`, `vendor`, `type` | Counter of execution errors by database, vendor and exception type. |

Copilot uses AI. Check for mistakes.
Copy link
Author

@romanek-adam-b2c2 romanek-adam-b2c2 Feb 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as in #497 (comment)

| `django_db_query_duration_seconds` | Histogram | `alias`, `vendor` | Histogram of query duration by database and vendor. |

## Labels

- `alias`: The Django database alias, which identifies the specific configured database connection.
- `vendor`: The database engine/vendor (e.g., "postgresql", "mysql", "sqlite") used for the connection.
- `type`: The type of error or exception encountered during database operations.

# Cache Metrics

| Metric Name | Type | Labels | Description |
|-----------------------------------|---------|----------|---------------------------------------------------------------------------|
| `django_cache_get_total` | Counter | *(none)* | Total number of cache `get` operations attempted. |
| `django_cache_get_hits_total` | Counter | *(none)* | Total number of cache `get` operations that resulted in a cache hit. |
| `django_cache_get_misses_total` | Counter | *(none)* | Total number of cache `get` operations that resulted in a cache miss. |
| `django_cache_get_fail_total` | Counter | *(none)* | Total number of cache `get` operations that failed (e.g., backend error). |

# Django Model Metrics

| Metric Name | Type | Labels | Description |
|------------------------------|---------|---------|---------------------------------------|
| `django_model_inserts_total` | Counter | `model` | Number of insert operations by model. |
| `django_model_updates_total` | Counter | `model` | Number of update operations by model. |
| `django_model_deletes_total` | Counter | `model` | Number of delete operations by model. |