tessl/pypi-django-prometheus

Django middlewares to monitor your application with Prometheus.io

—

Pending

Overview

Eval results

Files

Database Monitoring

Name: tessl/pypi-django-prometheus
Author: tessl

Automatic monitoring of database operations through instrumented Django database backends. Tracks connection counts, query execution times, errors, and bulk operations across different database vendors.

Capabilities

Instrumented Database Backends

Django-prometheus provides instrumented versions of Django's database backends that automatically collect metrics on database operations.

# PostgreSQL backend
django_prometheus.db.backends.postgresql.base.DatabaseWrapper

# MySQL backend  
django_prometheus.db.backends.mysql.base.DatabaseWrapper

# SQLite backend
django_prometheus.db.backends.sqlite3.base.DatabaseWrapper

# SpatiaLite backend
django_prometheus.db.backends.spatialite.base.DatabaseWrapper

# PostGIS backend
django_prometheus.db.backends.postgis.base.DatabaseWrapper

Database Metrics Functions

from django_prometheus.db.common import DatabaseWrapperMixin

class DatabaseWrapperMixin:
    """
    Mixin that adds Prometheus monitoring to Django database backends.
    Automatically applied to all instrumented database backends.
    """
    
    def connect(self):
        """
        Instrumented database connection method.
        Tracks successful connections and connection errors.
        """
    
    def execute(self, sql, params=None):
        """
        Instrumented query execution.
        Tracks query count, execution time, and errors.
        
        Parameters:
        - sql: str, SQL query string
        - params: optional query parameters
        """
    
    def executemany(self, sql, param_list):
        """
        Instrumented bulk query execution.
        Tracks bulk operation count, execution time, and errors.
        
        Parameters:
        - sql: str, SQL query string
        - param_list: list of parameter sets for bulk execution
        """

Monitored Metrics

Connection Metrics

django_db_new_connections_total: Counter of created connections by database alias and vendor
django_db_new_connection_errors_total: Counter of connection failures by database alias and vendor

Query Execution Metrics

django_db_execute_total: Counter of executed statements by database alias and vendor (including bulk)
django_db_execute_many_total: Counter of bulk operations by database alias and vendor
django_db_query_duration_seconds: Histogram of query duration by database alias and vendor
django_db_errors_total: Counter of execution errors by database alias, vendor, and exception type

Configuration

Settings Configuration

Configure database backends in Django settings:

# settings.py
DATABASES = {
    'default': {
        'ENGINE': 'django_prometheus.db.backends.postgresql',  # Instead of 'django.db.backends.postgresql'
        'NAME': 'mydatabase',
        'USER': 'mydatabaseuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    },
    'cache_db': {
        'ENGINE': 'django_prometheus.db.backends.sqlite3',  # Instead of 'django.db.backends.sqlite3'
        'NAME': '/path/to/cache.db',
    }
}

Multiple Database Support

DATABASES = {
    'default': {
        'ENGINE': 'django_prometheus.db.backends.postgresql',
        'NAME': 'main_db',
        # ... connection settings
    },
    'analytics': {
        'ENGINE': 'django_prometheus.db.backends.mysql',
        'NAME': 'analytics_db',
        # ... connection settings
    },
    'cache': {
        'ENGINE': 'django_prometheus.db.backends.sqlite3',
        'NAME': '/tmp/cache.db',
    }
}

# Each database will be tracked separately with its alias as a label

Usage Examples

Basic Database Monitoring

# With instrumented backends, all ORM operations are automatically monitored
from myapp.models import User, Product

# These operations will be tracked in database metrics:
users = User.objects.filter(is_active=True)  # SELECT query tracked
user = User.objects.create(username='john')  # INSERT query tracked
user.email = 'john@example.com'
user.save()  # UPDATE query tracked
User.objects.filter(username='old').delete()  # DELETE query tracked

# Bulk operations
Product.objects.bulk_create([
    Product(name='Product 1'),
    Product(name='Product 2'),
])  # Bulk INSERT tracked

Raw SQL Queries

from django.db import connection

# Raw queries are also monitored
with connection.cursor() as cursor:
    cursor.execute("SELECT COUNT(*) FROM myapp_user WHERE is_active = %s", [True])
    result = cursor.fetchone()
    
# Bulk raw queries
cursor.executemany("INSERT INTO logs (message) VALUES (%s)", [
    ('Log message 1',),
    ('Log message 2',),
])

Database Routing with Monitoring

# When using database routing, each database is monitored separately
class DatabaseRouter:
    def db_for_read(self, model, **hints):
        if model._meta.app_label == 'analytics':
            return 'analytics'
        return 'default'

# Queries will be tracked with appropriate database alias labels
analytics_data = AnalyticsModel.objects.all()  # Tracked under 'analytics' alias
user_data = User.objects.all()  # Tracked under 'default' alias

Metric Labels

All database metrics include the following labels:

alias: Database connection alias (e.g., 'default', 'analytics', 'cache')
vendor: Database vendor (e.g., 'postgresql', 'mysql', 'sqlite')

Error metrics additionally include:

type: Exception class name (e.g., 'OperationalError', 'IntegrityError')

Supported Database Vendors

PostgreSQL: Full support including PostGIS extension
MySQL: Full support for MySQL and MariaDB
SQLite: Full support including SpatiaLite extension
Oracle: Not directly supported (would need custom backend)

Performance Considerations

Monitoring adds minimal overhead to database operations
Query timing uses high-resolution timers for accuracy
Connection pooling is compatible with monitoring
Bulk operations are efficiently tracked without per-item overhead

Error Monitoring

Database errors are categorized by exception type:

# Common error types tracked:
# - OperationalError: Connection issues, syntax errors
# - IntegrityError: Constraint violations
# - DataError: Invalid data for field type
# - DatabaseError: General database errors
# - InterfaceError: Database interface errors

Install with Tessl CLI

npx tessl i tessl/pypi-django-prometheus

docs

cache-monitoring.md

database-monitoring.md

http-monitoring.md

index.md

metrics-export.md

migration-monitoring.md

model-monitoring.md

testing-utilities.md

tile.json

tessl/pypi-django-prometheus