michaelschiemer/docs/logging/docker-json-logging.md

Docker JSON Logging

Dokumentation für strukturierte JSON-Logs in Docker Containern für Log-Aggregation.

Übersicht

Das Framework verwendet automatisch strukturierte JSON-Logs in Production Docker-Umgebungen, um die Integration mit Log-Aggregatoren (Elasticsearch, Datadog, CloudWatch, etc.) zu ermöglichen.

Automatische Handler-Aktivierung

Development Mode (Standard)

PHP CLI in Docker → DockerJsonHandler (Pretty-Printed)
- Strukturiertes JSON mit Einrückung für bessere Lesbarkeit
- Alle Log-Aggregator-Felder enthalten
- Debugging-freundlich
- Lokale Docker-Entwicklung optimiert

Beispiel-Output:

{
    "timestamp": "2025-10-22T17:14:25+00:00",
    "@timestamp": "2025-10-22T17:14:25+00:00",
    "level": "INFO",
    "level_value": 200,
    "severity": 6,
    "channel": "app",
    "message": "Development test message",
    "environment": "development",
    "host": "3be143247465",
    "service": "dev-service",
    "context": {
        "user_id": 123,
        "action": "test"
    }
}

Production Mode

PHP CLI in Docker → DockerJsonHandler (Compact)
- Kompakte JSON-Ausgabe (eine Zeile pro Log)
- Alle Log-Aggregator-Felder enthalten
- Optimiert für maschinelle Verarbeitung und Log-Aggregatoren

Beispiel-Output:

{"timestamp":"2025-10-22T17:14:25+00:00","@timestamp":"2025-10-22T17:14:25+00:00","level":"INFO","level_value":200,"severity":6,"channel":"app","message":"Production log","environment":"production","host":"3be143247465","service":"api-service","context":{"user_id":123}}

Lokale Entwicklung (ohne Docker)

PHP CLI lokal → ConsoleHandler
- Farbige, interaktive Console-Ausgabe
- Optimiert für lokale Terminal-Sessions

Detection-Logik

// Automatische Docker-Erkennung
$inDocker = file_exists('/.dockerenv') || getenv('DOCKER_CONTAINER') === 'true';

if ($inDocker && $config->app->isProduction()) {
    // DockerJsonHandler für Production
} else {
    // ConsoleHandler für Development
}

JSON-Format

Jeder Log-Eintrag wird als eine Zeile JSON ausgegeben:

{
  "timestamp": "2025-10-22T19:08:43+02:00",
  "@timestamp": "2025-10-22T19:08:43+02:00",
  "level": "INFO",
  "level_value": 200,
  "severity": 6,
  "channel": "app",
  "message": "User logged in",
  "environment": "production",
  "host": "3be143247465",
  "service": "api-service",
  "context": {
    "user_id": 12345,
    "ip_address": "192.168.1.1"
  }
}

Standard-Felder

Feld	Typ	Beschreibung
timestamp	string	ISO 8601 Zeitstempel
@timestamp	string	Elasticsearch-konformer Zeitstempel
level	string	Log-Level Name (DEBUG, INFO, WARNING, ERROR, etc.)
level_value	int	Numerischer Log-Level Wert (100-600)
severity	int	RFC 5424 Severity Level (0-7)
channel	string|null	Log-Channel (app, security, database, etc.)
message	string	Log-Nachricht
environment	string	Deployment-Umgebung (production, staging, development)
host	string	Container/Server Hostname
service	string	Service-Name (aus APP_NAME env var)
context	object	Strukturierte Kontext-Daten
extra	object	Zusätzliche Metadaten (optional)

Docker Logs Verwendung

Basis-Kommandos

# Letzte 50 Logs anzeigen
docker logs php --tail 50

# Logs live verfolgen
docker logs php --follow

# Logs seit bestimmter Zeit
docker logs php --since 10m
docker logs php --since "2025-10-22T18:00:00"

Mit jq formatieren

# Pretty-print JSON
docker logs php 2>&1 | jq .

# Nur ERROR Logs
docker logs php 2>&1 | jq 'select(.level == "ERROR")'

# Nur CRITICAL und höher
docker logs php 2>&1 | jq 'select(.severity <= 2)'

# Als TSV (Tab-separated)
docker logs php 2>&1 | jq -r '[.timestamp, .level, .message] | @tsv'

# Gruppierung nach Level
docker logs php 2>&1 | jq -s 'group_by(.level) | map({level: .[0].level, count: length})'

# Fehler mit Context
docker logs php 2>&1 | jq 'select(.level == "ERROR") | {timestamp, message, context}'

Erweiterte Filterung

# Logs von bestimmtem Service
docker logs php 2>&1 | jq 'select(.service == "api-service")'

# Logs mit bestimmtem User
docker logs php 2>&1 | jq 'select(.context.user_id == 12345)'

