Doc Technique – Endpoint Profiler (Analyseur de performance HTTP)

Endpoint Profiler – Analyseur de performance HTTP (v1.1)

Objectif : fournir un addon Django réutilisable qui analyse vos logs Nginx afin d’identifier rapidement :

Les endpoints les plus lents (p95, p99, max en secondes).
Les endpoints les plus volumineux (count).
Les taux d’erreurs HTTP (5xx) par endpoint.
Les chemins anormaux ou non normalisés (“/api/user/123/” → “/api/user/:id/”).
L’évolution au cours du temps grâce à un historique SQL (runs successifs).

Cet addon ne modifie jamais votre code applicatif : il se contente d’analyser les logs Nginx access et de produire :

un dashboard dédié à l’URL /endpoint-profiler/,
un JSON & CSV exportables,
et un historique en base de données (2 tables Django).

Étape 1 – Installation du plugin Django

1. Installation du package (via PyPI ou wheel interne)

Télécharger le package d'installation (.whl)

Version actuelle : 0.1.0 – build Python 3 (wheel universel).

Placez le fichier dans static/downloads/ côté projet, ou adaptez simplement le chemin ci-dessous.

⬇ Télécharger le .whl

pip install django-endpoint-profiler
                # ou installation depuis un wheel interne :

pip install dist/django_endpoint_profiler-0.1.0-py3-none-any.whl

2. Activation dans `settings.py`

INSTALLED_APPS += [
                "nginx_analyzer.apps.NginxAnalyzerConfig",  # Endpoint Profiler
                ]

                ENDPOINT_PROFILER = {
                # Fichiers de logs Nginx à analyser
                "LOG_FILES": [
                "/var/log/nginx/access.log",
                "/var/log/nginx/access.log.1",
                ],

                # Chemins de sortie (relatifs à BASE_DIR autorisés)
                "OUTPUT_JSON": "endpoint_stats.json",
                "OUTPUT_CSV": "endpoint_stats.csv",

                # Seuils et volume d'analyse
                "MIN_COUNT": 5,     # nombre min. de requêtes pour inclure un endpoint
                "TOP": 50,          # nombre max. de lignes affichées dans le dashboard

                # Template de base utilisé pour le dashboard
                "BASE_TEMPLATE": "base_dashboard_2025.html",
                }

3. Déclarer l’URL du tableau d’analyse

from django.urls import include, path

                urlpatterns = [
                ...
                path("endpoint-profiler/", include("nginx_analyzer.urls")),
                ]

4. Appliquer les migrations (historique SQL)

python manage.py makemigrations nginx_analyzer
                python manage.py migrate nginx_analyzer

5. Générer le premier fichier de stats

Lancez simplement :

python manage.py profile_endpoints

Cette commande lit vos logs, génère les fichiers JSON & CSV, remplit les tables SQL EndpointProfilingRun et EndpointStat, et le dashboard devient immédiatement consultable.

Étape 2 – Utilisation du Profiler

1. Lancer un profiling manuel avec différents réglages

# Exemple : conserver les 100 endpoints les plus sollicités
                python manage.py profile_endpoints --top 100 --min-count 10

2. Gestion de l’écriture SQL (historique)

Deux options permettent de contrôler l’impact sur la base :

# 1) Profiling sans écrire en base (JSON/CSV uniquement)
                python manage.py profile_endpoints --no-db

                # 2) Profiling avec "reset" : supprime l'historique avant d'écrire
                python manage.py profile_endpoints --reset-history

--no-db : idéal pour un cron “light” qui ne maintient pas d’historique.
--reset-history : garde un seul snapshot à jour (tables vidées avant chaque run).
Sans option : chaque exécution ajoute un nouveau run à l’historique.

3. Accéder au dashboard

Le dashboard web est disponible à l’URL suivante :

/endpoint-profiler/

Bouton “Rafraîchir les stats” → provoque un nouveau profiling.
Combo “Run” → permet de naviguer dans l’historique des analyses.
Bouton “Réinitialiser filtres” → remet méthode / chemin / min-count / tri à zéro.

4. Intégration Cron (Linux)

*/5 * * * * /opt/env/bin/python /opt/project/manage.py profile_endpoints

*/10 * * * * /opt/env/bin/python /opt/project/manage.py profile_endpoints --reset-history

Étape 3 – Outputs & Historique

1. Fichier JSON

Généré automatiquement à l’emplacement configuré :

Contenu : liste complète des endpoints, triés par p95 descendante. Chaque entrée contient : method, path, count, avg, p95, p99, max, error_rate, plus la distribution des statuts HTTP.

