Le site dbt docs par défaut fonctionne bien pour les petits projets. À grande échelle, les performances se dégradent en raison de l’architecture côté client. Les notes ci-dessous décrivent le goulot d’étranglement et les mesures d’atténuation disponibles dans le site par défaut, comme contexte pour décider quand passer aux alternatives.
Le problème d’architecture
Le frontend dbt docs est une application monopage AngularJS 1.x. AngularJS a atteint sa fin de vie en décembre 2021. Le framework n’a pas reçu de mises à jour depuis, et le dépôt dbt-docs le reflète — l’architecture frontend est restée largement inchangée.
Toute l’analyse de manifest.json et catalog.json se fait côté client, sur le thread principal du navigateur. Lorsqu’un utilisateur ouvre le site docs :
- Le navigateur télécharge
manifest.jsonetcatalog.json(ou lestatic_index.htmlcombiné) - JavaScript analyse les charges JSON complètes en mémoire
- AngularJS construit l’arbre des modèles, résout les relations et effectue le rendu de l’interface
- L’utilisateur peut interagir avec le site
Chaque étape se produit dans le navigateur. Il n’y a pas de rendu côté serveur, pas de pagination, pas de chargement paresseux des données de modèle. L’ensemble du projet est chargé en mémoire d’un coup.
Les chiffres à grande échelle
Dagster a analysé le site de documentation dbt de GitLab et a publié des benchmarks concrets :
| Métrique | Valeur |
|---|---|
| Taille de la charge JSON | 58 Mo |
| Temps de chargement de la page | ~48 secondes |
| Utilisation de la mémoire du navigateur | ~350 Mo |
| Score de performance Lighthouse | 68/100 |
À cette échelle, le site docs est pratiquement inutilisable. Les utilisateurs attendent près d’une minute que la page devienne interactive. Les onglets du navigateur consomment des centaines de mégaoctets de RAM. Sur les machines avec une mémoire limitée (courantes avec les ordinateurs portables d’entreprise exécutant plusieurs applications), l’onglet peut planter complètement.
Le seuil est plus bas que vous ne le pensez
Vous n’avez pas besoin de l’échelle de GitLab pour ressentir le problème. Les projets avec plus de 500 modèles commencent à montrer une lenteur notable — quelques secondes de chargement, des résultats de recherche retardés, une visualisation du DAG qui se fige lors du rendu de graphes de lignage complexes. À partir de 1 000 modèles, l’expérience se dégrade significativement pour une utilisation quotidienne.
Le flag --select sur dbt docs generate aide en limitant la génération du catalogue, mais le manifest contient toujours l’ensemble de votre projet. Si votre manifest seul est volumineux (nombreux modèles, macros et références inter-projets), les performances du frontend en souffrent indépendamment de la portée du catalogue.
Effets du VPN et du réseau
De nombreuses équipes hébergent dbt docs derrière un VPN d’entreprise. Les utilisateurs accédant au site via des connexions VPN font face à des vitesses de transfert plus lentes, ce qui amplifie le problème de charge JSON. Une charge de 20 Mo qui se charge en 2 secondes sur un réseau local peut prendre 10 à 15 secondes via un VPN. Combiné avec la surcharge d’analyse côté client, l’attente totale peut dépasser 30 secondes pour des projets de taille moyenne.
Si votre équipe accède à la documentation à distance (courant pour les équipes distribuées), prenez en compte le temps de transfert dans votre décision d’hébergement. L’hébergement via CDN aide avec la vitesse de transfert, mais ne peut pas résoudre le goulot d’étranglement d’analyse côté client.
Ce que vous pouvez faire dans le site par défaut
Sans remplacer le frontend, quelques mesures d’atténuation aident :
- Utiliser le flag
--staticpour produire un seul fichier, évitant plusieurs requêtes HTTP pour des fichiers JSON séparés - Limiter la génération du catalogue avec
--selectpour réduire la taille decatalog.jsonpour les modèles qui importent le plus - Masquer les modèles intermédiaires avec
docs.show: falsepour réduire le nombre de nœuds que le frontend traite (voir Options de personnalisation du site dbt Docs) - Héberger derrière un CDN (CloudFront, Cloud CDN, Cloudflare) pour minimiser le temps de transfert des assets statiques
Ce sont des mesures palliatives. Elles font gagner du temps mais ne résolvent pas le problème fondamental : le frontend a été conçu pour des projets avec des dizaines de modèles, pas des centaines ou des milliers.
Quand changer
Les signaux qui pointent vers des frontends de remplacement ou des catalogues de données : les plaintes de l’équipe sur les temps de chargement, les utilisateurs qui évitent le site docs, les contournements construits pour éviter l’interface par défaut. Le plafond de performance du frontend AngularJS est structurel — un meilleur hébergement ou une meilleure mise en cache ne le surmonte pas.