Add comprehensive documentation of metrics exported by this library

[romanek-adam-b2c2]

This PR adds comprehensive documentation for all metrics exported by the library, including HTTP request/response, database, and Django model metrics. The new documentation provides:

• A detailed table of HTTP metrics, including metric names, types, labels, and descriptions, covering request/response counts, latency, body sizes, status codes, exceptions, and more.
• Explanations of all metric labels and their meanings.
• Tables for database metrics, detailing connection counts, errors, query executions, and durations, with associated labels.
• Tables for Django model operation metrics (inserts, updates, deletes) by model.
• Notes clarifying metric usage, label conventions, and histogram bucket details.

This update aims to help users understand and monitor all Prometheus metrics exposed by the library, improving observability and troubleshooting for Django applications.

[Copilot]

Pull request overview

This PR adds comprehensive documentation for Prometheus metrics exported by the django-prometheus library. The documentation provides detailed reference tables for HTTP request/response metrics, database metrics, and Django model metrics to help users understand and monitor their Django applications.

Changes:

• Added new file documentation/metrics.md with comprehensive tables documenting HTTP, database, and Django model metrics including metric names, types, labels, and descriptions
• Updated README.md to add a "Metrics Reference" section linking to the new documentation

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
documentation/metrics.md	New comprehensive metrics reference documentation covering HTTP request/response metrics (20 metrics), database metrics (6 metrics), and Django model metrics (3 metrics) with detailed label explanations
README.md	Added link to new metrics documentation in a dedicated "Metrics Reference" section

Comments suppressed due to low confidence (18)

documentation/metrics.md:15

• The description says "Number of requests split by HTTP method" but the actual metric documentation in the code (django_prometheus/middleware.py:76) says "Count of requests by method." Consider using "Count" instead of "Number" and removing "split by" to match the implementation's more concise wording.

| `django_http_requests_total_by_method`                             | Counter   | `method`                      | Number of requests split by HTTP method (e.g., GET, POST).                                                               |

documentation/metrics.md:16

• The description says "Number of requests split by transport protocol" but the actual metric documentation in the code (django_prometheus/middleware.py:84) says "Count of requests by transport." Consider using "Count" instead of "Number" and removing "split by" to match the implementation's more concise wording.

| `django_http_requests_total_by_transport`                          | Counter   | `transport`                   | Number of requests split by transport protocol (`http` or `https`).                                                      |

documentation/metrics.md:23

• The description says "Number of responses split by charset" but the actual metric documentation in the code (django_prometheus/middleware.py:135) says "Count of responses by charset." Consider using "Count" instead of "Number" and removing "split by" to match the implementation's more concise wording.

| `django_http_responses_total_by_charset`                           | Counter   | `charset`                     | Number of responses split by charset (e.g., utf-8).                                                                      |

documentation/metrics.md:8

• The description says "Total number of HTTP requests received before middlewares run" but the actual metric documentation in the code (django_prometheus/middleware.py:27) says "Total count of requests before middlewares run." While functionally similar, "received" adds unnecessary detail since the metric simply counts requests. Consider matching the implementation's wording for consistency.

| `django_http_requests_before_middlewares_total`                    | Counter   | *(none)*                      | Total number of HTTP requests received before middlewares run.                                                           |

documentation/metrics.md:11

• The description says "Number of requests for which the latency was unknown" but the actual metric documentation in the code (django_prometheus/middleware.py:46-49) says "Count of requests for which the latency was unknown (when computing django_http_requests_latency_including_middlewares_seconds)." The parenthetical context is important because it clarifies which latency metric this counter relates to. Consider including this detail.

| `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`). |

documentation/metrics.md:53

• The description says "Number of execution errors by database, vendor and exception type" but the actual metric documentation in the code (django_prometheus/db/metrics.py:37) says "Counter of execution errors by database, vendor and exception type." Consider using "Counter" instead of "Number" to match the implementation's wording and maintain consistency with the metric type terminology.

| `django_db_errors_total`                | Counter   | `alias`, `vendor`, `type` | Number of execution errors by database, vendor and exception type.                  |

documentation/metrics.md:17

• The description says "Number of requests by view name, transport protocol, and HTTP method" but the actual metric documentation in the code (django_prometheus/middleware.py:91) says "Count of requests by view, transport, method." Consider using "Count" instead of "Number" to match the implementation's wording.

