michaelschiemer/deployment/ansible/callback_plugins/README.md

# Ansible Callback Plugin - default_with_clean_msg

**Stand:** 2025-11-07  
**Status:** Dokumentation des Custom Callback Plugins

---

## Übersicht

Das `default_with_clean_msg` Callback Plugin erweitert Ansible's Standard-Output mit verbesserter Formatierung für multiline `msg` Felder. Multiline Nachrichten werden als lesbare Blöcke mit Borders angezeigt, anstatt als escaped Newline-Zeichen.

**Datei:** `deployment/ansible/callback_plugins/default_with_clean_msg.py`

---

## Zweck

### Problem

Ansible's Standard Callback Plugin zeigt multiline `msg` Felder so an:
```
"msg": "Line 1\nLine 2\nLine 3"
```

Dies macht es schwierig, multiline Debug-Ausgaben zu lesen und zu kopieren.

### Lösung

Das Custom Plugin formatiert multiline Nachrichten als lesbare Blöcke:
```
================================================================================
Line 1
Line 2
Line 3
================================================================================
```

---

## Funktionalität

### Multiline Message Formatting

**Automatische Erkennung:**
- Nur Nachrichten mit mehr als einer Zeile werden formatiert
- Einzeilige Nachrichten bleiben unverändert

**Format:**
- Border oben und unten (aus `=` Zeichen)
- Maximale Border-Breite: 80 Zeichen
- Farbcodierung entsprechend Task-Status

### Method Overrides

Das Plugin überschreibt folgende Methoden des Default Callbacks:

- `v2_playbook_on_task_start` - Task Start
- `v2_runner_on_start` - Runner Start
- `v2_runner_on_ok` - Erfolgreiche Tasks
- `v2_runner_on_failed` - Fehlgeschlagene Tasks
- `v2_runner_on_skipped` - Übersprungene Tasks
- `v2_runner_on_unreachable` - Unerreichbare Hosts

**Grund:** Diese Methoden werden überschrieben, um Warnings zu vermeiden, die auftreten, wenn `get_option()` vor der vollständigen Initialisierung aufgerufen wird.

---

## Konfiguration

### ansible.cfg

**Datei:** `deployment/ansible/ansible.cfg`

```ini
[defaults]
stdout_callback = default_with_clean_msg
callback_plugins = ./callback_plugins
```

**Wichtig:**
- `stdout_callback` aktiviert das Plugin als Standard-Output
- `callback_plugins` gibt den Pfad zu den Plugin-Dateien an

### Plugin-Datei

**Pfad:** `deployment/ansible/callback_plugins/default_with_clean_msg.py`

**Struktur:**
- Erbt von `ansible.plugins.callback.default.CallbackModule`
- Überschreibt spezifische Methoden
- Fügt `_print_clean_msg()` Methode hinzu

---

## Verwendung

### Automatisch

Das Plugin wird automatisch verwendet, wenn `ansible.cfg` korrekt konfiguriert ist:

```bash
cd deployment/ansible
ansible-playbook -i inventory/production.yml playbooks/setup-infrastructure.yml
```

### Manuell

Falls das Plugin nicht automatisch geladen wird:

```bash
ansible-playbook \
  --callback-plugin ./callback_plugins \
  --stdout-callback default_with_clean_msg \
  -i inventory/production.yml \
  playbooks/setup-infrastructure.yml
```

---

## Beispiel-Ausgabe

### Vorher (Standard Callback)

```
ok: [server] => {
    "msg": "Container Status:\nNAME               IMAGE                             COMMAND                  SERVICE   CREATED              STATUS                            PORTS\nproduction-php-1   localhost:5000/framework:latest   \"/usr/local/bin/entr…\"   php       About a minute ago   Restarting (255) 13 seconds ago"
}
```

### Nachher (Custom Callback)

```
ok: [server] => {
================================================================================
Container Status:
NAME               IMAGE                             COMMAND                  SERVICE   CREATED              STATUS                            PORTS
production-php-1   localhost:5000/framework:latest   "/usr/local/bin/entr…"   php       About a minute ago   Restarting (255) 13 seconds ago
================================================================================
}
```