2. Fichier CSV

Pensé pour être importé dans Excel, Grafana, Google Sheets, etc.

Une ligne par endpoint.
Colonnes : method, path, count, avg, p95, p99, max, error_rate.

3. Historique SQL

L’addon maintient deux tables dédiées :

EndpointProfilingRun — un run (date, total_endpoints, logs sources...).
EndpointStat — toutes les stats d’un run (une ligne par endpoint).

Consultation facile via l’admin Django :

/admin/nginx_analyzer/endpointprofilingrun/
/admin/nginx_analyzer/endpointstat/

4. Dashboard Web

Tri dynamique par p95 / p99 / avg / max / volume / taux d’erreur.
Filtre par méthode HTTP (GET, POST...).
Filtre textuel sur le chemin (préfixe /api/, etc.).
Filtre sur le volume minimum de requêtes (Min. requêtes).
Navigation dans l’historique via la combobox “Run”.

Étape 4 – Sécurité & Dépannage

1. Fichier JSON vide ?

Cas typique : les logs Nginx ne contiennent pas le champ rt= ou $request_time sur lequel se base l’analyse.

Vérifiez :

le log_format Nginx inclut bien $request_time,
la variable ENDPOINT_PROFILER["LOG_FILES"] pointe sur les bons fichiers.

2. Dashboard inaccessible ?

L’URL /endpoint-profiler/ est bien déclarée dans votre urls.py projet.
Les templates nginx_analyzer/base.html et nginx_analyzer/dashboard.html sont présents.
Les migrations nginx_analyzer ont été appliquées (si vous utilisez l’historique SQL).

3. Rien ne s'affiche dans le tableau (0 endpoints) ?

Commencez par mettre MIN_COUNT = 1 dans ENDPOINT_PROFILER pour voir tous les endpoints.
Vérifiez que les fichiers de logs configurés ne sont pas vides.

Lancez la commande avec un chemin explicite :

python manage.py profile_endpoints --log-file /var/log/nginx/access.log

4. Erreurs d’admin liées aux timezones (MySQL / MariaDB)

Sous certaines distributions MySQL/MariaDB, l’option date_hierarchy de l’admin peut déclencher l’erreur : “Are time zone definitions for your database installed?”.

Solution : désactiver date_hierarchy dans l’admin EndpointProfilingRunAdmin et utiliser simplement un filtrage par date.

Packaging & Publication PyPI

Cette section explique comment transformer ce plugin Django en un package Python installable via pip, et éventuellement publiable sur PyPI.

1. Structure du package

Le plugin doit respecter l’arborescence standard Python. Cliquez ci-dessous pour afficher l’arbre complet.

2. Fichier `pyproject.toml`

[build-system]
                    requires = ["setuptools>=68", "wheel"]
                    build-backend = "setuptools.build_meta"

                    [project]
                    name = "django-endpoint-profiler"
                    version = "0.1.0"
                    description = "Django add-on to profile HTTP endpoints from Nginx logs."
                    readme = "README.md"
                    requires-python = ">=3.8"
                    authors = [{ name = "Ideo-Lab", email = "contact@ideo-lab.com" }]
                    license = { text = "MIT" }
                    dependencies = ["Django>=3.2"]

                    [tool.setuptools]
                    packages = ["nginx_analyzer"]
                    include-package-data = true

                    [tool.setuptools.package-data]
                    "nginx_analyzer" = [
                    "templates/**/*.html",
                    "static/**/*",
                    "management/commands/*.py",
                    ]

3. Fichier `MANIFEST.in`

include README.md
                    recursive-include nginx_analyzer/templates *.html
                    recursive-include nginx_analyzer/static *
                    recursive-include nginx_analyzer/management *.py

4. Construire le package (build local)

python -m pip install --upgrade build
                    python -m build
                    # Résultat : dist/django_endpoint_profiler-*.whl

5. Tester l'installation locale

pip install dist/django_endpoint_profiler-0.1.0-py3-none-any.whl

6. Publier sur PyPI (optionnel)

pip install twine
                    twine upload dist/*

À propos – Licence – Auteur

Licence

Ce plugin est distribué sous licence MIT. Vous pouvez l’utiliser librement dans des projets personnels ou professionnels.

Auteur

Développé par Ideo-Lab — DevOps, DBA, Performance, Cloud Engineering.
Site : https://www.ideo-lab.com

Contributions

Les suggestions, issues et pull requests sont les bienvenues.

Contact

Pour toute question : contact@ideo-lab.com