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

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.

Symptôme	Niveau	Ce que ça révèle
Variable templatée incorrecte	`-v`	Args du module
Variable Jinja qui s’évalue mal	`-vv`	Args post-template (valeurs résolues)
Bug SSH (`Permission denied`, timeout)	`-vvv`	Commande SSH complète
Bug plugin de connexion ou de modules custom	`-vvvv`	Internals plugin

# Bug standard : commencer à -vvv
ansible-playbook site.yml -vvv

# Activer profile_tasks (callback) pour identifier les tâches lentes
# Dans ansible.cfg :
# [defaults]
# callbacks_enabled = ansible.posix.profile_tasks
# stdout_callback = yaml          # sortie multi-ligne lisible

# Conserver les modules transférés sur la cible (debug forensic)
ANSIBLE_KEEP_REMOTE_FILES=1 ansible-playbook site.yml -vvv

# Voir où se trouve un module Python sur la cible (depuis cible) :
# /tmp/ansible-tmp-*/AnsiballZ_<module>.py

Sécurité non négociable :

no_log: true sur toute tâche manipulant un secret — sinon -v leak la valeur en clair (token, password, clé). Le secret atterrit dans la sortie console, ELK, Splunk.
NE PAS partager une sortie -vvvv sur un canal public (Slack, GitHub issue) sans avoir d’abord scanné password|token|secret|key — ces sorties sont denses, un secret peut s’y cacher.
-vvv est le réflexe par défaut, pas -vvvv — -vvvv est rarement utile et noie le vrai message.
profile_tasks en CI/CD sur les playbooks longs — révèle les goulets d’étranglement à optimiser sans modifier le code.

Ce que vous allez apprendre

4 niveaux de verbosité et le symptôme typique de chacun.
Callback profile_tasks : mesurer les tâches lentes.
stdout_callback = 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

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

`-v` : voir les `register:` et résultats

- ansible.builtin.command: hostname
  register: out
- 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]
stdout_callback = 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.

`stdout_callback = yaml` pour sortie lisible

Sans :

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

Avec stdout_callback = 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: se pose au niveau de la task (alignement avec name:), jamais dans le module. Erreur classique :

- 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.

Lab pratique

Le lab troubleshooting/verbosite (labs/troubleshooting/verbosite/) reproduit les 4 niveaux de verbosité avec un exercice par niveau, plus un challenge profile_tasks à 3 tâches mesurées.

À 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.
stdout_callback = 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.

Prochaines étapes

Débogueur Ansible interactif REPL au runtime, fix variable sans relancer.

Idempotence et tuning performances creates: / regexp: / changed_when:, pipelining + forks + ControlPersist.

Lab 89 sur GitHub 4 niveaux de verbosité + challenge profile_tasks 3 tâches.

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

Ce que vous allez apprendre

Prérequis

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

-v : voir les register: et résultats

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

-vvv : voir la commande SSH exacte

-vvvv : internals du plugin de connexion

Callback profile_tasks — mesurer les performances

stdout_callback = yaml pour sortie lisible

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

ANSIBLE_KEEP_REMOTE_FILES=1 — debug forensic