---

## Bekannte Limitationen

### Warnings bei Option Access

**Problem:** Frühere Versionen des Plugins riefen `get_option()` auf, bevor Ansible's Optionen vollständig initialisiert waren, was zu Warnings führte:

```
[WARNING]: Failure using method (v2_playbook_on_task_start) in callback plugin: 'display_skipped_hosts'
```

**Lösung:** Das Plugin überschreibt die problematischen Methoden direkt, ohne `get_option()` aufzurufen.

### Option-Checks

**Aktuell:** Das Plugin zeigt immer alle Hosts an (ok, changed, skipped), ohne Option-Checks.

**Grund:** Option-Checks würden `get_option()` erfordern, was Warnings verursacht.

**Workaround:** Falls Option-Checks benötigt werden, können sie nach vollständiger Initialisierung implementiert werden.

---

## Technische Details

### Inheritance

```python
from ansible.plugins.callback.default import CallbackModule as DefaultCallbackModule

class CallbackModule(DefaultCallbackModule):
    CALLBACK_NAME = 'default_with_clean_msg'
    
    def _print_clean_msg(self, result, color=C.COLOR_VERBOSE):
        # Custom formatting logic
```

**Vorteil:** Erbt alle Standard-Funktionalität und erweitert nur die Formatierung.

### Method Overrides

**Warum Overrides?**

Die Standard-Methoden rufen `get_option()` auf, um zu prüfen, ob bestimmte Hosts angezeigt werden sollen. Dies schlägt fehl, wenn Optionen noch nicht initialisiert sind.

**Lösung:** Direkte Implementierung ohne Option-Checks:

```python
def v2_runner_on_ok(self, result):
    # Eigene Implementierung ohne get_option()
    # ...
    self._print_clean_msg(result, color=color)
```

---

## Entwicklung

### Plugin testen

```bash
# Plugin-Verzeichnis
cd deployment/ansible/callback_plugins

# Syntax prüfen
python3 -m py_compile default_with_clean_msg.py

# Mit Ansible testen
cd ..
ansible-playbook -i inventory/production.yml playbooks/check-container-status.yml
```

### Plugin erweitern

**Neue Formatierung hinzufügen:**

1. `_print_clean_msg()` Methode erweitern
2. Neue Formatierungslogik implementieren
3. Tests durchführen

**Beispiel:**
```python
def _print_clean_msg(self, result, color=C.COLOR_VERBOSE):
    msg_body = result._result.get('msg')
    if isinstance(msg_body, str) and msg_body.strip():
        # Custom formatting logic here
        # ...
```

---

## Troubleshooting

### Plugin wird nicht geladen

**Problem:** Plugin wird nicht verwendet, Standard-Output bleibt

**Lösung:**
1. `ansible.cfg` prüfen:
   ```ini
   stdout_callback = default_with_clean_msg
   callback_plugins = ./callback_plugins
   ```

2. Plugin-Datei prüfen:
   ```bash
   ls -la deployment/ansible/callback_plugins/default_with_clean_msg.py
   ```

3. Syntax prüfen:
   ```bash
   python3 -m py_compile default_with_clean_msg.py
   ```

### Warnings erscheinen

**Problem:** Warnings wie `'display_skipped_hosts'`

**Lösung:** Plugin-Version prüfen - sollte Method Overrides ohne `get_option()` verwenden.

**Aktueller Stand:** Plugin verwendet direkte Overrides ohne Option-Checks.

---

## Referenz

- [Ansible Callback Plugins Documentation](https://docs.ansible.com/ansible/latest/plugins/callback.html)
- [Ansible Callback Development Guide](https://docs.ansible.com/ansible/latest/dev_guide/developing_plugins.html#callback-plugins)
- [Initial Deployment Troubleshooting](../docs/troubleshooting/initial-deployment-issues.md) - Problem 8: Ansible Debug Messages

---

## Changelog

### 2025-11-07
- Initial Version erstellt
- Multiline Message Formatting implementiert
- Method Overrides ohne Option-Checks
- Warnings behoben