Exploitation & dépannage
Cette page rassemble tout ce dont vous avez besoin pour faire tourner Brume dans des conditions de niveau production : performance, ops, et les erreurs les plus courantes.
Performance
Section intitulée « Performance »Parallélisme
Section intitulée « Parallélisme »BRUME_PARALLELISM (défaut 4) contrôle le nombre de threads workers appliqués à l’étape de transformation. Augmentez-le sur des machines avec des cœurs disponibles et de bonnes I/O.
BRUME_PARALLELISM=12 brume executeLes retours décroissants apparaissent au-delà de 2 × cœurs physiques. Surveillez votre base source — Brume ouvre une connexion en lecture par worker.
fk_depth
Section intitulée « fk_depth »Un fk_depth plus faible extrait moins de données. Si votre bug est reproductible à la profondeur 2, ne payez pas pour la profondeur 4.
Pattern courant au moment du debug :
BRUME_FK_DEPTH_OVERRIDE=1 brume execute # run de smokeBRUME_FK_DEPTH_OVERRIDE=3 brume execute # run completBrume streame les lignes — il ne charge pas les tables en mémoire. Les deux endroits gourmands en mémoire sont :
- Les colonnes JSONB avec des
json_pathsprofondément imbriqués — le parsing/serialization se fait ligne par ligne mais le heap JVM grossit avec la taille des objets. - Les groupes
linked_columnsà forte cardinalité — le mapping déterministe est mis en cache en mémoire.
Démarrez avec le heap JVM par défaut et augmentez seulement si vous observez OutOfMemoryError dans les logs.
Gestion des secrets
Section intitulée « Gestion des secrets »Où stocker les secrets
Section intitulée « Où stocker les secrets »Par ordre de préférence :
- Un gestionnaire de secrets (Vault, AWS Secrets Manager, GCP Secret Manager, fichier chiffré SOPS).
- Les secrets du fournisseur CI (GitHub Actions encrypted secrets, GitLab masked variables).
- Fichier
.envdans un répertoire avec permissions POSIX strictes (chmod 600, possédé uniquement par l’utilisateur brume).
Ne jamais mettre .env sous git. Le .gitignore livré avec .env.example inclut les bons patterns.
Rotation des secrets
Section intitulée « Rotation des secrets »La rotation casse le déterminisme — la même valeur source atterrira sur un faux différent. Si un système aval dépend du déterminisme (jointures sur colonnes HASH-ées, références à des IDs mappés FPE_ID dans des rapports de bug, etc.), planifiez-la comme une bascule coordonnée :
- Choisissez une date.
- Arrêtez le rafraîchissement des environnements aval le jour de la rotation.
- Faites tourner les secrets.
- Re-exécutez
brume executesur tous les environnements aval. - Notifiez les utilisateurs que les anciens faux IDs ne sont plus valides.
Compte source en lecture seule
Section intitulée « Compte source en lecture seule »Voir la référence .env pour les grants SQL.
Compatibilité PostgreSQL
Section intitulée « Compatibilité PostgreSQL »Brume supporte PostgreSQL 14, 15, 16, 17 et 18 à la fois sur source et cible.
Le binaire pg_dump utilisé par Brume (pour la réplication du schéma) doit être sur le PATH et sa version majeure doit correspondre à celle de la source. Si votre source est Postgres 17, installez postgresql-client-17.
brume diag # vérifie la version pg_dump vs source| Flag | Niveau |
|---|---|
--quiet | ERROR |
| (défaut) | INFO |
--verbose | DEBUG |
Le rapport final par table est toujours imprimé sur stdout, peu importe le niveau.
Logs JSON
Section intitulée « Logs JSON »Utilisez --json pour l’ingestion machine (SIEM, agrégateur de logs, artefact CI) :
brume execute --json 2> logs.jsonlChaque ligne est un objet JSON avec timestamp, level, event, table et des champs contextuels.
Erreurs courantes
Section intitulée « Erreurs courantes »Connection refused
Section intitulée « Connection refused »FATAL: connection refused (host=db.prod.internal port=5432)La source ou la cible n’est pas joignable. Exécutez brume diag pour isoler laquelle. Vérifiez VPN, security groups, sslmode.
pg_dump version mismatch
Section intitulée « pg_dump version mismatch »pg_dump: error: server version: 17.2; pg_dump version: 14.10Installez le paquet postgresql-client-NN correspondant.
Strategy requires a type
Section intitulée « Strategy requires a type »configuration error: column `users.email` declares strategy FAKE but no `type`Ajoutez type: EMAIL (ou le type qui correspond). Voir stratégies et types.
NULLIFY on NOT NULL column
Section intitulée « NULLIFY on NOT NULL column »configuration error: column `users.created_at` is NOT NULL but strategy is NULLIFYChoisissez soit une stratégie non-null (FAKE, MASK, HASH, KEEP), soit faites un ALTER de la colonne pour la rendre nullable sur la cible.
JSONB path does not resolve
Section intitulée « JSONB path does not resolve »warning: path `$.contact.phone` never resolved across 12,498 rows of `users.metadata`Le chemin est faux ou n’existe dans aucune ligne de la colonne. Inspectez quelques lignes manuellement et ajustez le chemin. Brume continue le traitement — c’est un avertissement, pas une erreur fatale.
Uncovered PII columns (depuis brume plan)
Section intitulée « Uncovered PII columns (depuis brume plan) »plan est heuristique : il scanne les noms de colonnes à la recherche de patterns ressemblant à des PII (*_email, *_phone, *_name, address, iban, …). Revoyez chaque colonne signalée et :
- Soit ajoutez une règle dans
brume.yml, - Soit confirmez explicitement par une règle
strategy: KEEPpour documenter l’intention.
FK depth exceeded
Section intitulée « FK depth exceeded »warning: table `events` reached at depth 5, exceeds fk_depth=3 — not extractedLa table n’est pas incluse dans le sous-ensemble. Soit augmentez fk_depth, soit ajoutez la table comme racine supplémentaire dans extraction.tables.
- Recettes — workflows de production à copier-coller.
- RGPD & conformité — checklist de validation.
- Commandes CLI — flags et codes de sortie.