//Cloudogu EcoSystem Docs

The EcoSystem Debug Mode

The debug mode brings the system into a state in which the maximum number of logs is of logs is produced. Thus errors occurring in the system can be retraced in the best way possible.

Activation

The debug mode is activated by the command cesapp debug-mode enable. After execution, the activation must be confirmed by entering y.

After debug mode activation all log files are rotated. This means that their contents are stored as archive files next to the actual log files are stored. The log files are then emptied.

Afterwards the log levels of all Dogus are set to the highest level (DEBUG). are set. Previously configured log levels, if any, are saved in etcd, to be able to be restored later.

To apply the configuration, all Dogus are then restarted.

If the debug mode is activated, you can reproduce an error that has occurred. reproduce it. All information relevant for understanding the problem should then be found in the log files.

As long as the debug mode is activated, a warning is issued with every Cesapp command. is issued to remind you that debug mode is enabled. This is just to make sure that every time you use a Cesapp command you should be aware that debug mode is still that the debug mode is still active and can be ignored otherwise. ignored.

Warning: If possible, the system should not be used productively during productive use during the activation, otherwise the log files will become unusually large and in addition thereby the comprehensibility of errors is worsened.

Deactivation

The deactivation of the debug mode is done by the command cesapp debug-mode disable. After execution, the deactivation must be confirmed by entering y.

After debug mode deactivation, the log levels are reset to the value they had before the activation. The logs are rotated again and all Dogus are are restarted a second time. The system can now be used normally again.

Status query

The status query of the debug mode is done with the command cesapp debug-mode status. You get either the output enabled or disabled, depending on whether the debug mode is mode is enabled or disabled. If the debug mode is enabled, an additional warning about it is output. If the status command should be executed in a script, for example, and the warning may not appear, the command can be executed with cesapp --log-level error debug-mode status. can be executed.

Support archive

The debug archive can be created only if the debug mode is enabled. This is done with the command cesapp debug-mode archive create. This way the archive is collected and stored as /var/log/docker/debug-archive/debug-archive.zip. file. The debug archive contains all files relevant to support cases. The following things are included:

  • Installed dogus, container status and size of volumes.
  • All environment variables
  • Status of important processes

    • Backup watcher
    • ETCD
    • Cesappd
    • All running processes
    • Status of the firewall
  • Information about the system

    • Operating system & version
    • Kernel
    • CPU
    • Partitions & Utilization
    • RAM
    • SWAP
    • Installed Apt packages
  • A list of all contained files in all volumes of the dogus.
  • Implementation pending: logs of all dogus and all important system programs
  • Implementation pending: Copy of the ETCD

    • As tree structure: Only with keys
    • As .json object: Keys and Values
    • Encrypted keys are contained encrypted in the archive and thus for nobody reconstructable
    • Single keys or folders can be hidden automatically by an etcd configuration or a command-flag.

Configuration of etcd-keys

To define default values of which registry keys should be censored in the archive. For this purpose, registry keys must be created as follows: A key in the format config/_global/debug/excluded_etcd_keys/<free-choice-name>/<key-or-dir-to-censor>. Example: etcdctl set config/_global/debug/excluded_etcd_keys/global_configuration config/_global. The global configuration is then displayed in the json file in the archive like this:

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

The additional tree structure of the registry stored in the archive remains untouched and shows all existing keys and values.

Flags

The archive creation command can be configured using some flags.

--fail-fast

Normally the creation of an archive does not abort if an error occurs. This ensures that at least part of the archive is created in case of an error. However, if you want the command to abort with an error message in this case, you can use the flag --fail-fast can be specified.

--path

Here an alternative path for the archive can be specified. It should always be a complete path including file name and file extension. If an incomplete path is given (e.g. /path/to/myfile) it will be completed as follows: path/to/myfile. will be completed as follows: /path/to/myfile/debug-archive.zip. Example of correct usage of the flag: cesapp debug-mode archive --path /path/to/archive.zip create.

--exclude-etcd-keys

This flag can be used to define a list of registry keys (both individual keys and entire folders), whose values should be censored in the debug archive. The keys are still visible, but their values are specified with ***. This flag is passed a list of comma separated values, e.g. --exclude-etcd-keys dogu,config/_global.

--exclude and --only

These flags are used to filter what content should go into the debug archive. Either --exclude or --only can be used with a command, never both. The value of the flag is given as a comma separated list. With --exclude certain parts can be excluded from the archive. With --only all parts are excluded from the archive that were not enumerated. Examples: cesapp debug-mode archive --exclude=log,etcd create. cesapp debug-mode archive --only=system,env create

The following values are valid for --exclude and --only:

system

This package contains information about the operating system and its version, used hardware, partitions and installed apt packages.

env

This package contains all environment variables.

dogu

Contains a list of all installed dogus and their status.

process

Contains information about all running services and processes.

volume

Contains a list with all files of all volumes of all dogus.

log

Contains all important log files.

etcd

Contains the entire content of etcd (encrypted keys are not visible).

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)