# Performance-Logs (> 1 Sekunde)
docker logs php 2>&1 | jq 'select(.context.duration_ms > 1000)'

# Security-Channel Logs
docker logs php 2>&1 | jq 'select(.channel == "security")'

Log-Aggregator Integration

Elasticsearch

Die JSON-Logs sind direkt Elasticsearch-kompatibel:

{
  "@timestamp": "2025-10-22T19:08:43+02:00",  // Elasticsearch convention
  "severity": 6,                               // RFC 5424 numeric
  "environment": "production",
  "host": "3be143247465",
  "service": "api-service"
}

Filebeat Konfiguration:

filebeat.inputs:
- type: container
  paths:
    - '/var/lib/docker/containers/*/*.log'
  json.keys_under_root: true
  json.add_error_key: true
  processors:
    - add_docker_metadata: ~

Datadog

Docker Compose Konfiguration:

services:
  php:
    labels:
      - "com.datadoghq.ad.logs=[{\"source\":\"php\",\"service\":\"api-service\"}]"
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

CloudWatch

Fluent Bit Konfiguration:

[INPUT]
    Name              tail
    Path              /var/lib/docker/containers/*/*.log
    Parser            docker
    Tag               php.*

[OUTPUT]
    Name              cloudwatch_logs
    Match             php.*
    region            eu-central-1
    log_group_name    /aws/ecs/php-service
    log_stream_prefix app/

Environment-Konfiguration

Production Aktivierung

# .env
APP_ENV=production
APP_DEBUG=false
APP_NAME=api-service

Docker Environment Variable

Optional kann Docker-Detection explizit aktiviert werden:

# docker-compose.yml
services:
  php:
    environment:
      - DOCKER_CONTAINER=true

Testing

Manueller Test

# In Container ausführen
docker exec php php tests/debug/test-docker-json-logging.php

# Output prüfen
docker exec php php tests/debug/test-docker-json-logging.php 2>&1 | jq .

Unit Tests

# Logging Tests ausführen
./vendor/bin/pest tests/Unit/Framework/Logging/

Performance

Charakteristiken:

• Latenz: <1ms pro Log-Eintrag
• Overhead: ~5% gegenüber einfacher String-Ausgabe
• Throughput: >10,000 Logs/Sekunde
• Memory: Konstanter Speicherverbrauch (kein Buffering)

Optimierungen:

• Kompakte JSON-Ausgabe (keine Pretty-Print Formatierung)
• Direkte STDOUT-Ausgabe ohne Buffering
• Minimaler Serialisierungs-Overhead durch JsonSerializer

Troubleshooting

JSON-Logs erscheinen nicht in docker logs

Mögliche Ursachen:

1. APP_ENV ist nicht auf "production" gesetzt
2. Logs werden nicht in CLI-Mode generiert (nur Web-Requests)
3. Docker-Detection schlägt fehl

Lösung:

# Environment prüfen
docker exec php php -r "echo getenv('APP_ENV') . PHP_EOL;"

# Docker-Detection prüfen
docker exec php php -r "var_dump(file_exists('/.dockerenv'));"

# SAPI prüfen
docker exec php php -r "echo PHP_SAPI . PHP_EOL;"

JSON ist nicht valide

Ursache: Multi-line Ausgabe von anderen Komponenten

Lösung: Nur JSON-Zeilen filtern

docker logs php 2>&1 | grep '^{' | jq .

Zu viele Logs

Lösung: Log-Level erhöhen

# .env
LOG_LEVEL=WARNING  # Nur WARNING und höher

Best Practices

1. Strukturierte Kontext-Daten

✅ Good:

$logger->info('User action', LogContext::withData([
    'user_id' => $userId,
    'action' => 'login',
    'ip_address' => $ipAddress
]));

❌ Bad:

$logger->info("User $userId logged in from $ipAddress");

2. Konsistente Field-Names

Verwende snake_case für Context-Keys:

LogContext::withData([
    'user_id' => 123,        // ✅ snake_case
    'request_id' => 'abc',   // ✅ snake_case
    'userId' => 123          // ❌ camelCase
]);

3. Sensitive Daten vermeiden

Niemals Passwörter, Tokens oder PII in Logs:

// ❌ Schlecht
$logger->info('Login', ['password' => $password]);

// ✅ Gut
$logger->info('Login', ['user_id' => $userId]);

4. Richtige Log-Levels

• DEBUG: Detaillierte Debugging-Informationen
• INFO: Informative Ereignisse (User-Login, API-Calls)
• WARNING: Warnungen (Deprecated-API-Usage)
• ERROR: Fehler (Database-Errors, External-API-Failures)
• CRITICAL: Kritische Fehler (System-Ausfall)

Weiterführende Dokumentation

• Log-Aggregator-Felder
• Structured Logging Best Practices
• Performance Tuning