Logs de build et d’exécution : déboguer les déploiements Dockup

Les logs de build et d’exécution répondent à des questions différentes. Les logs de build expliquent comment le code source a été transformé en image et pourquoi ce processus a échoué. Les logs d’exécution expliquent ce que l’application déployée a fait après le démarrage du conteneur ou de la charge de travail Kubernetes.

Lire le mauvais flux fait perdre du temps. Une dépendance manquante lors de la construction de l’image n’apparaîtra jamais dans les logs d’exécution, tandis qu’une image créée avec succès peut planter au démarrage malgré une sortie de build parfaitement propre.

Quelle est la différence entre les logs de build et les logs d’exécution ?

Appuyez-vous sur l’étape du déploiement pour choisir le flux approprié :

Étape	Statut habituel	Log approprié	Échecs courants
Clonage	cloning	Build	Accès au dépôt, branche
Installation des dépendances	building	Build	Lockfile, registre, package
Compilation/bundling	building	Build	Erreurs de type, mémoire, fichiers manquants
Démarrage de l’image	deploying	Exécution et health	Commande de démarrage, port, permissions
Service en cours d’exécution	running	Exécution	Exceptions, indisponibilité des dépendances
Contrôle de readiness	deploying	Exécution et configuration health	Chemin incorrect, démarrage lent

Lisez la dernière sortie de build :

dockup logs production/api --build --json

Lisez la sortie d’exécution du service en cours :

dockup logs production/api --json

Demandez davantage de lignes d’exécution lorsque l’événement pertinent est plus ancien :

dockup logs production/api -n 500 --json

La réponse JSON identifie la cible et le type de log, ce qui aide un agent à éviter de fusionner des flux sans rapport.

Comment fonctionne dockup logs --build --follow ?

Le mode de suivi diffuse les nouvelles lignes en interrogeant l’instantané actuel :

dockup logs production/api --build -f --json

En mode JSON, la sortie est au format NDJSON : un objet par ligne et par lot. Un consommateur peut traiter chaque ligne progressivement.

Un dernier lot indique le résultat final du build. La commande s’arrête automatiquement lorsque le déploiement réussit ou échoue et renvoie un code différent de zéro en cas d’échec. Elle convient donc à un agent ou à un job CI sans nécessiter de boucle de vérification d’état écrite manuellement.

Le suivi de l’exécution fonctionne de manière similaire :

dockup logs production/api -f --json

Chaque lot inclut restarted. Lorsque restarted:true, le conteneur a redémarré ou le buffer de logs conservé a effectué une rotation ; Dockup réémet donc l’intégralité de l’instantané actuel au lieu d’abandonner silencieusement certaines lignes.

L’intervalle d’interrogation par défaut est de 2 secondes. Utilisez --interval uniquement lorsqu’il existe une raison précise de modifier cette fréquence.

Comment diagnostiquer un build en échec ?

Commencez par consulter le résultat final du déploiement :

dockup deploy production/api --wait --json

Lorsqu’il se termine avec deploy_failed, récupérez le build log et recherchez la première erreur causale, pas le dernier message de cascade.

Voici une séquence utile :

1. Confirmez la cible et l’ID du déploiement.
2. Identifiez l’étape de clonage, d’installation, de compilation ou de création de l’image.
3. Recherchez la première erreur qui ne peut pas être corrigée par une nouvelle tentative.
4. Comparez la méthode de build avec les attentes du dépôt.
5. Reproduisez le problème depuis un clone propre si possible.
6. Apportez une modification ciblée.
7. Redéployez avec --wait.

Les échecs courants de Nixpacks incluent une racine de projet non reconnue, un lockfile manquant, l’absence d’un script de démarrage conventionnel ou la nécessité d’installer un package natif. Les échecs courants liés au Dockerfile incluent un contexte de build incorrect, un artefact non copié, une image de base indisponible ou une instruction RUN en échec.

Le guide Nixpacks vs Dockerfile propose une carte de décision pour choisir le système de build.

Évitez de corriger une erreur de build déterministe en augmentant le délai d’expiration de 900 secondes. Modifier le délai aide lorsqu’un build légitime est long ; cela ne répare pas une commande qui s’est terminée avec une erreur.

Comment diagnostiquer un crash d’exécution ou un échec de health check ?

Une image créée avec succès peut tout de même échouer avant le basculement du trafic. Inspectez l’état du service et sa sortie d’exécution :

dockup status production/api --json
dockup logs production/api --json
dockup health production/api --json

Recherchez notamment les situations suivantes :

