Django Prometheus business metrics

This Django app provides a Prometheus metrics endpoint serving so-called business metrics. These are metrics that are calculated when Prometheus hits the metrics endpoint.

Usage

1. Create a BusinessMetricsManager object and register some metrics:

   # project/business_metrics.py
   
   from django_business_metrics.v0 import BusinessMetricsManager, users
   
   metrics_manager = BusinessMetricsManager()
   
   # Add a pre-defined metric
   metrics_manager.add(users)
   
   # Add some custom metrics
   @metrics_manager.metric(name='name', documentation='documentation')
   def my_metric():
       return 10
   

2. Register a Prometheus endpoint:

   # project/urls.py
   
   ...
   from .business_metrics import metrics_manager
   
   ...
   urlpatterns = [
       ...
       path('business-metrics', metrics_manager.view),
       ...
   ]
   

3. Setup your Prometheus agent to scrape metrics from /business-metrics endpoint.

Development

Pre-requisites:

• uv
• nox - may be installed as uv tool install --with pyyaml --exclude-newer "14 days" nox
• docker and docker compose plugin

Ideally, you should run nox -s format lint before every commit to ensure that the code is properly formatted and linted. Before submitting a PR, make sure that tests pass as well, you can do so using:

nox -t check  # equivalent to `nox -s format lint test`

If you wish to install dependencies into .venv so your IDE can pick them up, you can do so using:

uv sync --all-extras --dev

Python / django version compatibility

Use cruft questionnaire to add/remove supported versions: cruft update --cookiecutter-input

Versioning

This package uses Semantic Versioning and Conventional Commits.

Commitizen may be used to generate commit messages:

uv tool install "commitizen==4.13.9"
git add ...
cz commit

Additionally, this package uses ApiVer to further reduce the risk of breaking changes. This means, the public API of this package is explicitly versioned, e.g. django_business_metrics.v1, and will not change in a backwards-incompatible way even when django_business_metrics.v2 is released.

Internal packages, i.e. prefixed by django_business_metrics._ do not share these guarantees and may change in a backwards-incompatible way at any time even in patch releases.

Release process

Releases are prepared explicitly by developers with help of Commitizen. Run cz bump which will:

• update the changelog
• make the bump commit and tag it

Then push the commit & tag to the repository, which will trigger the release workflow:

git push origin HEAD --follow-tags

• alpha, beta and rc releases are published to TestPyPI (use cz bump --prerelease alpha|beta|rc to create them)
• regular ones are published to PyPI