//Cloudogu EcoSystem Docs

Der EcoSystem Debug-Modus

Der Debug-Modus bringt das System in einen Zustand, in dem die maximale Ausprägung an Logs produziert wird. Dadurch können im System auftretende Fehler bestmöglich nachvollzogen werden.

Aktivierung

Die Aktivierung des Debug-Modus erfolgt über den Befehl cesapp debug-mode enable. Nach der Ausführung muss die Aktivierung durch die Eingabe von ybestätigt werden.

Nach der Aktivierung des Debug-Modus werden sämtliche Log-Dateien rotiert. Das bedeutet, deren Inhalt als Archiv-Dateien neben den eigentlichen Log-Dateien abgelegt werden. Die Log-Dateien werden anschließend geleert.

Anschließend werden die Log-Level aller Dogus auf die höchste Stufe (DEBUG) gesetzt. Vorher gegebenenfalls konfigurierte Log-Level werden im etcd gesichert, um später wiederhergestellt werden zu können.

Damit die Konfiguration Anwendung findet, werden dann alle Dogus neu gestartet.

Wenn der Debug-Modus aktiviert ist, können Sie einen aufgetretenen Fehler reproduzieren. Alle für das Verständnis des Problems relevanten Informationen sollten dann in den Log-Dateien zu finden sein.

Solange der Debug-Modus aktiviert ist, wird bei jedem Cesapp-Befehl eine Warnung ausgegeben, die daran erinnert, dass der Debug-Modus aktiviert ist. Diese soll nur dazu dienen, dass man sich bei jeder Benutzung eines Cesapp-Befehls im Klaren sein soll, dass der Debug-Modus noch aktiv ist und kann ansonsten ignoriert werden.

Warnung: Das System sollte während der Aktivierung nach Möglichkeit nicht produktiv genutzt werden, da ansonsten die Log-Dateien ungewöhnlich groß werden und außerdem dadurch die Nachvollziehbarkeit von Fehlern verschlechtert wird.

Deaktivierung

Die Deaktivierung des Debug-Modus erfolgt über den Befehl cesapp debug-mode disable. Nach der Ausführung muss die Deaktivierung durch die Eingabe von ybestätigt werden.

Nach der Deaktivierung des Debug-Modus werden die Log-Level auf den Wert zurückgesetzt, den sie vor der Aktivierung hatten. Die Logs werden erneut rotiert und alle Dogus ein weiteres Mal neu gestartet. Das System kann nun wieder normal genutzt werden.

Statusabfrage

Die Statusabfrage des Debug-Modus erfolgt über den Befehl cesapp debug-mode status. Dabei bekommt man entweder die Ausgabe enabled oder disabled, je nachdem, ob der Debug-Modus aktiviert oder deaktiviert ist. Falls der Debug-Modus aktiviert ist, wird zusätzlich noch eine Warnung darüber ausgegeben. Sollte der Status-Befehl zum Beispiel in einem Script ausgeführt werden und die Warnung darf nicht auftauchen, kann der Befehl mit cesapp --log-level error debug-mode status ausgeführt werden.

Support-Archiv

Das Support-Archiv kann nur erstellt werden, wenn der Debug-Modus aktiviert ist. Dies erfolgt über den Befehl cesapp debug-mode archive create. So wird das Archiv zusammengestellt und als /var/log/docker/debug-archive.zip abgelegt. Das Support-Archiv enthält alle Dateien, die für Supportfälle relevant sind. Die folgenden Dinge sind enthalten:

• Installierte Dogus, Container Status und größe der Volumes
• Alle Umgebungsvariablen

• Status von wichtigen Prozessen

  • Backup-Watcher
  • ETCD
  • Cesappd
  • Alle laufenden Prozesse
  • Status der Firewall

• Informationen über das System

  • Betriebssystem & Version
  • Kernel
  • CPU
  • Partitionen & Auslastung
  • RAM
  • SWAP
  • Installierte Apt-Pakete
• Eine Liste aller enthaltenen Dateien in allen Volumes der Dogus
• Implementierung ausstehend: Logs aller dogus und aller wichtigen Systemprogramme