• Le processus s’arrête immédiatement après le démarrage.
• L’application utilise le mauvais port.
• L’application écoute sur 127.0.0.1 au lieu de toutes les interfaces.
• Une variable d’environnement requise est absente.
• La connexion à PostgreSQL ou Redis échoue.
• Les permissions de fichiers empêchent le démarrage.
• Le endpoint de health renvoie un statut différent d’un succès.
• Le démarrage prend plus de temps que ne l’autorisent les nouvelles tentatives configurées.
• Une migration échoue ou s’exécute en parallèle.

La configuration de health peut être consultée ou mise à jour :

dockup health production/api \
  --path /healthz \
  --interval 5 \
  --timeout 3 \
  --retries 5 \
  --json

N’assouplissez pas le contrôle de health simplement pour faire passer une release défectueuse. Si le démarrage nécessite légitimement davantage de temps, modifiez la policy en vous appuyant sur des éléments concrets et conservez un endpoint qui prouve toujours la readiness.

Les modifications d’environnement nécessitent un nouveau déploiement. Si un secret manquant est corrigé, redéployez puis attendez ; le redémarrage de l’ancien conteneur n’applique pas le nouvel environnement souhaité.

Comment les agents doivent-ils analyser le NDJSON sans perdre le code de sortie ?

Un agent ou un script doit lire chaque ligne JSON tout en préservant le statut du processus. Évitez de rediriger la sortie vers une commande qui masque le code de sortie d’origine sans pipefail.

set -o pipefail
dockup logs production/api --build -f --json \
  | tee build-stream.ndjson

Avec pipefail, une commande Dockup en échec conserve un code différent de zéro pour l’ensemble du pipeline, même si tee s’est terminé correctement.

Un consommateur peut inspecter chaque objet indépendamment :

while IFS= read -r line; do
  printf '%s\n' "$line" | jq -r '.lines[]?'
done < build-stream.ndjson

Conservez l’artefact NDJSON brut. Un extrait lisible est utile dans une pull request ou lors d’un incident, mais les champs d’origine préservent les marqueurs de redémarrage, le statut et les signaux de fin.

Les principes généraux des interfaces machine sont expliqués dans Concevoir une CLI pour les agents IA.

Quel runbook reproductible utiliser pour déboguer un déploiement ?

Suivez ce parcours de décision :

dockup status production/api --json
dockup deployments production/api -n 5 --json
dockup logs production/api --build --json
dockup logs production/api --json

Classez ensuite l’incident :

Classification	Éléments probants	Action suivante
Source/build	Erreur dans le build log	Corriger le dépôt ou la définition du build
Configuration	Variable d’environnement ou port absent/incorrect	Corriger la configuration et redéployer
Readiness	L’application fonctionne, mais le health check échoue	Corriger le endpoint ou ajuster le délai avec justification
Dépendance d’exécution	Exception de connexion	Vérifier la base de données, le réseau et les identifiants
Régression	La version précédente fonctionnait	Envisager un rollback vers un ID connu
Incertitude liée à la plateforme	Timeout, absence d’état final	Inspecter le statut avant de réessayer

N’effectuez un rollback qu’après avoir identifié un déploiement précédent connu :

dockup rollback <deploymentId> production/api --json

Conservez d’abord l’ID du déploiement en échec et ses logs. Un rollback rétablit la disponibilité du service ; il n’explique pas la cause racine.

L’article sur les déploiements zero-downtime explique pourquoi un contrôle de readiness en échec peut protéger le trafic en production.

Comment rendre les logs de production utiles ?

Dockup peut récupérer la sortie, mais la qualité des logs dépend de l’application. Privilégiez des enregistrements structurés, correspondant à un seul événement, avec un horodatage, un niveau de gravité, des IDs de requête ou de trace, le nom du composant et une description sûre de l’erreur.

Ne journalisez jamais les tokens d’accès, les URLs de base de données, les mots de passe, les en-têtes d’autorisation complets ni les données personnelles inutiles au fonctionnement. Le masquage des secrets dans la configuration Dockup ne censure pas les sorties arbitraires de l’application.

Journalisez les informations de démarrage qui peuvent être exposées sans risque et qui facilitent le diagnostic :

• Version de l’application ou commit.
• Nom de l’environnement.
• Port d’écoute.
• Noms des fonctionnalités activées, sans leurs valeurs secrètes.
• Classe de l’hôte de base de données, mais pas le mot de passe.
• Version des migrations.
• Readiness de l’endpoint de health.

Modèle de chronologie d’incident

Notez les éléments suivants :

