Logging¶

Dokumenttyp: Developer Playbook
Status: Draft v0.2
Stand: 2026-06-30
Prinzip: Allgemeine Anleitung mit Praxisbeispiel aus Immohai

Ziel¶

Dieses Dokument erklärt, was Logging ist, warum Logs für Webprojekte wichtig sind und wie typische Logs auf einem Ubuntu-Server mit Docker, Docker Compose und Nginx geprüft werden.

Logging bedeutet: Ereignisse, Warnungen und Fehler werden gespeichert, damit man später nachvollziehen kann, was passiert ist.

Kurz erklärt¶

Logs sind Protokolle.

Ein Log beantwortet Fragen wie:

Was ist passiert?
Wann ist es passiert?
Welcher Dienst war betroffen?
Welche Fehlermeldung wurde erzeugt?
Welche Anfrage kam beim Server an?

Beispiele:

Container startet nicht.
Nginx liefert 502 Bad Gateway.
HTTPS-Zertifikat kann nicht erneuert werden.
Eine Datei wird nicht gefunden.
Eine App gibt einen Fehler aus.

Warum Logging wichtig ist¶

Ohne Logs sieht man oft nur:

Die Website geht nicht.

Mit Logs kann man herausfinden:

Der Container läuft nicht.
Nginx findet den lokalen Port nicht.
Die App wirft einen Fehler.
Das Zertifikat ist abgelaufen.
Eine Datei fehlt.

Logs sind deshalb ein zentrales Werkzeug für Fehlersuche und Betrieb.

Monitoring und Logging¶

Monitoring und Logging sind nicht dasselbe.

Begriff	Bedeutung
Monitoring	Prüft, ob etwas funktioniert
Logging	Zeigt, was passiert ist

Einfach gesagt:

Monitoring sagt: Es gibt ein Problem.
Logging hilft zu verstehen: Warum gibt es das Problem?

Beispiel:

Monitoring:
https://immohai.ohaisoft.com antwortet nicht.

Logging:
Nginx-Log zeigt 502 Bad Gateway.
Docker-Log zeigt, dass der Container gestoppt ist.

Typische Log-Quellen¶

Bei einem kleinen Docker-/Nginx-Setup sind vor allem diese Log-Quellen wichtig:

Quelle	Zweck
Docker Logs	Ausgaben einzelner Container
Docker Compose Logs	Logs aller Dienste eines Projekts
Nginx Access Log	eingehende HTTP-/HTTPS-Anfragen
Nginx Error Log	Fehler von Nginx
Systemd Journal	Systemdienst-Logs, z. B. Nginx oder Docker
Certbot Logs	Zertifikats- und Renewal-Probleme
App Logs	anwendungsspezifische Fehler

Grundprinzip der Fehlersuche¶

Bei Problemen sollte von außen nach innen geprüft werden.

öffentliche URL
↓
Nginx
↓
lokaler Port
↓
Docker-Container
↓
App
↓
Dateien / Konfiguration

Dazu passen die Logs:

Nginx Error Log
↓
Docker Compose Logs
↓
App Logs

Docker-Logs anzeigen¶

Alle laufenden Container anzeigen:

docker ps

Logs eines Containers anzeigen:

docker logs <container-name>

Beispiel:

docker logs immohai-web
docker logs immohai-docs
docker logs developer-playbook-docs

Nur die letzten 100 Zeilen anzeigen:

docker logs immohai-web --tail=100

Logs live verfolgen:

docker logs immohai-web -f

Docker Compose Logs anzeigen¶

Im Projektordner:

docker compose logs

Logs eines bestimmten Dienstes:

docker compose logs <service>

Beispiel:

docker compose logs docs
docker compose logs web

Letzte 100 Zeilen:

docker compose logs docs --tail=100

Live verfolgen:

docker compose logs docs -f

Docker Compose Status prüfen¶

Logs allein reichen nicht immer.

Zusätzlich prüfen:

docker compose ps

Allgemeine Containerübersicht:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

Wenn ein Container nicht läuft, zuerst die Logs des Containers prüfen.

Nginx Access Log¶

Der Nginx Access Log zeigt eingehende Anfragen.

Pfad:

/var/log/nginx/access.log

Letzte 100 Zeilen anzeigen:

sudo tail -n 100 /var/log/nginx/access.log

Live verfolgen:

sudo tail -f /var/log/nginx/access.log

Typische Informationen:

IP-Adresse des anfragenden Clients
Zeitpunkt
HTTP-Methode
URL
HTTP-Statuscode
User-Agent

Beispielhafte Statuscodes:

