Verbosité Ansible : -v / -vv / -vvv / -vvvv et callbacks profile_tasks

Quand un playbook échoue, votre premier réflexe doit être -v. Chaque cran de verbosité ouvre un nouveau niveau d'information : -v enrichit les résultats, -vv montre les arguments post-template Jinja2, -vvv révèle la commande SSH exacte, -vvvv expose les internals du plugin de connexion. Cette page distingue précisément quel niveau utiliser pour quel symptôme, et complète avec les callbacks profile_tasks + timer qui mesurent les performances sans toucher au playbook.

À la fin, vous saurez choisir le bon -v selon le bug, activer profile_tasks dans ansible.cfg, et éviter le piège classique : fuiter un secret en sortie verbose.

Ce que vous allez apprendre

• 4 niveaux de verbosité et le symptôme typique de chacun.
• Callback profile_tasks : mesurer les tâches lentes.
• callback_result_format = yaml pour des sorties multi-ligne lisibles.
• no_log: true : empêcher un secret de fuir en -v.
• ANSIBLE_KEEP_REMOTE_FILES=1 pour conserver les modules sur la cible.

Prérequis

• Avoir validé Premier playbook.
• Lab homelab avec un host atteignable.

Tableau de référence, quand utiliser quel niveau

Flag	Apporte	Symptôme typique
-v	Résultats des tâches enrichis	Vue d'ensemble, voir le détail des register:
-vv	Arguments réels passés au module (post-template)	Bug Jinja2, variable mal substituée
-vvv	Détails connexion SSH, chemin tmp module sur la cible	Connection failed, Permission denied, MODULE FAILURE
-vvvv	Internals plugin de connexion, ControlMaster, scp/sftp raw	Très rare, surtout pour debug ControlMaster ou SSH multiplexing

Glissez pour voir

Règle pratique : commencer par -v puis monter graduellement. -vvv couvre 90 % des cas de debug réseau/connexion.

Un cinquième cran existe, hors de cette échelle, et il ne se demande pas avec un -v de plus : la variable d'environnement ANSIBLE_DEBUG active le mode debug du moteur lui-même. Là où -vvvv détaille le plugin de connexion, ANSIBLE_DEBUG=1 déroule le pipeline interne d'ansible-core, plugin par plugin, jusqu'au découpage des tâches. La sortie est massive et sa documentation prévient d'ailleurs que « debug mode should not be used in production » :

ANSIBLE_DEBUG=1 ansible-playbook site.yml 2> debug.log

Réservez-la au cas où vous suspectez un bogue d'Ansible, pas une erreur de votre playbook. Le même réglage s'écrit debug = true dans la section [defaults] d'un ansible.cfg, forme à éviter : elle vous suivra sur toutes les exécutions suivantes.

-v : voir les register: et résultats

- name: Relever le nom d'hôte
  ansible.builtin.command: hostname
  register: out
  changed_when: false

- name: Afficher le résultat capturé
  ansible.builtin.debug:
    var: out

Sans -v :

TASK [debug] ***
ok: [db1.lab] => {
    "out": "<no_log: True>"
}

Avec -v :

TASK [debug] ***
ok: [db1.lab] =>
  out:
    changed: false
    cmd:
      - hostname
    rc: 0
    stdout: db1.lab
    stdout_lines:
      - db1.lab

🔍 Observation : -v est le niveau de dev quotidien. Affiche le contenu de chaque register: pour debug rapide.

-vv : voir les variables résolues post-Jinja2

Cas typique, bug de typo dans une variable :

vars:
  db_user: "appuser"
tasks:
  - debug: msg="User: {{ db_use }}"   # ← typo

Avec -vv :

TASK [debug] ***
task path: /home/.../lab.yml:7
fatal: [db1.lab]: FAILED! => {"msg": "...'db_use' is undefined..."}

Le path lab.yml:7 est ajouté → vous savez exactement quelle ligne corriger.

🔍 Observation : -vv ajoute le chemin fichier:ligne + les arguments réels post-template. Bug Jinja2 → toujours -vv minimum.

-vvv : voir la commande SSH exacte

Cas typique, connexion SSH refusée :

ansible-playbook lab.yml -vvv

Sortie :

ESTABLISH SSH CONNECTION FOR USER: ansible
SSH: EXEC ssh -C -o ControlMaster=auto -o ControlPersist=60s -o KbdInteractiveAuthentication=no \
  -o PreferredAuthentications=publickey -o PasswordAuthentication=no \
  -o User=ansible -o ConnectTimeout=10 db1.lab '/bin/sh -c '"'"'echo ~ansible && sleep 0'"'"''
ssh: Could not resolve hostname db1.lab: Name or service not known

🔍 Observation cruciale : -vvv montre la commande SSH exacte. Reproduisez-la avec ssh -vvv user@host pour bypass complètement Ansible et identifier la cause racine (DNS, clé SSH, sudoers).

-vvvv : internals du plugin de connexion

Très rarement utile, sauf debug ControlMaster ou scp/sftp :

ansible-playbook lab.yml -vvvv 2>&1 | head -50