1. ID du déploiement et commit source.
2. Horodatages de début et de fin du déploiement.
3. Première erreur causale de build ou d’exécution.
4. Résultat du contrôle de health.
5. Commande de récupération et ID du déploiement.
6. Période d’impact pour les utilisateurs.
7. Responsable du suivi.

Les données d’uptime ajoutent la disponibilité et le temps de réponse à la minute près :

dockup uptime production/api --hours 24 --json

Le résultat inclut le temps de réponse moyen et p95. Combinez-le avec les logs de build et d’exécution pour distinguer un incident de déploiement d’une régression de performance plus longue.

Consultez la référence de la CLI Dockup pour connaître les options de logs actuelles et les bonnes pratiques de sécurité pour journaliser les applications en toute sécurité.

Corréler les logs avec l’historique des déploiements

Une ligne n’est utile que si elle peut être associée à la bonne release. Stockez l’ID du déploiement, le hash du commit et l’heure de démarrage avec l’artefact de logs. Lorsque deux releases sont effectuées à peu d’intervalle, les horodatages seuls peuvent être trompeurs.

dockup deployments production/api -n 20 --json

L’historique des déploiements indique quelle source était active et quelle release a atteint un état final. Un agent ne doit pas attribuer une exception d’exécution au dernier commit tant que l’état du service ne confirme pas que ce commit a bien été déployé.

Éviter l’exposition de secrets par les logs

Une connexion en échec incite souvent les développeurs à afficher l’URL complète. Journalisez plutôt le protocole, l’hôte masqué, le nom de la base de données et la catégorie d’erreur. Pour les tokens, ne journalisez qu’une empreinte sûre générée avant le stockage, si l’organisation dispose d’une policy en ce sens.

Examinez les artefacts des builds en échec avant de les partager en dehors de l’équipe. La sortie des gestionnaires de packages et de Docker peut contenir des URLs de dépôts privés, des noms d’utilisateur de registre ou des arguments de commande, même lorsque Dockup masque correctement les secrets d’environnement stockés.

Les logs de build et d’exécution peuvent ainsi être utilisés en toute sécurité pour un diagnostic collaboratif.

Préserver un bundle minimal d’éléments probants

Pour chaque release en échec, enregistrez le JSON du résultat du déploiement, le build log, l’extrait d’exécution pertinent, l’état du service et l’ID du déploiement de récupération sélectionné. Ce bundle est suffisamment compact pour un usage courant et suffisamment complet pour permettre à un autre opérateur de poursuivre sans répéter des mutations incertaines.

Confirmer la correction, pas seulement le nouveau build

Une fois le déploiement corrigé terminé avec succès, répétez la requête ou la condition de démarrage à l’origine de l’échec et surveillez la sortie d’exécution pour vérifier que le problème ne réapparaît pas. Ne clôturez l’incident que lorsque le symptôme d’origine a disparu, que le contrôle de health réussit et que le comportement attendu en production est observé.

Boucler la résolution

Documentez la correction vérifiée.

Commencer par un déploiement vérifiable

Forcez l’échec d’un build de test, capturez son flux NDJSON et son code de sortie, puis vérifiez que votre runbook sélectionne le build log plutôt que le log d’exécution.

Commencez gratuitement sur app.dockup.ai. Le plan Free coûte 0 $ par mois, inclut un crédit initial de 10 $ et prend en charge un workspace, trois bases de données et trois déploiements.

FAQ

Quelle est la différence entre les build logs et les runtime logs de Dockup ?

Les build logs couvrent le clonage, l’installation des dépendances, la compilation et la création de l’image. Les runtime logs couvrent le conteneur applicatif ou les pods démarrés.

Comment suivre les build logs de Dockup en direct ?

Utilisez dockup logs avec --build et --follow, ou -f. Avec --json, la commande émet des lots NDJSON et se termine lorsque le déploiement atteint son état final.

Pourquoi le suivi du build renvoie-t-il un code différent de zéro ?

Il préserve le résultat du déploiement. Un build en échec doit faire échouer le shell appelant, le job CI ou la tâche de l’agent, plutôt que de donner l’impression que le flux de logs s’est terminé avec succès.

Que signifie restarted:true dans la sortie du suivi de l’exécution ?

Cela indique que le conteneur a redémarré ou que le buffer conservé a effectué une rotation ; Dockup a donc réémis l’instantané actuel au lieu de perdre silencieusement certaines lignes.

Les logs de l’application doivent-ils contenir des secrets d’environnement ?

Non. Dockup masque les lectures de configuration stockées, mais ne peut pas sécuriser les secrets arbitraires affichés par l’application. Les identifiants doivent être masqués au niveau de la journalisation de l’application.