Status	Bedeutung
`200`	erfolgreich
`301`	Weiterleitung
`403`	verboten
`404`	nicht gefunden
`500`	Serverfehler
`502`	Bad Gateway
`504`	Gateway Timeout

Nginx Error Log¶

Der Nginx Error Log ist bei Problemen meistens wichtiger als der Access Log.

Pfad:

/var/log/nginx/error.log

Letzte 100 Zeilen anzeigen:

sudo tail -n 100 /var/log/nginx/error.log

Live verfolgen:

sudo tail -f /var/log/nginx/error.log

Typische Fehler:

Fehler	Bedeutung
`connect() failed`	Nginx erreicht den lokalen Dienst nicht
`connection refused`	Zielport ist nicht offen
`host not found`	Zielhost oder DNS nicht gefunden
`permission denied`	Rechteproblem
`upstream timed out`	lokaler Dienst antwortet nicht rechtzeitig

Nginx Systemdienst-Logs¶

Zusätzlich zu den Nginx-Dateilogs kann das Systemd Journal geprüft werden.

Status:

sudo systemctl status nginx

Journal:

sudo journalctl -u nginx --no-pager -n 100

Live verfolgen:

sudo journalctl -u nginx -f

Docker Systemdienst-Logs¶

Docker selbst ist ein Systemdienst.

Status prüfen:

sudo systemctl status docker

Logs anzeigen:

sudo journalctl -u docker --no-pager -n 100

Live verfolgen:

sudo journalctl -u docker -f

Certbot Logs¶

Certbot-Probleme treten meist bei HTTPS-Einrichtung oder Zertifikatserneuerung auf.

Zertifikate anzeigen:

sudo certbot certificates

Renewal testen:

sudo certbot renew --dry-run

Certbot-Logs liegen typischerweise unter:

/var/log/letsencrypt/

Letzte Certbot-Logeinträge anzeigen:

sudo ls -la /var/log/letsencrypt
sudo tail -n 100 /var/log/letsencrypt/letsencrypt.log

Logs nach Neustart prüfen¶

Nach einem Neustart von Containern oder Diensten sollten die Logs kurz geprüft werden.

Docker Compose:

docker compose restart
docker compose ps
docker compose logs --tail=100

Nginx:

sudo nginx -t
sudo systemctl reload nginx
sudo journalctl -u nginx --no-pager -n 50

Certbot:

sudo certbot renew --dry-run

Praxisbeispiel Developer Playbook¶

Projektordner:

/home/fober/workspace/developer-playbook

Container:

developer-playbook-docs

Prüfen:

cd /home/fober/workspace/developer-playbook
docker compose ps
docker compose logs docs --tail=100
curl -I http://127.0.0.1:8100
curl -I https://playbook.ohaisoft.com

Wenn die öffentliche URL nicht funktioniert, zusätzlich prüfen:

sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --no-pager -n 100

Praxisbeispiel Immohai¶

Projektordner:

/home/fober/projects/immohai

Container:

immohai-web
immohai-docs

Prüfen:

cd /home/fober/projects/immohai
docker compose ps
docker compose logs web --tail=100
docker compose logs docs --tail=100
curl -I http://127.0.0.1:8200
curl -I http://127.0.0.1:8201
curl -I https://immohai.ohaisoft.com
curl -I https://docs.immohai.ohaisoft.com

Wenn die öffentliche URL nicht funktioniert:

sudo nginx -t
sudo tail -n 100 /var/log/nginx/error.log
sudo journalctl -u nginx --no-pager -n 100

Typischer Prüfablauf bei Fehlern¶

Wenn eine Website nicht erreichbar ist:

curl -I https://app.example.com

Wenn Fehler:

sudo nginx -t
sudo tail -n 100 /var/log/nginx/error.log

Dann lokalen Dienst prüfen:

curl -I http://127.0.0.1:<lokaler-port>

Dann Container prüfen:

docker ps
docker compose ps
docker compose logs --tail=100

Dann System prüfen:

df -h
free -h
sudo systemctl status docker
sudo systemctl status nginx

Typische Fehlerbilder¶

502 Bad Gateway¶

Bedeutung:

Nginx ist erreichbar, aber der lokale Dienst dahinter nicht.

Prüfen:

sudo tail -n 100 /var/log/nginx/error.log
curl -I http://127.0.0.1:<lokaler-port>
docker compose ps
docker compose logs --tail=100

Typische Ursachen:

Container läuft nicht.
proxy_pass zeigt auf falschen Port.
App im Container ist abgestürzt.
Port-Mapping ist falsch.

404 Not Found¶

Bedeutung:

Der Server antwortet, aber der angefragte Pfad oder Inhalt wurde nicht gefunden.

