Le problème que personne ne voit#
Il y a deux mois, j’ai déployé une API FastAPI en production et le serveur se comportait étrangement. CPU stable à 40-50% sans raison apparente. J’ai pensé que c’était une fuite mémoire, que c’étaient les logs, que c’était la base de données. C’était --reload.
Il s’avère que copier-coller la commande de développement directement dans le conteneur Docker est plus courant que cela ne devrait l’être. Et oui, uvicorn avec --reload fonctionne. Le serveur répond. Les requêtes vont vite. Mais il y a un coût que tu ne vois pas jusqu’à ce que tu aies 10K requêtes par jour.
Qu’est-ce que le file-watcher exactement#
Le flag --reload d’uvicorn lance un processus supplémentaire qui surveille tous les fichiers Python de ton projet. Pas seulement ton code. Tous.
Quand tu actives --reload, uvicorn :
- Démarre un gestionnaire de processus (watchfiles par défaut)
- Chaque X secondes (par défaut 0.4s) scanne tous les .py du répertoire
- Calcule les checksums ou hashs de chaque fichier
- S’il détecte des changements, redémarre le worker complet
- Pendant ce temps, continue à scanner à chaque cycle, même sans changements
Ce scan n’est pas gratuit. Dans un projet moyen avec 200 fichiers Python distribués dans vendor, les librairies et les modules propres, chaque cycle de watchfiles touche le disque et le CPU.
Comment il consomme du CPU à chaque requête#
La partie criminelle est que le file-watcher ne s’interrompt pas pendant les requêtes. Tandis que ton API traite une demande :
- Le moniteur continue à scanner les fichiers en arrière-plan
- Il entre en concurrence pour l’I/O du disque avec ton application
- Dans les conteneurs, si tu n’as pas de limites de ressources, il peut finir par consommer plus de CPU que la logique même de la requête
J’ai mesuré cela sur mon serveur. Avec une requête simple à un endpoint qui prend 50ms :
Sans --reload :
CPU: 2-3% por request
I/O wait: <1%Avec --reload :
CPU: 8-12% por request
I/O wait: 3-5%Cela ne semble pas beaucoup sur une requête isolée. Mais avec 100 requêtes concurrentes, cet overhead se multiplie.
Comment le détecter sur ton serveur#
1. Regarde les processus en exécution#
ps aux | grep uvicornSi tu vois deux processus uvicorn (ou un uvicorn + watchfiles), tu as --reload actif.
2. Vérifie ta commande de démarrage#
# MAL - esto es lo que probablemente tienes
uvicorn main:app --host 0.0.0.0 --port 8000 --reload
# BIEN - así debe estar en producción
uvicorn main:app --host 0.0.0.0 --port 80003. Surveille le CPU pendant un test de charge#
# Terminal 1: corre tu servidor
docker run -it tu-contenedor
# Terminal 2: genera carga
ab -n 1000 -c 10 http://localhost:8000/endpointObserve top ou docker stats. Si tu vois des pics inexplicables, soupçonne --reload.
4. Vérifie les logs d’uvicorn#
Avec --reload actif, tu verras des messages comme :
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO: Will watch for changes in these directories: ...Si tu vois “Will watch for changes”, tu as un problème.
La solution (c’est évident, mais important)#
Dans Docker, assure-toi que ton Dockerfile n’utilise PAS --reload :
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
# Aquí no va --reload
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]Pour le développement local, utilise --reload sans culpabilité :
uvicorn main:app --reloadCe que j’ai appris#
Le file-watcher d’uvicorn est excellent pour le développement. C’est transparent, cela fonctionne bien et cela accélère le cycle. Mais en production, c’est comme laisser l’ordinateur scanner avec un antivirus en continu.
J’ai examiné mes autres conteneurs après cela. J’en ai trouvé trois autres avec --reload actif. Après l’avoir supprimé, la consommation de CPU a baissé entre 30-45%.
C’est l’un de ces bugs qui n’en est pas vraiment un. Ton application fonctionne. Les requêtes sont traitées. Mais ton serveur effectue un travail invisible dont il n’a pas besoin.
La prochaine fois avant de déployer en production, grep pour --reload. Cela t’évitera une session de dépannage.
Équipement recommandé#
- Raspberry Pi 3 B+ — Serveur léger à faible consommation pour démarrer ton homelab
- Raspberry Pi 4 (4GB) — La base parfaite pour homelab, Docker et monitoring
Liens d’affiliation. Aucun coût supplémentaire pour toi.