• Implementierung ausstehend: Kopie des ETCD

  • Als Baumstruktur: Nur mit Keys
  • Als .json-Objekt: Keys und Values
  • Verschlüsselte Keys sind verschlüsselt im Archiv enthalten und damit für niemanden rekonstruierbar
  • Einzelne Keys oder Ordner sind durch eine etcd-Konfiguration oder einen command-flag automatisch ausblendbar

Konfiguration der etcd-keys

Um Standardwerte zu definieren, welche Registry-Keys im Archiv zensiert werden sollen. Dafür müssen registry-keys wie folgt angelegt werden: Ein key im Format config/_global/debug/excluded_etcd_keys/<frei-waehlbarer-name>/<key-oder-dir-zum-Zensieren> Beispiel: etcdctl set config/_global/debug/excluded_etcd_keys/globale_konfiguration config/_global Die globale Konfiguration wird dann in der Json-Datei im Archiv so angezeigt:

{ 
   "config" : {
      "_global": "***"
   }
}

Die zusätzlich im Archiv abgelegte Baumstruktur der Registry bleibt dabei unberührt und zeigt alle vorhandenen keys und values an.

Wird dem Befehl der Flag --exclude-etcd-keys mitgegeben, wird die Konfiguration im etcd ignoriert.

Flags

Der Befehl zum Erstellen des Archivs kann über einige Flags konfiguriert werden.

--fail-fast

Normalerweise bricht die Erstellung eines Archivs nicht ab, wenn ein Fehler auftritt. Das sorgt dafür, dass im Fehlerfall zumindest ein Teil des Archivs erstellt wird. Sollte aber gewünscht sein, dass der Befehl in diesem Fall mit einer Fehlermeldung abgebrochen wird, kann der Flag --fail-fast mitgegeben werden.

--path

Hier kann ein alternativer Pfad für das Archiv angegeben werden. Es sollte immer ein vollständiger Pfad inklusive Dateiname und Dateiendung sein. Sollte ein unvollständiger Pfad angegeben werden (z.B. /path/to/myfile) wird dieser wie folgt vervollständigt: /path/to/myfile/debug-archive.zip. Beispiel für eine korrekte Verwendung des Flags: cesapp debug-mode archive --path /path/to/archive.zip create.

--exclude-etcd-keys

Über diesen Flag kann eine Liste aus Registry-Keys (sowohl einzelne Keys als auch ganze Ordner) definiert werden, deren Werte in dem Support-Archiv zensiert werden sollen. Die Keys sind weiterhin sichtbar, deren Werte werden aber mit *** angegeben. Diesem Flag wird eine Liste aus Kommaseparierten Werten übergeben, z.B. --exclude-etcd-keys dogu,config/_global.

--exclude und --only

Diese Flags dienen dazu, zu filtern, welche Inhalte in das Support-Archiv sollen. Es kann bei einem Befehl entweder --exclude oder --only verwendet werden, niemals beide. Der Wert des Flags wird als kommaseparierte Liste angegeben. Mit --exclude können bestimmte Teile aus dem Archiv ausgeschlossen werden. Mit --only werden alle Teile aus dem Archiv ausgeschlossen, die nicht aufgezählt wurden. Beispiele: cesapp debug-mode archive --exclude=log,etcd create cesapp debug-mode archive --only=system,env create

Folgende Werte sind für --exclude und --only gültig:

system

Dieses Paket enthält Informationen über das Betriebssystem und dessen Version, verwendete Hardware, Partitionen und installierte Apt-Pakete.

env

Dieses Paket enthält alle Umgebungsvariablen.

dogu

Enthält eine Liste mit allen installierten Dogus und deren Status.

process

Enthält Informationen über alle laufenden Services und Prozesse.

volume

Enthält eine Liste mit allen Dateien aller Volumes aller Dogus.

log

Enthält alle wichtigen Log-Dateien.

etcd

Enthält den gesamten Inhalt des etcd (verschlüsselte Keys sind nicht sichtbar).

Manpage

NAME:
   cesapp debug-mode - cesapp debug-mode <enable | disable | status | archive>

USAGE:
   cesapp debug-mode command [command options] [arguments...]

COMMANDS:
   archive  cesapp debug-mode archive <flags> create
   help, h  Shows a list of commands or help for one command

OPTIONS:
   --help, -h     show help (default: false)
   --version, -v  print the version (default: false)