Vous voyez le multiplexing SSH (1 socket réutilisée), le transport sftp/scp des modules, et les internals Python du plugin ssh. À utiliser uniquement après avoir épuisé -vvv.

Callback profile_tasks, mesurer les performances

Ajouter dans ansible.cfg :

[defaults]
callback_result_format = yaml
callbacks_enabled = ansible.posix.profile_tasks, ansible.posix.timer

[callback_profile_tasks]
task_output_limit = 10
sort_order = descending

Lancer :

ANSIBLE_CONFIG=ansible.cfg ansible-playbook lab.yml

Sortie en fin de run :

TASK execution time:
   1.    Install nginx ─────────── 12.45s
   2.    Configure firewalld ───── 3.20s
   3.    Setup mariadb ──────────── 2.10s
   …

Playbook run took 0 days, 0 hours, 1 minutes, 23 seconds

🔍 Observation : identifier les goulots d'étranglement sans modifier le code. Sur une fleet de production, c'est le premier outil pour décider quoi paralléliser ou optimiser.

callback_result_format = yaml pour sortie lisible

Sans :

ok: [db1.lab] => {"ansible_facts": {"my_data": [{"name": "alice"}, {"name": "bob"}]}}

Avec callback_result_format = yaml :

ok: [db1.lab] =>
  ansible_facts:
    my_data:
      - name: alice
      - name: bob

🔍 Observation : multi-ligne, indenté, lisible. À activer par défaut dans ansible.cfg projet.

⚠️ no_log: true, éviter de fuiter un secret en -v

Sans no_log: :

- ansible.builtin.shell: 'echo "Token: super_secret_token_42"'
  register: out
- debug: var=out.stdout

Lancer en -v :

ok: [db1.lab] =>
  out.stdout: "Token: super_secret_token_42"   ← LEAK

Le secret apparaît en clair. À ne jamais committer dans Git en CI.

Fix :

- ansible.builtin.shell: 'echo "Token: super_secret_token_42"'
  register: out
  no_log: true                                  # ← masque la sortie

`no_log` au niveau task, pas module

no_log: se pose au niveau de la task (alignement avec name:), jamais dans le module. Erreur classique :

- name: Déposer ...
  ansible.builtin.copy:
    no_log: true                # ← KO, c'est un argument du module copy (qui n'existe pas)
    src: ...

Bonne forme :

- name: Copier le secret
  ansible.builtin.copy:
    src: ...
    dest: ...
  no_log: true                  # ← OK, attribut de la task

ANSIBLE_KEEP_REMOTE_FILES=1, debug forensic

Quand un module échoue avec MODULE FAILURE, le module Python est transféré et exécuté sur la cible, puis supprimé. Pour le conserver et l'inspecter :

ANSIBLE_KEEP_REMOTE_FILES=1 ansible-playbook lab.yml -vvv

Sur la cible, le module reste dans ~/.ansible/tmp/ansible-tmp-*/ :

ssh ansible@target
cd ~/.ansible/tmp/ansible-tmp-*/
ls
# AnsiballZ_copy.py
python AnsiballZ_copy.py explode    # extrait le code module + args
python AnsiballZ_copy.py execute    # rejoue le module avec les mêmes args

🔍 Observation : reproduit exactement ce qu'Ansible a exécuté, avec accès au traceback Python complet. Indispensable pour debugger un module custom ou un bug obscur.

Mettre en pratique

Choisir le bon -v se décide au symptôme, et le seul moyen de l'ancrer est d'avoir les quatre sorties sous les yeux. Le lab reproduit un défaut par niveau : un register: invisible sans -v, une variable Jinja2 mal résolue que seul -vv situe par fichier et ligne, une connexion SSH refusée dont -vvv révèle la commande exacte à rejouer à la main. Un exercice mesure ensuite les tâches lentes avec profile_tasks, et un dernier fait constater ce qu'un no_log: manquant laisse remonter dans la sortie, ce que la vérification relève explicitement.

Lab pratique

Niveaux de verbosité et callback plugins

$ dsoxlab run troubleshooting-verbosite

Environnement : VM·Durée : ~40 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run troubleshooting-verbosite
dsoxlab check troubleshooting-verbosite

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• -v = dev quotidien (résultats register).
• -vv = bug Jinja2 (variables post-template + path fichier:ligne).
• -vvv = bug SSH/connexion (commande SSH exacte).
• -vvvv = internals plugin (rare, ControlMaster).
• profile_tasks + timer dans ansible.cfg pour mesurer.
• callback_result_format = yaml pour lisibilité.
• no_log: true systématique sur tâches manipulant un secret.
• ANSIBLE_KEEP_REMOTE_FILES=1 pour debug forensic d'un module.

Pour aller plus loin

• Idempotence et tuning : Ce que profile_tasks mesure ici sert directement à choisir les leviers de tuning.
• Découvrir une collection : Beaucoup d'échecs viennent d'un module introuvable : cette page explique le FQCN et l'endroit où vivent les collections.

×

📖 Voir la documentation →