| `django_http_requests_total_by_view_transport_method`              | Counter   | `view`, `transport`, `method` | Number of requests by view name, transport protocol, and HTTP method.                                                    |

documentation/metrics.md:19

• The description says "Number of responses broken out by template name used for rendering" but the actual metric documentation in the code (django_prometheus/middleware.py:106) says "Count of responses by template name." Consider using "Count" instead of "Number" and simplifying the description to match the implementation's more concise wording.

| `django_http_responses_total_by_templatename`                      | Counter   | `templatename`                | Number of responses broken out by template name used for rendering.                                                      |

documentation/metrics.md:20

• The description says "Number of responses by HTTP status code" but the actual metric documentation in the code (django_prometheus/middleware.py:114) says "Count of responses by status." Consider using "Count" instead of "Number" to match the implementation's wording.

| `django_http_responses_total_by_status`                            | Counter   | `status`                      | Number of responses by HTTP status code (e.g., 200, 404).                                                                |

documentation/metrics.md:21

• The description says "Number of responses split by HTTP status, view name, and HTTP method" but the actual metric documentation in the code (django_prometheus/middleware.py:121) says "Count of responses by status, view, method." Consider using "Count" instead of "Number" and removing "split by" to match the implementation's more concise wording.

| `django_http_responses_total_by_status_view_method`                | Counter   | `status`, `view`, `method`    | Number of responses split by HTTP status, view name, and HTTP method.                                                    |

documentation/metrics.md:49

• The description says "Number of created connections by database and by vendor" but the actual metric documentation in the code (django_prometheus/db/metrics.py:7) says "Counter of created connections 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.

| `django_db_new_connections_total`       | Counter   | `alias`, `vendor`         | Number of created connections by database and by vendor.                            |

documentation/metrics.md:50

• The description says "Number of connection failures by database and by vendor" but the actual metric documentation in the code (django_prometheus/db/metrics.py:14) says "Counter of connection failures 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.

| `django_db_new_connection_errors_total` | Counter   | `alias`, `vendor`         | Number of connection failures by database and by vendor.                            |

documentation/metrics.md:51

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

| `django_db_execute_total`               | Counter   | `alias`, `vendor`         | Number of executed statements by database and by vendor, including bulk executions. |

documentation/metrics.md:24

• The description says "Number of streaming responses served" but the actual metric documentation in the code (django_prometheus/middleware.py:142) says "Count of streaming responses." Consider using "Count" instead of "Number" to match the implementation's wording.

| `django_http_responses_streaming_total`                            | Counter   | *(none)*                      | Number of streaming responses served.                                                                                    |

documentation/metrics.md:25

• The description says "Number of exceptions occurring, labeled by the exception object (class) type" but the actual metric documentation in the code (django_prometheus/middleware.py:149) says "Count of exceptions by object type." Consider using "Count" instead of "Number" to match the implementation's wording. Also, "object type" in the implementation is more concise than "exception object (class) type".

| `django_http_exceptions_total_by_type`                             | Counter   | `type`                        | Number of exceptions occurring, labeled by the exception object (class) type.                                            |

documentation/metrics.md:26

• The description says "Number of exceptions broken down by view name" but the actual metric documentation in the code (django_prometheus/middleware.py:156) says "Count of exceptions by view." Consider using "Count" instead of "Number" and simplifying the description to match the implementation's more concise wording.

| `django_http_exceptions_total_by_view`                             | Counter   | `view`                        | Number of exceptions broken down by view name.                                                                           |

documentation/metrics.md:67

• The description says "Number of update operations performed by each Django model" but the actual metric documentation in the code (django_prometheus/models.py:14) says "Number of update operations by model." While similar, consider matching the implementation's more concise wording.

| `django_model_updates_total` | Counter | `model` | Number of update operations performed by each Django model. |

documentation/metrics.md:9

• The description says "Total number of HTTP responses before middlewares run" but the actual metric documentation in the code (django_prometheus/middleware.py:33) says "Total count of responses before middlewares run." Consider matching the implementation's wording for consistency.

| `django_http_responses_before_middlewares_total`                   | Counter   | *(none)*                      | Total number of HTTP responses before middlewares run.                                                                   |

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

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

[romanek-adam-b2c2]

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.

[Copilot]

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. |

[romanek-adam-b2c2]

Same as in #497 (comment)