Prüfen:

sudo tail -n 100 /var/log/nginx/access.log
sudo tail -n 100 /var/log/nginx/error.log

Typische Ursachen:

falscher Pfad
falsche Nginx-Konfiguration
fehlende Datei
falsches Volume

403 Forbidden¶

Bedeutung:

Zugriff ist verboten.

Typische Ursachen:

Rechteproblem
Nginx darf Datei nicht lesen
falscher Root-Pfad
Verzeichnislisting nicht erlaubt

Certbot Renewal Fehler¶

Prüfen:

sudo certbot renew --dry-run
sudo tail -n 100 /var/log/letsencrypt/letsencrypt.log

Typische Ursachen:

Port 80 nicht erreichbar
DNS falsch
Nginx-Konfiguration fehlerhaft
Domain zeigt nicht auf den Server

Logs und Datenschutz¶

Logs können sensible Informationen enthalten.

Mögliche Inhalte:

IP-Adressen
URLs
Query-Parameter
User-Agent
Fehlermeldungen
technische Pfade

Deshalb:

Logs nicht unüberlegt veröffentlichen.
Logs nicht vollständig in öffentliche Dokumentation kopieren.
Keine Tokens oder Passwörter in URLs verwenden.
Bei Fehleranalysen sensible Daten anonymisieren.
Logs nicht in Git committen.

Logs und Speicherplatz¶

Logs können wachsen und Speicherplatz belegen.

Speicher prüfen:

df -h

Loggrößen grob prüfen:

sudo du -sh /var/log/*

Docker-Speicher prüfen:

docker system df

Nicht blind löschen.

Zuerst verstehen, welche Logs groß sind und warum.

Logrotation¶

Ubuntu verwendet normalerweise logrotate, um Logs zu rotieren und alte Logs zu komprimieren.

Prüfen:

ls -la /etc/logrotate.d/

Für Nginx gibt es typischerweise eine eigene Logrotate-Konfiguration.

cat /etc/logrotate.d/nginx

Für kleine Projekte reicht die Standardkonfiguration meist aus.

Einfache Logging-Routine¶

Empfehlung für kleine Projekte:

Anlass	Prüfung
nach Änderung an Docker Compose	`docker compose logs --tail=100`
nach Änderung an Nginx	`sudo nginx -t` und Nginx Error Log
nach Certbot	`sudo certbot renew --dry-run`
bei öffentlichem Fehler	Nginx Error Log und Docker Logs
wöchentlich	Speicherplatz und auffällige Logs prüfen

Best Practices¶

Bei Fehlern zuerst die passende Log-Ebene prüfen.
Nginx Error Log bei öffentlichen Fehlern zuerst lesen.
Docker Compose Logs bei Containerproblemen zuerst lesen.
Logs nicht vollständig in Dokumentation kopieren.
Sensible Daten in Logs anonymisieren.
Keine Logs mit Tokens oder Passwörtern committen.
Speicherplatz regelmäßig prüfen.
Logrotation nicht deaktivieren.
Bei 502 immer lokalen Port und Containerstatus prüfen.
Bei Certbot-Fehlern DNS, Port 80 und Nginx prüfen.

Typische Fehler¶

Fehler	Ursache	Lösung
keine Logs sichtbar	falscher Container oder Dienst	Containername prüfen
Logs zeigen nichts Neues	falscher Projektordner	in richtigen Compose-Ordner wechseln
502 Bad Gateway	lokaler Dienst nicht erreichbar	Nginx Error Log und Docker Logs prüfen
404 Not Found	falscher Pfad oder fehlende Datei	Access Log und Konfiguration prüfen
Certbot-Fehler	DNS oder HTTP-Challenge fehlerhaft	Let's-Encrypt-Log prüfen
Server voll	Logs oder Docker-Daten belegen Speicher	`df -h` und `docker system df` prüfen
sensible Daten in Logs	App schreibt Secrets aus	Logging-Konfiguration anpassen

Checkliste¶

[ ] Unterschied zwischen Monitoring und Logging verstanden
[ ] Docker Logs bekannt
[ ] Docker Compose Logs bekannt
[ ] Nginx Access Log bekannt
[ ] Nginx Error Log bekannt
[ ] Systemd Journal bekannt
[ ] Certbot Logs bekannt
[ ] typischer Prüfablauf bei Fehlern bekannt
[ ] 502-Fehlerbild verstanden
[ ] 404-Fehlerbild verstanden
[ ] Logs werden nicht in Git gespeichert
[ ] sensible Logdaten werden geschützt
[ ] Speicherplatz wird regelmäßig geprüft
[ ] einfache Logging-Routine festgelegt